WarpIN 0.9.20 README
(W) Ulrich Mller, Sept 9, 1999
Last updated August 11, 2002, 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-2002 Jens Bckman,
                            Ulrich Mller,
                            Teemu Ahola,
                            Cornelis Bockemhl,
                            Yuri Dario,
                            and others.

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

    WarpIN is becoming more and more popular among OS/2 developers
    as the preferred installer.

    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. Developer sections are specifically
    marked and may be skipped.

    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 yet. While WarpIN has indeed
    come a long way since the first releases, there might be
    some bugs left.

    As soon as we consider something ready for public use, we'll
    release a "stable" version with an even minor number, such as
    1.0.0.


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

    WarpIN needs to be installed before it can install archives
    itself.

    Starting with V0.9.14, WarpIn comes as a self-installing
    executable. Simply double-click on that and follow the
    instructions.


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.

       Since WarpIN now has full support for "real" self-installing
       archives (starting with V0.9.14), WPI2EXE is no longer part
       of the binary releases.

    -- 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 on your boot
    drive. Of course this will only pack those files into a test
    archive, but not delete your original files.

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

    To perform the test, 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.

        NOTE:      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.

        NOTE:      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:/netlabs.src/warpin
       For the XWPHelpers repository:
        SET CVSROOT=:pserver:guest@www.netlabs.org:/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).

       For details about how to use CVS, see

            http://www.xworkplace.org/cvs.html


    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)  IBM VisualAge C++ 3.08 is the preferred compiler.

        Yuri Dario has managed to get the thing compiled with VAC
        3.6.5 as well, but I am not checking this.

        Jens used to use EMX to develop the back-end, and for that
        reason there are still some #defines for compatibility
        in the code. However, I usually do not check whether the
        code still compiles with EMX. So 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).

        The main WarpIN code no longer uses the STL, but WicPM
        does, so to compile the whole thing, an STL implementation
        is required.

        With EMX, the STL is already included in the emx\include\cpp
        tree.

        With 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. Apparently, the newer STL versions use
        the more modern template features, which VAC doesn't like.

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

    With V0.9.12, the build setup has been reworked.

    Before compiling, you need to set up a bunch of environment
    variables. Please take a look at config.in in this directory,
    which is included by setup.in, which is in turn included by
    every single makefile from all the directories.

    You must adjust the directories in config.in and the other
    settings to match your system, or compiling won't work.


    Building
    --------

    Before starting the first build, you must run

        nmake dep

    once, which will create ".depend" files in all the subdirectories
    for the source dependencies. This uses the fabulous fastdep
    utility, which should be in the root dir of the xwphelpers.
    You should re-run "nmake dep" only after you have updated the
    sources from the CVS server because dependencies might change.

    After that, just run "nmake" to compile.


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.



