Changes between Version 5 and Version 6 of WPIBuild


Ignore:
Timestamp:
Jun 10, 2007, 3:26:26 PM (12 years ago)
Author:
jbs
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WPIBuild

    v5 v6  
    11[[PageOutline]]
    22
    3 = Building WarpIN (WPI) install files for FM/2 =
     3= Building WarpIN (WPI) installation files for FM/2 =
    44
    55== Prerequisites ==
    66
    77 * A drive with long filename support
    8  * A functional FM/2 build environment. (See build instructions elsewhere for details.)
     8 * A functional FM/2 build environment. ([/repos/fm2/trunk/BUILDING See build instructions] elsewhere for details.)
    99   * IBM !VisualAge C++ version 3.65 with FP2 (Soon to be Open Watcom.)
    1010   * OS/2 Develoeprs Toolkit v4.5 or newer
    1111   * SVN
     12   * A local copy of the SVN repository of FM/2 source files
    1213 * WarpIN, version 0.9.20 or later, installed
    1314 * A functional version of SED installed
    1415
    15 == How to build WarpIN installation files for FM/2 ==
    16  1. Use '''SVN CHECKOUT''' and/or '''SVN UPDATE''' to ensure you have the latest source files.
    17  2. From the base of the source subtree, use '''NMAKE ALL''' to ensure you have the latest binaries.
    18  3. (Optional) Set environment variables to manage/customize the Warpin file creation. (See below for details.)
    19  4. If you do not disable the build of an FM2UTILS WPI file, then you should...
    20   a. create a '''FM2UTILS''' subdiretory of the '''WARPIN''' subdirectory of the FM/2 source subtree.
    21   b. obtain a copy of '''FM2UTILS.ZIP''' and unzip it into this directory.
    22  4. From the base of the source subtree, use '''NMAKE DIST''' which will compress the executables and build the WarpIN installation files.
    23 
    24 NOTE: If repeated builds of WarpIN installation files from the same FM/2 binary files are needed/desired, then repeated compression of the executables is not needed. Use '''NMAKE WPI''' to skip the compression steps and just build the WarpIN files.
    25 
    26 == Customizing the WPI build through environment variables. ==
     16== Building WarpIN installation files for FM/2 ==
     17=== Customizing the WPI build through environment variables. ===
     18Before building WarpIN installation files for FM/2 you may want to customize the build via the following environment variables:
    2719 BUILD_FM2UTILS::
    2820  By default, a WPI file is created for both FM/2 and the optional, separate FM/2 utilities package. To prevent the creation/update of the FM/2 Utilities WPI file, use '''SET BUILD_FM2UTILS=0'''.
     
    3224  The WPI file for FM/2 Utilities is named '''FM2UTILS'''''<version-string>'''''.WPI'''. The ''<version-string>'' portion of the file name can be set through the '''FM2UTILS_VER''' environment variable. For example, '''SET FM2UTILS_VER=-1-0-1''' will result in '''FM2UTILS-1-0-1.WPI''' being created/updated.
    3325
    34 == Modifying the FM/2's WarpIN installation ==
     26=== How to build the WarpIN installation files of FM/2 ===
     27 1. Obtain a local copy of the SVN respository of FM/2 source files.
     28 2. (Optional) Set environment variables to manage/customize the Warpin file creation. (See above for details.)
     29 3. If a WPI file for FM2 Utilities is to be built...
     30  a. If a '''FM2Utils''' subdirectory of the Warpin subdirectory of the FM/2 build subtree does not exist, create one.
     31  b. Obtain a copy of FM2UTILS.ZIP and unzip it into this '''FM2Utils''' directory.
     32 4. (Optional) Make any desired changes to local copies of the files within the build subtree.
     33 5. Build the WarpIN installation files of FM/2 using '''NMAKE DIST''' or '''NMAKE WPI'''.
     34 * '''NMAKE DIST'''
     35  * ensures that the rest of FM/2 is built and should be used every time the local copy of any FM/2 source files have been changed.
     36  * performs LXLITE compression of the executables.
     37  * builds the WPI file(s)
     38 * '''NMAKE WPI'''
     39  * only builds the WPI files so it is faster than '''NMAKE DIST'''.
     40  * will not work correctly unless '''NMAKE DIST''' has been at least once beforehand.
     41  * is intended to be used by those who are making modifications to the WarpIN installation files for FM/2 (See below.). As these programmers develop and test their changes they will be repeatedly building WPI files when the only changes that have been made is to the WarpIN-related files or environment variables:
     42   * warpin\fm2.wis.in (the WarpIN script)
     43   * warpin\bld_fm2_wpidirs.txt
     44   * warpin\makefile
     45   * various text files "read" by the script and displayed within WarpIN windows during installation
     46   * various REXX programs called by EXECUTE and/or DEEXECUTE statements within the script.
     47
     48== Modifying the FM/2's WarpIN installation files ==
    3549
    3650=== Getting started ===
    3751
    38 Before attempting to modify FM/2's WarpIN installation one should first read and understand the WarpIN Programmer's Guide and Reference. It will acquaint you with the general, technical details of creating WPI files. Then read and become familiar with FM/2's WarpIN script, '''FM2.WIS.IN''', which is found in the '''WARPIN''' subdirectory of the FM/2 source subtree. This will acquaint you with the specifics of how the current WarpIN installation of FM/2 is implemented.
     52Before attempting to modify FM/2's WarpIN installation files one should first read and understand the WarpIN Programmer's Guide and Reference. It will acquaint you with the general, technical details of creating WPI files. Then read and become familiar with FM/2's WarpIN script, '''FM2.WIS.IN''', which is found in the '''WARPIN''' subdirectory of the FM/2 source subtree. This will acquaint you with the specifics of how the current WarpIN installation of FM/2 is implemented.
    3953
    4054=== Overview ===
     
    4761 3. The files and subdirectories are installed into the user-selected installation directory during the installation of FM/2.
    4862
    49 Changes to the FM/2 Warpin installation will fall into three general categories:
     63Changes to the FM/2 Warpin installation will fall into the following general categories:
    5064 * Changes that only require script changes. Examples of these changes are:
    5165  * Changes in package names
     
    5670  * Changes in whether or not '''CONFIG.SYS''' is updated
    5771  * Changes in if or how OS2.INI is modified
    58  * Internal changes to the various REXX programs run via EXECUTE and DEEXECUTE statements within the script. If these changes require different parameters, then the script will need changing, too.
     72 * Changes to files referenced within the script:
     73  * various REXX programs run via EXECUTE and DEEXECUTE statements within the script. If these changes require different parameters, then the script will need changing, too.
     74  * various text files "read" by the script and displayed during the WarpIN installation of FM/2.
    5975 * Changes which require changes to the staging process (and, possibly, changes to the script). Examples of these changes are:
    6076  * Changes in package numbers (requires script change, too)
     
    6480  * Changes to the names of files
    6581  * Changes to the package numbers to which files are assigned
    66 
    67 === How to modify the WarpIN installation ===
    68  * For script changes alter '''FM2.WIS.IN'''. Do NOT alter FM2.WIS!.
    69  * For internal changes to the REXX programs called via EXECUTE or DEEXECUTE, edit the appropriate file within the build subtree.
     82 * Changes to the WPI file build process itself (See below for details on the current WPI build process.)
     83  * Changes to warpin\makefile
     84  * Changes to the programs called from warpin\makefile
     85=== How to modify the WarpIN installation files for FM/2 ===
     86 * For script changes alter warpin\'''FM2.WIS.IN'''. ''Do NOT alter warpin\FM2.WIS''!.
     87 * For changes to files referenced within the script, edit the appropriate files within the build subtree and update the script, if necessary.
    7088 * For changes which require changes to the staging process:
    7189  1. Make appropriate changes, if any, to the build process. For example:
    7290    * Cause new or renamed files and/or directories to be created.
    7391    * Cause discontinued files to no longer be created.
    74   2. Alter '''BLD_FM2_WPIDIRS.TXT'''. This file is used to control which files from which build subtree directories are to be staged into which directories of which packages. '''BLD_FM2_WPIDIRS.TXT''' is self-documented. Read it to learn how to make changes to it.
     92  2. Alter warpin\'''BLD_FM2_WPIDIRS.TXT'''. This file is used to control which files from which build subtree directories are to be staged into which directories of which packages. '''BLD_FM2_WPIDIRS.TXT''' is self-documented. Read it to learn how to make changes to it.
     93 * For changes to the WPI build process, edit the appropriate files within the build subtree.
    7594 * When finshed with these modifications, follow the instructions above ("How to build ...") to create the new FM/2 WPI files.
     95
     96
     97== The WPI file build process ==
     98
     99The portion of the build process for FM/2 which build the WPI files is controlled by the warpin\makefile file. For the following reasons a significant amount of the processing is delegated to REXX programs called from the makefile:
     100 * To build a WPI file the WarpIN executable named WIC.EXE must be functional during the build process. By default the WarpIN directory is not added to the PATH and LIBPATH when WarpIN is installed so WIC.EXE will not run from the command line without being added to the PATH and LIBPATH. The following options were considered:
     101  * Use the REXX CMD file distributed with WarpIN (RUNWIC.CMD). It provides one-time executions of WIC.EXE (by temporarily modifying the PATH and LIBPATH). But it is flawed because it "breaks" other LIBPATH modifications which may have made previously. And even though this will be fixed with future distributions of WarpIN the FM/2 build process still needs to "find" RUNWIC.CMD to run it. So RUNWIC.CMD was rejected.
     102  * Use a custom REXX programs, BLD_FM2*_WPI.CMD, which
     103   * Do not "break" other settings.
     104   * Adds the Warpin directory to the PATH and (BEGIN)LIBPATH only if it is not already on those paths.
     105   * Relieve developers from having to add the Warpin directory manually to the PATH and LIBPATH.
     106 * Providing the following in an easily maintainable way without the use of REXX programs (and '''BLD_FM2_WPIDIRS.TXT'''), was beyond the makefile programming skills of the initial programmer of the WPI build process:
     107  * Staging only updated or missing files from the correct build subtree directories into the correct staging subdirectories for inclusion into the correct packages.
     108  * Changes to file names, build subtree directories and package subdirectories and/or package numbers are facilitated.
     109  * Ensuring that discontinued files are no longer packaged into the WPI files.
     110
     111The make process:
     112 1. Target: checkfiles
     113  a. Pupose: Determine what files, if any, need to be staged for addition to the WPI file.
     114  b. REXX program: ckfiles
     115   1. If the WPI file is missing or if the '''BLD_FM2_WPIDIRS.TXT''' file is newer than the WPI file, then '''BLD_FM2_WPIDIRS.TXT''' is copied to '''BLD_FM2_WPIDIRS.IN'''. (This causes a full rebuild of the WPI file later on.)
     116   2. Otherwise the '''BLD_FM2_WPIDIRS.TXT''' is read, a '''BLD_FM2_WPIDIRS.IN''' file is written which lists only the files from '''BLD_FM2_WPIDIRS.TXT''' which are new or updated (compared to the date/time of the WPI file).
     117 2. Target: fm2.wis: fm2.wis.in fm2utils\fm2utils.doc fm2utils\license.txt
     118  a. Purpose: To incorporate the text from FM/2 Utilities text files into the FM/2 install script.
     119  b. This is done so that changes to these text files would not require identical changes to the FM/2 WarpIN script.
     120  c. SED is used to read '''FM2.WIS.IN''' and replace certain special strings with the contents of the text files, creating the final script, FM2.WIS. This is why SED is required and why changes to the script must be made to FM2.WIS.IN.
     121 3. Target: fm2$(FM2_VER).wpi:: bld_fm2_wpidirs.in
     122  a. Purpose: Stage the files identified by the checkfiles target and then build the WPI file.
     123  b. REXX program: bld_fm2_wpidirs.cmd
     124   1. If '''BLD_FM2_WPIDIRS.IN''' is newer than the WPI file, then read it to identify which files need to be staged, where they are located in the build subtree and where they should be staged.
     125  c. REXX program: bld_fm2_wpi.cmd
     126   1. Build the WPI file from the staged files and the latest script, fm2.wis.
     127   2. Delete the staging directories. This prevents "moved" or discontinued files, which would otherwise linger in the staging directories, from being incorporated into future WPI files.
     128 4. Target: fm2$(FM2_VER).wpi:: fm2.wis
     129  a. Purpose: Build the WPI file when only the script has changed.
     130  b. REXX program: bld_fm2_wpi.cmd
     131 5. fm2utils$(FM2UTILS_VER).wpi: bld_fm2utils_wpi.cmd fm2utils.wis fm2utils\fm2utils.doc fm2utils\license.txt ..\shdwmgr.cmd
     132  a. Purpose: Build the FM/2 Utilities WPI file
     133  b. REXX program: bld_fm2utils_wpi.cmd