; $Id: readme.txt,v 1.34 2001/03/14 11:52:42 phaller Exp $

WarpIN 0.9.11 README
(W) Ulrich Mller, Sept 9, 1999
Last updated April 26, 2001, Ulrich Mller


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

    1.  LICENSE, COPYRIGHT, DISCLAIMER
    2.  INTRODUCTION
    3.  GETTING STARTED
    4.  WPI2EXE, WICPM
    5.  RELEASE HISTORY
    6.  KNOWN LIMITATIONS
    7.  TESTING WARPIN
    8.  CONTACT
    9.  COMPILING
    10. SOURCE CODE NOTES
    11. SOURCE CODE DOCUMENTATION


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

    Copyright (C) 1998-2001 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.

    NOTE: Some parts of WarpIN may have been published under a different
          licence. See the individual source files for details.


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

    Welcome to WarpIN 0.9.11.

    WarpIN is becoming more and more popular among OS/2 developers
    as the preferred installer. Still, WarpIN isn't quite perfect
    yet and has a few quirks left to be fixed (see section 6 below).

    This README contains information not contained in the WarpIN
    INF files. It is distributed with the binary distributions,
    but is also in the root directory of the WarpIN CVS tree.
    As a result, this file contains information both for WarpIN
    users and WarpIN developers. Please read through all of this
    before using WarpIn.

    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.


3. GETTING STARTED
==================

    WarpIN needs to be installed before it can install archives
    itself. Simply double-click on WARPIN.EXE, which will register
    WarpIN with OS2.INI and create program objects.

    For details, please refer to WPI_USER.INF.

    If you have a previous version of WarpIN installed, WarpIN
    can automatically update an existing installation. As with
    a first-time install, simply double-click on WARPIN.EXE (the
    new one), and it will copy itself over your existing
    installation. In the dialog that comes up, press the "Upgrade
    existing" button.


4.  WPI2EXE, WICPM
==================

    This release contains two additional programs with no or
    little documentation at this point.

    -- WPI2EXE was new with V0.9.4 and creates an .EXE file from
       a .WPI file. This has been added to avoid the download
       programs we have been experiencing with .WPI files (see
       WPI_USER.INF).

       The .EXE created by WPI2EXE contains the .WPI file(s)
       plus a small stub which starts WarpIN on the user's hard
       disk, if WarpIn has already been installed. If WarpIN is
       not installed, the user is given a message where to
       download WarpIN.

    -- WICPM is the PM version of WIC, the WarpIN Archive
       Creator. This is work in progress and is for users who
       do not enjoy working on the command line.


5. RELEASE HISTORY
==================

    See HISTORY.TXT.


6. KNOWN LIMITATIONS
====================

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


7. TESTING WARPIN
=================

    In the "test" subdirectory, you can find a small script called
    "apps.cmd" which creates a test archive (APPS.WPI), 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 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.

    2.  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.


8. CONTACT
==========

    We have created two groups on groups.yahoo.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.

9. 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 6 above to find out what doesn't work yet.

    Source code is no longer included with the binary releases.
    To get the sources, do one of the following:

    -- Download a sources package.

    -- Check out the sources from the Netlabs CVS server.

    If you check out from Netlabs CVS, starting with V0.9.6, you
    will need to check out TWO repositories:

    -- "warpin": the WarpIN main source code.

    -- "xwphelpers": the "XWorkplace helpers", i.e. code that
       is shared with XWorkplace. This used to be the code that
       was in src\helpers and include\helpers in the WarpIN source
       tree.

    To check out the most current WarpIN sources from the Netlabs
    CVS server, you have again two options. In both cases, you
    will need to download CVS 1.10.6 from Hobbes (cvs-1_10_6.zip).

    -- Use the Netlabs Open Source Archive Client (NOSAC), which
       creates WPS objects for working on the Netlabs sources.

    -- If you prefer using the command line, use the following
       environment for WarpIN:

       For the WarpIN repository:
        SET CVSROOT=:pserver:guest@www.netlabs.org:d:/netlabs.src/warpin
       For the XWPHelpers repository:
        SET CVSROOT=:pserver:guest@www.netlabs.org:d:/netlabs.src/xwphelpers
       For both:
        SET USER=guest

       For each, do a "cvs login" with "readonly" as your password.

       Then run "cvs checkout ." (mind the dot).


    Annotation to CVS access
    ------------------------

       With certain CVS version, it has been noticed the files
       .\include\wicpm\wicpm.h
       .\src\wicpm\wicpm.cpp
       are missing. If this is the case, just go to the corresponding
       directory and manually issue "cvs update wicpm.h" or
       "cvs update wicpm.cpp"


    Requirements
    ------------

    To compile, 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... but
        I will gladly accept fixes.

    c)  If you use VAC++ 3.08, you need an implementation of the
        C++ Standard Template Library (STL). With EMX, this is
        already included in the emx\include\cpp tree.

        Wih VAC, I am using STLport, an enhanced version of the
        original STL by Hewlett Packard.

        I have uploaded STLport 3.0.1 to
        ftp.netlabs.org/pub/tools/wps/xworkplace/ for your
        convenience. Other versions are available from
        www.stlport.org.

        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.

        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). See below.

    d)  As said above, with V0.9.6, the helpers code has been put
        into a separate CVS repository at Netlabs. Check out the
        "xwphelpers" repository before compiling, this code is
        needed.

    e)  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 with
             the XWorkplace sources (on Netlabs CVS too) in the
             PROGREF.INF file.

        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).

    f)  It is suggested to have the tool "gbmsize.exe" from the
        so called "general bitmap module" in the path. HTML2IPF
        calls this automatically to convert all .gif files to
        appropriate .bmp bitmaps as required for building the .INF
        and .HLP files of the documentation.

        However, this only gets called if the matching .BMP files
        do not exist yet. So alternatively, you can convert all
        GIFs manually to OS/2 1.3 bitmaps. (NOTE: 2.0 bitmaps
        will NOT work.)


    Environment variables
    ---------------------

    Before compiling, you need to set environment variables to
    which the makefiles react.

    The following are REQUIRED:

    -- "CVS_WORK_ROOT": the root directory of your local CVS tree,
       i.e. the parent directory of "warpin" and "xwphelpers".
       The WarpIN makefiles use this variable to locate the
       "xwphelpers" directory.

       For example:
        SET CVS_WORK_ROOT=K:\cvs

    -- "STL_DIR": with VAC only, this must point to the root of
       your external STL implementation (see remarks above).

       For example:
        SET STL_DIR=K:\libs\STLport-3-0-1

    -- "WPI_PROG_DIR": set this to "wpi_prog".
       The build process will create the new programming
       documentation for the XML-based scripts there.

    The following are OPTIONAL:

    -- "EMX": EMX only, set this to YES if you're using EMX
       instead of VAC.

       For example:
        SET EMX=YES

    -- "WPI_DEBUG": set this to YES if you want to build the
       debug version (which is a LOT larger, but runs with IPMD
       from VAC). I don't think this works with EMX.

       For example:
        SET WPI_DEBUG=YES

       With the debug build, you will also need the PMPRINTF
       package by Dennis Bareis. Last time I checked (Mar 12,
       2001), this was at

            http://www.labyrinth.net.au/~dbareis/zips_fw/pmf96179.zip

       You will need to put the DLLs from PMPRINTF on your
       LIBPATH.


10. 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/ tree at any time to enforce 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).

    You must use NMAKE only, 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 use neither VAC nor EMX, edit "setup.in" in the main
    directory. This file is included from all makefiles in the
    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.


11. 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.
    A compiled version exists in the main directory of the xwphelpers
    repository.

    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.



