; $Id: readme.txt,v 1.20 2000/05/28 13:46:59 umoeller Exp $

WarpIN 0.9.3 README
(W) Ulrich Mller, Sept 9, 1999
Last updated June 5, 2000, Ulrich Mller


0. CONTENTS OF THIS FILE
========================

    1. LICENSE, COPYRIGHT, DISCLAIMER
    2. INTRODUCTION
    3. COMPILING
    4. SOURCE CODE NOTES
    5. SOURCE CODE DOCUMENTATION
    6. RELEASE HISTORY
    7. TO DO
    8. FILE DESCRIPTIONS
    9. TESTING WARPIN
    10. CONTACT


1. LICENSE, COPYRIGHT, DISCLAIMER
=================================

    Copyright (C) 1998-2000 Jens Bckman,
                            Cornelis Bockemhl,
                            Ulrich Mller,
                            Teemu Ahola.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as contained in
    the file COPYING in this distribution.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


2. INTRODUCTION
===============

    Welcome to WarpIN 0.9.3.

    WarpIN uses a Linux-like version numbering. That is, version
    numbers always have three parts, specifying major, minor, and
    maintenance releases.

    Versions with odd minor numbers are developer releases.

    So this version is a developer release too! Do not expect
    everything to be bomb-proof with this version. Instead,
    expect this version to have some bugs still.

    As soon as we consider something ready for public use, we'll
    release a "stable" version with an even minor number. So when
    this version is working OK one day, we'll release V1.0.0.

    This version has been released to allow building test archives
    already. Since creating install scripts is probably the most
    time-consuming part, this is something you might want to try
    already now. We are not planning to make any further changes
    to either the compression routines or the script language
    which are not fully backward-compatible (famous last words).

    Still, not everything works yet (see section 7 below).


3. COMPILING
============

    This section describes how to compile WarpIN from the Netlabs
    CVS archive. If you're reading this file as part of a binary
    release (that is, if you already have WARPIN.EXE), you may skip
    this section. Instead, read the WarpIN INF files and check them
    against section 7 below to find out what doesn't work yet.

    Source code is no longer included with the binary releases.
    Instead, download a sources package or check out the sources
    from the Netlabs CVS server.

    To check out the most current WarpIN sources from the command
    line, use:
        SET CVSROOT=:pserver:guest@www.netlabs.org:d:/netlabs.src/warpin
        SET USER = guest

    Then do a "cvs checkout".

    Alternatively, use the Netlabs Open Source Archive Client (NOSAC).
    See http://www.netlabs.org/nosa for details.

    What you need:

    a)  IBM NMAKE is our make utility. See "Source code notes" below.

        NMAKE comes with the IBM compilers and is now also publicly
        available with the IBM Device Driver Development Kit (DDK),
        available from "http://service.boulder.ibm.com/ddk/".
        It's behind the "Build tools ZIP file" button (tools.zip).
        You will need to register first, but other than that, the
        thing is free.

    b)  One of EMX/GCC or VAC++ 3.08. Jens uses EMX to develop the
        back-end, I use VAC++ 3.08 for the whole thing, but
        from time to time I check whether the frontend compiles
        with EMX too. If it doesn't, please don't complain,
        because EMX compatibility is not my main goal here.

        The front end currently does NOT fully compile with EMX
        or PGCC. The compiler crashes with some strange error
        message I don't understand. If anyone can help me on this,
        please drop me a note.

    c)  If you use VAC++ 3.08, you need an implementation of the
        C++ Standard Template Library (STL). This is already
        included with EMX.

        I am using STLport, an enhanced version of the original
        STL by Hewlett Packard. Download one from www.stlport.org,
        which has different versions.

        I strongly recommend using 3.0.1, which still works with
        VAC++ 3.0. With the newest version (I have tested 3.2.1)
        you get lots of linker errors from ILINK which I haven't
        been able to fix yet. Apparently, the newer STL versions
        use the craziest template features, which VAC doesn't like.

        I have uploaded STLport 3.0.1 to
        ftp.netlabs.org/pub/tools/wps/xworkplace/ for your
        convenience.

        Note: Starting with V0.9.3, you must set the STL_DIR
        environment variable to point to your STL main directory
        to compile (VAC only).

    d)  Only if you want to produce the INF files from the 001\
        subdirectory, you will need:

        aa)  HTML2IPF, a beautiful HTML-to-IPF converter written
             by Andrew Pawel Zabolotny. I have included this in
             the 001\ directory. Documentation is available in
             the XWorkplace source tree (on Netlabs CVS too).

        bb)  You absolutely need IBM's INF compiler, IPFC.EXE.
             This used to be included only with the OS/2 Developer
             Toolkits, but is now also included for free with the
             DDK also (together with NMAKE, see above).


4. SOURCE CODE NOTES
====================

    If you have a binary distribution, you can skip this section.
    This section is for developers and anyone interested in becoming
    one.

    With 0.9.0, the source code tree was completely reorganized to
    follow the standard conventions used under Linux and with most
    other Netlabs projects. That is, we have a "src" tree which has
    all the .C/.CPP source files, and an "include" tree with
    corresponding subdirectories for the headers. Finally, the makefiles
    create a "bin" directory if it doesn't exist already where only
    temporary .OBJ/.LIB files will be written into. All those files
    from all src/ subdirectories will end up in bin/.

    You can delete the entire bin/ directory at any time to have a
    complete rebuild of WarpIN.

    I have developed a new makefile system with "smart" makefiles.
    All makefiles are written for IBM NMAKE (see previous section).

    Please use NMAKE from now on, because GNU make has some really
    strange limitations. For example, it cannot handle makefiles
    which use spaces instead of tabs, which is a really dull
    behavior. Also, I have spent quite some time on these new
    makefiles, and these are probably quite difficult to port.

    To build WARPIN.EXE and WIC.EXE in the main directory, call
    NMAKE on the main makefile (just execute "NMAKE" in the main
    directory). See the main "makefile" for details and other
    possible targets.

    Now, the "smartness" of the makefiles (other than makefiles
    being smart in the first place) is that if any makefile in
    any subdirectory is called directly (instead of being called
    from the makefile in the main directory), it will automatically
    recurse into the main makefile. This allows you to run NMAKE in
    any subdirectory and still get a complete build of everything,
    should this be necessary. This comes in real handy with many
    programming editors which don't have real project handling, but
    only operate on the directory of the current source file.

    If you don't use IBM VAC++, edit "setup.in" in the main directory.
    This file is included from all subdirectories of "src\" to
    define compiler options. So by redefining the "CC" and "LINK"
    macros, you can adjust the whole compilation process to your
    favorite compiler. EMX/GCC is already preconfigured and can
    be enabled by setting the respective flag on top of "setup.in".


5. SOURCE CODE DOCUMENTATION
============================

    If you have a binary distribution, you can skip this section.
    This section is for developers and those interested in becoming
    one.

    In the "tools\xdoc" directory, you will find my "xdoc" utility.
    You must compile first before you can use this.

    Using xdoc, you can automatically create source code documentation
    for WarpIN (the frontend, that is). This might be of great help
    if you don't want to always have to search all code files for
    a certain class.

    After compiling, use "createdoc.cmd" in the main directory to
    have xdoc create source code documentation for the frontend.
    After that, open "HTML\index.html" and go for the source files
    index. In frontend\warpin.cpp, you will find an introduction.

    Of course, you can also read the source files directly, if you
    prefer that.


6. RELEASE HISTORY
==================

    V0.9.3
    ------

    --  Completely removed Add/Remove mode. We now always
        enter "Full install" mode.

    --  Removed DosQuerySysState calls which apparently
        caused crashes on some systems. Using 16-bit
        DosQProcStat instead.

    --  Added REXX support documentation to WPI_PROG.INF.

    --  Added FORMAT=HTML and FORMAT=PLAIN to <README>.
        Limited HTML support introduced.

    --  XTextView control had serious problems with scroll bars.
        Fixed. Also added lots more features.

    --  Added more package dependency checks.

    --  Macros in target paths never worked, especially "?:\"
        for the boot drive. Fixed. Added package references
        to macro resolution.

    --  <PCK CREATEOBJECT> didn't work with REPLACE. Fixed.

    --  <PCK EXECUTE> didn't work right. Fixed.

    --  Added <PCK EXTERNAL REQUIRED>.

    --  Fixed a few memory leaks in BSString class.

    --  Added more error checking in various places.

    --  VARPROMPT window crashed if nothing was entered. Fixed.

    --  Tabs in scrips caused errors. Fixed.

    --  Added readme shadow to WarpIN install objects.

    --  Checkboxes weren't always set right on Configure page. Fixed.

    --  Exception handlers caused exceptions themselves sometimes
        with certain strange stack frames. Fixed.

    --  SYM file parsing only worked on Warp 4. Fixed, I hope.

    --  Switched helpers to create helpers.lib now for easier linking.


    V0.9.2
    ------

    Mostly bugfixes, plus REXX support, plus new tags.

    --  REXX support (C) Cornelis Bockemhl. No documentation
        yet, as this is fully experimental and subject to
        major change. ;-)

    --  Made NEXTBUTTON optional.

    --  VARPROMPT implemented.

    --  External packages implemented.

    --  Added more error checking to backend to solve hung
        WarpIN with broken packages.

    --  Script codepage support added.

    --  Macro resolution in TARGETPATH finally works with
        environment variables too.

    --  Free space on drive wasn't displayed right if > 4GB.
        Fixed.

    --  Finally displaying package descriptions as tooltips.

    --  Renamed database file to "datbas_X.ini" with X being
        the boot drive so that WarpIN can be used from several
        OS/2 boot partitions independently. The old database
        is automatically converted.

    --  Database allowed several packages to be selected at
        once, which confused the rest of the GUI. Fixed; now
        only one package can be selected.

    --  Added database "configuration" view.

    --  Sped up database display.

    --  Added tab key support to database windows.

    --  Added more configuration descriptions to database;
        now using virtual methods, which works much better.

    --  "Undo config" wasn't checked right when deinstalling
        multiple packages at once. Fixed.

    --  "Exit" menu item didn't work. Fixed.

    --  Fixed memory leaks.

    --  Fixed exception handlers which weren't unwinding
        call stacks right.

    --  Exception handlers now also parse SYM files in
        ?:\OS2\PDPSI\PMDF on Warp 4.

    --  Changed linking to non-optimizing in order to have
        exception handlers parse SYM files right.


    V0.9.1
    ------

    This is both a "lotsa-new-features" and a bugfix release.

    --  WicPM added.

    --  Package dependencies are now implemented. Dependencies
        are stored in the database according to the REQUIRES
        attributes of the PCK tag and the database performs
        checks before deinstalling. Also, before installing,
        we check whether dependencies are met.

        This has been tested to a certain extent, but not
        extremely extensive. I'd be grateful for more feedback.

    --  CONFIGSYS attribute UNIQUE flag support improved.

    --  EXECUTE attribute is now supported.

    --  CLEARPROFILE and WRITEPROFILE attributes now supported
        (although deinstallation doesn't work yet).

    --  Six-part package IDs (with three-part version numbers)
        are working now.

    --  Installation of WarpIN itself now creates objects for
        the documentation too.

    --  Various GUI enhancements and bugfixes. Added new
        XTextView control for viewing text.

    --  WarpIN can now repair the database itself to a certain
        extent, should it become corrupt.

    --  CONFIG.SYS was always rewritten to disk, even if
        nothing was changed. That lead to a lot of backup files
        in the boot drive. Fixed.

    --  Script parsing errors always had wrong line numbers.
        Reworked that, I hope it's better now.

    --  REPLACECLASS wasn't stored in the database. Fixed that.

    --  Fixed some memory leaks and other heap problems.

    --  WIC.EXE has new "-c" and "-r" parameters for changing
        to subdirectories and recursively adding files.

    --  Source code reorganized again. Split up the frontend C++
        classes across many more headers to reduce the need for
        recompiles and speed up compilation also.

    --  Introduced more base classes for the various frontend
        classes so we can make STL list's of the base class,
        which reduces code bloat amazingly. I reduced WARPIN.EXE's
        size by about 100 KB doing this.


    V0.9.0
    ------

    --  Source code reorganized.

    --  Reworked the entire frontend to use C++ classes now;
        implemented a proper "add/remove" mode if packages from
        an archive have already been installed.

    --  Packages support six-part IDs now too (three-part version
        numbers).

    --  Rewrote "add/remove" mode completely.

    --  Lots of other user interface enhancements.

    --  Entry field on cnr page was limited to some 30 characters. Fixed.

    --  Changed back-end to use libbz2 instead of zlib. This leads to
        an incompatible archive format, but compresses faster and better.

    --  DLL/EXE files can now be unlocked if in use.

    --  GROUP tags are working again.

    --  WARPIN and TITLE tags are working.

    --  Added EXPANDED attribute to GROUP tag.

    --  Rewrote the database viewer completely. Now using a split
        view.

    --  Database was missing install date and time. Added that.

    --  PMWIC added to source code.

    --  Added directory recursion to WIC.EXE.


    Alpha #4
    --------

    --  There are now two INFs: one for the user, one for the programmer.

    --  The global database is working!! This was a %&$ of work...
        This means that de-installing packages should be working now.

    --  Creating WPS objects, CONFIG.SYS manipulation, WPS class management,
        and macro resultion implemented!
        Check the PCK tag reference in WPI_PROG.INF for details.

    --  Better "File exists" dialog.

    --  Multiple packages are now supported.

    --  Added environment variable support for CID installation.

    --  WIC.EXE can now update packages and set install scripts independently
        (as far as I've tested this). Phh...

    --  Most strings that WarpIN displays have now been exported to the resources
        and MSG file to support NLS. This will probably still change however, so
        don't attempt any translating at this point. There's still no NLS for
        the install script error messages, and I don't know yet whether there'll
        ever be.

    Alpha #3
    --------

    --  Compression/decompression. We're now using the zlib library
        which works just beautifully.

    --  Lots of error checking. Files are checked for existence
        before they are overwritten, most other error conditions
        should be handled well also. If all goes wrong, there is
        a sophisticated exception handler too.

    --  The front-end sources have been cleaned up big time. There
        is now a clean separation between the string logic (for the
        install script) and the PM display stuff. There is no more
        string parsing in the PM part (gui.* files), so this can
        more easily be replaced.

    --  There is readable documentation in INF format now.
        PLEASE READ IT before asking any questions.


    Previous versions
    -----------------

    Lost track of them, sorry.


7. TO DO
========

    In contrast to what the INF files might say, the following things
    are _not_ implemented or working yet:

    --  system/readonly files cannot be overwritten

    --  Not all environment variables are evaluated yet.

    But we're working on this. ;-)

    Please, check the BUGS and FEATURES files in the main directory
    also.

    Ulrich Mller


8. FILE DESCRIPTIONS
====================

    Files in this directory:

    --  COPYING: the GNU General Public Licence (GPL), under which
        WarpIN is released.

    --  *.cmd: demo scripts for creating test archives. See notes below.

    --  *.wis: demo install scripts for the *.cmd archive creator scripts
        of the same filestem.

    --  warpin.exe: the actual installer. This needs a WarpIN archive
        on the command line. You best create a program object for this
        and associate it with "*.WPI" files.

    --  warpin.inf: "WarpIN Programmer's Guide and Reference."

    --  warpin.tmf: WarpIN NLS text messages. Must be in the same dir
        as warpin.exe.

    --  warpin.sym: symbol table created by MAPSYM.EXE in case WarpIN
        crashes.
        Must be in the same dir as warpin.exe.

    --  wic.exe: the "WarpIN Archive Creator". Explains itself on the
        command line.

    The subdirectories contain the source code.


9. TESTING WARPIN
=================

    I have added a small script called "apps.cmd" which creates
    a test archive, containing a lot of files from the \OS2 system
    directories.
    This will of course only create the archive, not delete any files.

    The sample archive will have three packages and an install script
    which can create WPS objects and modify CONFIG.SYS.

    ----> WARNING 1: Alpha #4 was the first alpha which messes with CONFIG.SYS.
                     From my experience, the system still boots after
                     WarpIN has modified CONFIG.SYS, but WATCH OUT.
                     WarpIN will create a backup copy of your CONFIG.SYS
                     file called CONFIG.xxx with "xxx" being a three-digit
                     number, but please, please, make an additional backup
                     copy of CONFIG.SYS yourself before installing the
                     archive, you never know.

    Then do this:

    1.  Double-click on WARPIN.EXE to have it install itself.

    2.  Double-click on APPS.CMD to have a large sample archive (APPS.WPI)
        created. This packs a number of system files, including all the DLLs
        in your \OS2\DLL directory, into the sample archive.

        WARNING 2: This thing requires up to 30 MB of free space on the
                   current drive. WIC.EXE still has no error checking in
                   this respect, so beware.

    3.  Double-click on APPS.WPI to have it installed.

        WARNING 3: Do not enter any OS/2 system directories for the package
                   installation paths. This might overwrite all your system
                   DLLs! Use some new directory instead.


10. CONTACT
===========

    We have created two groups on egroups.com for WarpIN discussions.
    All WarpIN developers are members of both groups, so please don't
    mail us directly, but use the groups instead:

    warpin-user     for WarpIN users which don't care for programming.
                    Use this group for bug reports.

    warpin-dev      for WarpIN developers and anyone who's interested.
                    You should be vaguely familiar with the source code
                    to join.


