; $Id: readme.txt,v 1.36 2001/05/31 18:13:39 umoeller 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. 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.