; $Id: readme.txt,v 1.25 2000/07/27 17:20:30 umoeller Exp $

WarpIN 0.9.4 README
(W) Ulrich Mller, Sept 9, 1999
Last updated July 27, 2000, Ulrich Mller


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

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


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

    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 4 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, please
    copy the files from this release over the files of your
    existing installation. There's no automatic updating yet.


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

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

    -- WPI2EXE is 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. 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


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

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.

    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 from Hobbes (cvs110.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:

        SET CVSROOT=:pserver:guest@www.netlabs.org:d:/netlabs.src/warpin
        SET USER=guest

       Do a "cvs login" with "readonly" as your password.

       Then do a "cvs checkout".

    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.

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

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


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/ 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".


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



