WarpIN 1.0.18 README
(W) Ulrich Mller, Sept 9, 1999
Last updated December 7, 2008


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-2008 Jens Bckman,
                            Ulrich Mller,
                            Teemu Ahola,
                            Cornelis Bockemhl,
                            Yuri Dario,
                            Paul Ratcliffe
                            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 1.0.18.

    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 1.0.18 is the latest "stable" WarpIN release. This does
    not mean that WarpIN is bug-free, but I consider the current
    code useful enough to be recommended as the standard WarpIN
    installation.

    However, there are still a few known issues, which mostly affect
    package creators. Please see the BUGS file for details. In
    addition, WarpIN CID support via wic.exe is still experimental,
    but this addition does not hurt the GUI version.


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 netlabs.org for WarpIN discussions:

    warpin-user     for WarpIN users who 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.

    A bugtracker for WarpIN is available at

            http://xtracker.xworkplace.org

    Please use that beast for reporting bugs instead of posting
    them to the mailing lists. Thank you.


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.

    NOTE: If you are familiar with the XWorkplace sources, be aware
          that as opposed to with XWorkplace, there is no branch
          for WarpIN yet. Check out both repositories from the
          trunk. Most importantly, do not attempt to compile
          WarpIN with the 1.0.x branch of the "xwphelpers"
          repository, which will probably fail.

    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.12.13 - the latest is here:

      http://hobbes.nmsu.edu/pub/os2/dev/util/cvs11213.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@cvs.netlabs.org:/netlabs.cvs/warpin
       For the XWPHelpers repository:
        SET CVSROOT=:pserver:guest@cvs.netlabs.org:/netlabs.cvs/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


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

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

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

    f)  If you do a debug build (by setting WPI_DEBUG to something
        in config.in), you'll need the PMPRINTF package by Dennis
        Bareis. It's available at
        http://www.labyrinth.net.au/~dbareis/zips_fw/pmf96179.zip.

        Alternatively, you can set WPI_DEBUG_SYM to do a release
        build with debug symbols, but excluding PMPRINTF.


    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.
