| 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. === |
| | 18 | Before building WarpIN installation files for FM/2 you may want to customize the build via the following environment variables: |
| 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 == |
| 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. |
| | 95 | |
| | 96 | |
| | 97 | == The WPI file build process == |
| | 98 | |
| | 99 | The 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 | |
| | 111 | The 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 |
