.. ***************************** Module Header ******************************* .. .. Module Name: makefile.txt .. .. Source file for the INF file providing help for makefile .. Requires HyperText/2 package to compile .. .. Unlike the nepmd.inf, the makefile.inf is compiled to the bin subdirectory .. and checked in to make it always available right after checking out. .. .. So when updating this file, commit also the changed INF file! .. .. Copyright (c) Netlabs EPM Distribution Project 2002 .. .. $Id$ .. .. =========================================================================== .. .. This file is part of the Netlabs EPM Distribution package and is free .. software. You can redistribute it and/or modify it under the terms of the .. GNU General Public License as published by the Free Software .. Foundation, in version 2 as it comes in the "COPYING" file of the .. Netlabs EPM Distribution. This library 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. See the GNU .. General Public License for more details. .. .. *************************************************************************** .hi 234 .include titleeng.inc .set TITLE=*[=DOCTITLE]* .set STDLIST=compact break=fit tsize=20 .ti [=DOCTITLE] .. ============================================================================= .1 Making of [=DOCTITLE] .. ============================================================================= .an IDPNL_OVERVIEW .at font='20.Tms Rmn' fc=darkgray italic bold .bitmap bmp\nllogo.bmp center .ce present the Making of .at font='24.Tms Rmn' fc=red bold italic .ce The [=DOCTITLE] .at [=TOPICS] .su 1 .. ----------------------------------------------------------------------------- .2 Requirements .. ----------------------------------------------------------------------------- .an IDPNL_REQUIREMENTS The following is required for making the [=TITLE]: .su V30 [=NOTE] .ul compact .at hi - Any makefile processing will check for all required packages to be available and abort if anything is missing on your system! .at .. ............................................................................. .3 Long filename support .. ............................................................................. .an IDPNL_REQUIREMENTS_LONGFILENAME This project requires long filename support (e.g. JFS or HPFS). .. ............................................................................. .3 C Compiler .. ............................................................................. .an IDPNL_REQUIREMENTS_COMPILER As compiler, the following are supported: .ul compact - *IBM VAC 3.08* (much better debugger). - *IBM C Set/2* (debugger seems not to cope with the debug version...) [=NOTE] .ul compact - The compiler used is automatically recognized by the makefile. .. ............................................................................. .3 OS/2 Toolkit .. ............................................................................. .an IDPNL_REQUIREMENTS_TOOLKIT As toolkit, one of the following is required: .ul compact - *OS/2 Warp 4.5 Developer's Toolkit* - *OS/2 Warp 4 Developer's Toolkit* - *OS/2 Warp 3 Developer's Toolkit* Since eComStation, the toolkit is distributed with the operating system. There exist a few fixes. One of them is *RC.EXE*, see below. A recent and fixed version of the toolkit can be downloaded with .fo off yum install os2tk45 os2tk45-book os2tk45-headers os2tk45-ipfc os2tk45-libs os2tk45-rc os2tk45-readme os2tk45-utils .fo on [=NOTE] .ul - The following applies only if you use an original unfixed version of the OS/2 toolkit: - Some 5.xx versions of *RC.EXE* are quite buggy and cause problems. Therefore you have to replace the *RC.EXE*, that comes with Toolkit 4.5x. Older versions are usually OK to compile NEPMD. - The most recommended *RC.EXE* version is 5.00.007. It can be found here: - [http://www.os2site.com/sw/internet/mozilla/build/rcos2-5.00.007.zip] - As an alternative, you can use the Toolkit 4 version of *RC.EXE*, as recommended by the Warpzilla project: - [ftp://ftp.software.ibm.com/ps/products/warpzilla/os2tk40rc.zip] - Or rename bin\rc16.exe to rc.exe. That one works without the message file, but is the 16 bit version. The version, that comes with Warp 4.x and with eCSMT is also a 16 bit version and should work as well. .. ............................................................................. .3 EPM Macro Compiler .. ............................................................................. .an IDPNL_REQUIREMENTS_ETPM The *EPM Macro Compiler* is required to compile the .ex files. [=NOTE] .ul - *etpm.exe* is contained in the *NEPMD Macro Recompilation* package of the *NEPMD* WarpIN archive. It's located in epmbbs\bin. - Alternatively, you can download the program file *etpm.exe* as part of the *EPM base application* package zip file (no other files of this package are required) - [https://hobbes.nmsu.edu/?search=epmapp The Hobbes File Archive] . (search "epmapp" at hobbes.nmsu.edu) - *etpm.exe* must be accessible by the PATH statement. .. ............................................................................. .3 HyperText/2 .. ............................................................................. .an IDPNL_REQUIREMENTS_HTEXT For compilation of the online help, the preprocessor *HyperText/2* is used. Version 2.0 or later is required. [=NOTE] .ul - You can download *HyperText/2* from - [https://hobbes.nmsu.edu/?search=htext The Hobbes File Archive] . (search "htext" at hobbes.nmsu.edu) - Install according to the information in htext.inf. .ul - *htext.cmd* must be accessible by the PATH statement. - The bitmap files ***.bmp* must be placed either .ul compact - into the same directory where *htext.cmd* is located - into a subdirectory *htext* or *bmp* within the directory where *htext.cmd* is located - into a directory specified by either of the environment variables - *INCLUDE* - *HTINCLUDE* .. ............................................................................. .3 fastdep.exe .. ............................................................................. .an IDPNL_REQUIREMENTS_FASTDEP For creating dependency files, the *FastDep* utility is used. [=NOTE] .ul - You can download *FastDep* from the *XWorkplace* project being hosted on the *Netlabs SVN Archive Server*. Get the *XWPHelpers* project files with a SVN client. A binary is contained in the *xwphelpers* directory. - As an alternative, download a snapshot from - [ftp://ftp.netlabs.org/pub/snapshots/xwphelpers netlabs.org ftp server] . (go to ftp://ftp.netlabs.org/pub/snapshots/xwphelpers) - *fastdep.exe* must be accessible by the PATH statement. .. ............................................................................. .3 WarpIN .. ............................................................................. .an IDPNL_REQUIREMENTS_WARPIN The *WarpIN* Installer is used to create the installation package. As a minimum version 0.9.19 is required. [=NOTE] .ul - You can download *WarpIN* from - [http://trac.netlabs.org/warpin] - Makefile processing will extend the environment automatically to access the *WarpIN* executables, so it is not required to make them accessible via the PATH or LIBPATH statements. .. ............................................................................. .3 Tools available as .rpm packages .. ............................................................................. .an IDPNL_REQUIREMENTS_RPM The following packages can be downloaded and installed with one call to yum: .fo off yum install [.IDPNL_REQUIREMENTS_UNZIP unzip] [.IDPNL_REQUIREMENTS_WGET wget] [.IDPNL_REQUIREMENTS_REXX2EXE rexx2exe] [.IDPNL_REQUIREMENTS_GREP grep] [.IDPNL_REQUIREMENTS_LXLITE lxlite] [.IDPNL_REQUIREMENTS_TOUCH coreutils] .fo on .. ............................................................................. .4 unzip.exe of Info-Zip .. ............................................................................. .an IDPNL_REQUIREMENTS_UNZIP *UNZIP* is required in order to unpack certain parts of the EPMBBS packages, as it supports the deflated method used for some text files. This is not supported by *PKUNZIP2*. *PKUNZIP2* is not needed anymore, because since UNZIP 5.52 of 2005, also the shrink method is supported. [=NOTE] .ul - To download and install, execute .fo off yum install unzip .fo on - Alternatively, you can download *unzip* from - [https://hobbes.nmsu.edu/?search=unzip The Hobbes File Archive] . (search "unzip" at hobbes.nmsu.edu) - *unzip.exe* must be accessible by the PATH statement. .. ............................................................................. .4 wget.exe .. ............................................................................. .an IDPNL_REQUIREMENTS_WGET *wget* is used to download the original zip files, if not present. [=NOTE] .ul - To download and install, execute .fo off yum install wget .fo on - Alternatively, you can download *wget* from - [https://hobbes.nmsu.edu/?search=wget The Hobbes File Archive] . (search "wget" at hobbes.nmsu.edu) - *wget.exe* must be accessible by the PATH statement. - When sitting behind a firewall, create/modify a wget resource file in order to use an FTP proxy. Insert or add the following entries to the file %home%\.wgetrc and replace the bold printed values as required: .fo off ftp__proxy=http://*proxyname*:*proxyport* proxy__user=*proxy__userid* proxy__passwd=*proxy__password* .fo on .. ............................................................................. .4 rexx2exe.exe .. ............................................................................. .an IDPNL_REQUIREMENTS_REXX2EXE For converting a REXX script to an executable, the *REXX2EXE* compiler us used. [=NOTE] .ul - To download and install, execute .fo off yum install rexx2exe .fo on - Alternatively, you can download *REXX2EXE* from - [https://hobbes.nmsu.edu/?search=rexx2exe The Hobbes File Archive] . (search "rexx2exe" at hobbes.nmsu.edu) - *rexx2exe.exe* must be accessible by the PATH statement. .. ............................................................................. .4 grep.exe .. ............................................................................. .an IDPNL_REQUIREMENTS_GREP For checking unpacked EPM files, the *grep* utility is used. [=NOTE] .ul - The *grep* utility is only required if you run *src\wis\makefile* with pseudo target *check*. It is not mandatory in order to create the package itself. - To download and install, execute .fo off yum install grep .fo on - Alternatively, you can download *grep* from - [https://hobbes.nmsu.edu/?search=grep The Hobbes File Archive] . (search "grep" at hobbes.nmsu.edu) - *grep.exe* must be accessible by the PATH statement. .. ............................................................................. .4 lxLite.exe .. ............................................................................. .an IDPNL_REQUIREMENTS_LXLITE For packing the executables of the [=TITLE], the *lxlite* utility is used. [=NOTE] .ul - The *lxlite* utility is only required if you build the release version of the [=TITLE] executables, which is the default. In order to build the debug versions instead, either .ul compact - specify *DEBUG=1* as parameter to *nmake* or - set the environment variable *DEBUG=1* before calling *nmake*. - To download and install, execute .fo off yum install lxlite .fo on - Alternatively, you can download *lxlite* from - [https://hobbes.nmsu.edu/?search=lxlite The Hobbes File Archive] . (search "lxlite" at hobbes.nmsu.edu) - *lxlite.exe*, together with its *lxlite.cfg* must be accessible by the PATH statement. .. ............................................................................. .4 touch.exe .. ............................................................................. .an IDPNL_REQUIREMENTS_TOUCH For aligning the timestamps of the compiled files before they were packed into the WarpIN package the *touch* utility out of the *GNU file utilities* is used. [=NOTE] .ul - The *touch* utility is only required if you adjust the timestamps. In order to do that, either .ul compact - specify *TOUCH=1* as parameter to *nmake* or - set the environment variable *TOUCH=1* before calling *nmake*. - To download and install, execute .fo off yum install coreutils .fo on - Alternatively, you can download the *GNU core utilities* from - [https://hobbes.nmsu.edu/?search=coreutils The Hobbes File Archive] . (search "coreutils" at hobbes.nmsu.edu) - *touch.exe* must be accessible by the PATH statement. .. ----------------------------------------------------------------------------- .2 Development tree overview .. ----------------------------------------------------------------------------- .an IDPNL_DEVTREE The following directories currently exist in the SVN development tree: . (The *.svn* maintenance directory is not included here.) .pl compact break=none tsize=18 .fo off ³ ÃÄbranches no branch exists ³ ÃÄtags since the change from CVS to SVN, no tags are created anymore ³ ÀÄtrunk .lm 3 ³ ÃÄbin helpers and documentation for compilation ³ ÀÄsrc .lm 5 ³ ÃÄdoc several additional docs ³ ÃÄannounce ³ ÃÄhobbes ³ ÃÄtestfiles ³ ÃÄwse2002 ³ ÀÄwse2008 ³ ÃÄgui GUI and other files for compilation ³ ÃÄcommon ³ ÃÄepmcall EPM loader ³ ÃÄetk E Toolkit header files ³ ÃÄnepmdlib NEPMD library ³ ³ ÀÄmacros E macros as interface for the library (not shipped in the release) ³ ÃÄrecomp Recomp utility (outdated) ³ ³ ÀÄtestcase ³ ÀÄtest ³ ÃÄheader GNU headers for all used filetypes ³ ÃÄipf HyperText/2 sources for the NEPMD INF files ³ ÀÄbmp bitmaps for INF files ³ ÃÄ[=DISTDIR] base directory for sources simply copied to compile\[=DISTDIR] ³ ÃÄbar toolbars ³ ÃÄbin binary and executable files ³ ÃÄbmp toolbar bitmaps ³ ÃÄdll dlls ³ ÃÄex LST files used by toolbar macros and RecompileNew ³ ÃÄinstall installation related files ³ ³ ÀÄico NEPMD related icons for installation ³ ÃÄmacros E macros ³ ÃÄhilite definition files for keyword highlighting ³ ³ ÃÄ ³ ³ ÀÄ ³ ÃÄndx keyword help files ³ ÀÄtools external tools, included in the release ³ ÃÄnls base directory for all NLS files ³ ÃÄnetlabs ³ ³ ÀÄbin Text Message File ³ ÃÄrecomp NLS files for Recomp (outdated) ³ ÀÄwis NLS files for building the WarpIN package ³ ÃÄold unused files - for comparison only ³ ÃÄrexx installation files being executed after unpacking ³ (these files are converted to EXE files to avoiding ³ the annoying VIO window being popupped otherwise) ÃÄstatus outdated project status list ³ ÀÄdb ³ ÀÄwis WarpIN package creation files .lm .. .fo on The following #temporary# directory trees are created when building the *WarpIN* package: .fo off ³ ÀÄtrunk .lm 3 ³ ÃÄcompile holds temporary files being the same for debug or ³ ³ release version ³ ÃÄbase ³ ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ³ ÃÄepmcall ³ ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ³ ÀÄrecomp ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ³ ÀÄ the name of this directory is either *debug* or .lm 5 ³ *release* (among others it holds the resulting ³ WarpIN package file) ÃÄbase ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ÃÄepmcall ³ ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package ÀÄrecomp .lm 7 ÀÄ[=DISTDIR] directory tree to be packed into the WarpIN package .lm .fo on [=NOTE] .ul compact - The temporary directory trees, except *zip* and *epm.packages*, can be completely cleaned up (deleted) with executing *nmake clean* in the working root directory. Other directories used during a build are determined by the environment variables *%ZIPSRCDIR%* and *%UNZIPPEDDIR%*: .fo off *%ZIPSRCDIR%* holds downloaded EPMBBS ZIP files. The default for *%ZIPSRCDIR%* is \zip. *%UNZIPPEDDIR%* holds unpacked EPMBBS files before they were added to the WarpIN package. The default for *%UNZIPPEDDIR%* is \epm.packages .fo on .. ----------------------------------------------------------------------------- .2 Configuring the make process .. ----------------------------------------------------------------------------- .an IDPNL_CONFIGMAKE [=TOPICS] .su V30 .. ............................................................................. .3 Setting up the build environment .. ............................................................................. .an IDPNL_CONFIGMAKE_SETENV The easiest way to configure a build environment is to use a CMD file whilch contains the appropriate commands. The easiest way to create such a command file is to have it created for you. This can be done by: .ol compact - Execute: SET USED__COMPILER=abc. (This is an "incorrect" value which will trigger the automatic CMD file creation process in step 2.) - Run \bin\setenv.cmd. - You will be asked if you want to create this CMD file. - If you indicate you want the CMD file, you will be prompted for a variety of settings. At the end a file named *mysetenv.cmd* will be created for you in the base directory of the project. Once you have a CMD file with the appropriate settings just run it before trying to build NEPMD. [=NOTE] .ul compact - If you want to build your own CMD file or if you are just curious about the settings, .ol compact - Use the process above to create *mysetenv.cmd* - Read *mysetenv.cmd*. It is fairly well documented internally. - If you want to change the settings in *mysetenv.cmd* you can edit it directly or can just repeat the procedure above for creating *mysetenv.cmd*. - *DO NOT EDIT* any of the files in the \bin directory. .. ............................................................................. .3 Sample mysetenv.cmd .. ............................................................................. .an IDPNL_CONFIGMAKE_SETENVSAMPLE In the previous section it was described how executing \bin\setenv.cmd creates a new file *\trunk\mysetenv.cmd*. Here's an example for such a resulted file with comments stripped off: .fo text SET USED_COMPILER=VAC308 SET DIR_COMPILER=g:\dev\ibmcpp308 SET DIR_TOOLKIT=g:\dev\toolkt45 :: TMP, TZ and HOME are usually set by the OS: :: SET TMP=I:\TMP :: SET TZ=CET-1CDT,3,-1,0,7200,10,-1,0,10800,3600 :: SET HOME=f:\home SET BASEURL=ftp://hobbes.nmsu.edu/pub/os2/apps/editors/epm SET ZIPSRCDIR=G:\dev\netlabs\nepmd\zip SET UNZIPPEDDIR=G:\dev\netlabs\nepmd\epm.packages SET SVNEDITOR=epm.exe /m SET APPEND_DATE_TO_WPIFILE=1 SET TOUCH=1 : SET DEBUG= SET DEBUG=1 : Apply the compiler and toolkit vars CALL .\bin\setenv2.cmd .fo on Place such a file in the trunk directory! .. ............................................................................. .3 General settings in configure.in .. ............................................................................. .an IDPNL_CONFIGMAKE_CONFIGUREIN The *src\wis\makefile* requires several values, some of which have to be configured before executing *nmake* to build the complete package. [=NOTE] .ul compact - If you use [.IDPNL_CONFIGMAKE_SETENV *mysetenv.cmd*], then all of the following values will be set for you. So you will not need to edit the configure.in file. #Values which may be configured by anyone or can be predefined via an environment variable:# ..................................................................... .pl bold - BASEURL = specifies the location where the original ZIP files of the EPMBBS package (epm603b.zip and epm603bupd.zip) can be downloaded. The default is ftp://hobbes.nmsu.edu/pub/os2/apps/editors/epm. . - ZIPSRCDIR = specifies a local directory where the zip files from *BASEURL* will be saved. If the zip files are already present in this directory, then a download from *BASEURL* will not be necessary. . - UNZIPPEDDIR = specifies a local directory where the unpacked zip files will be placed. The default is *epm.packages* under your project base directory. . .el [=NOTE] .ul compact - You can predefine *BASEURL*, *ZIPSRCDIR* and *UNZIPPEDDIR* with environment variables. These environment variable settings override any settings in configure.in. - The parent directories of *ZIPSRCDIR* and *UNZIPPEDDIR* must exist. - *ZIPSRCDIR* and *UNZIPPEDDIR* will be created during a build if they do not already exist. - Do not use *UNZIPPEDDIR* for other files. Any files in that directory are deleted before unpacking the EPMBBS package files. #Values to be configured by release maintainer only:# ..................................................... .pl bold - STEM = specifies the id of the project, used within some filenames. - VERSION = specifies the current version, used in the name of the WPI package file. - ID__VERSION__NEPMD = specifies the current version and revision as to be used within the *WarpIN* script. . . [=NOTE] .ul compact - Keep in sync with the major and minor version used in *VERSION*! - This value has to be specified in the *WarpIN* package ID style: \\ .el - ID__VERSION__REQ__WARPIN = specifies the version and revision of *WarpIN* that the resulting WPI package should be restricted to as a minimum for installation. [=NOTE] .ul compact - This value has to be specified in the *WarpIn* package ID style: \\ .el .. ----------------------------------------------------------------------------- .2 Makefile pseudo targets .. ----------------------------------------------------------------------------- .an IDPNL_TARGETS [=TOPICS] .su V30 .. ............................................................................. .3 Main makefile .. ............................................................................. .an IDPNL_TARGETS_MAIN This section describes the makefile pseudo targets that are available for the main makefile within the project base directory (root of the development tree). [=NOTE] .ul compact - Ensure your environment is properly set for a build. See [.IDPNL_CONFIGMAKE_SETENV] for more information. - Targets marked with (**) require a working internet connection if the EPM zip files are not available within the directory specified by the *ZIPSRCDIR* environment settings. The following pseudo targets are available: .pl bold compact break=none tsize=20 - nmake all = Build all modules and thus the complete package. (**) . . This is achieved by calling all makefiles below the *src* subdirectory, of which the subdirectories are listed in the macro *MODULELIST*. . . This results in the *WarpIN* WPI package file created either in the *debug* or *release* directory, depending on the value of the *DEBUG* environment variable. (**) . - nmake inst = Like *nmake all*, but also starts the installation of WPI file. (**) . - nmake remove = Quickly deinstalls all packages installed from the [=TITLE] without using the *WarpIN* GUI. This is intended for testing purposes only! . [=NOTE] .ul compact - The revision numbers from the *WarpIN* script are ignored, but the vendor name, package name and component name must match exactly. - All files and WPS objects are removed. - No *INI* entries or *CONFIG.SYS* entries are removed. - No dependencies are checked! . - nmake gui = Build GUI components only. .. - nmake rungui .. = Build and run selected GUI components. - nmake lib = Build components for nepmdlib.dll only. - nmake runlib = Build components for nepmdlib.dll, nepmdlib.ex and neprgeng.inf. Copy nepmdlib.dll, nepmdlib.ex and neprgeng.inf to netlabs dirs for testing. Restart EPM if required. . - nmake [[help]] = Show this INF file (the INF is compiled first if it is outdated). This calls the makefile within the *src\ipf* directory with the target *showhelp*. - nmake showusr = Build User's Guide only and show it. - nmake showprg = Build Programming Guide only and show it. - nmake showfld = Build HLP file for the NEPMD folder and its objects only and show it. . - nmake inf = Build all INF and HLP files of the whole project. - nmake show = Build all INF and HLP files of the whole project and show all. . - nmake clean = Remove the *compile* and binary (both *debug* and *release*) directories. . - nmake NLS [[NLS=xxx]] = . (Re)set NLS language identifier to default or the specified [.IDPNL_APPENDIX_LANGIDS three letter language identifier]. To make things easier, the makefile allows also to set the language identifier by just specifying the symbol *NLS=xxx* without any target. . [=NOTE] .ul compact - This is only intended for testing purposes, as normally the language information for [=TITLE] is set by running the installation package of it. .. ............................................................................. .3 src\ipf\makefile .. ............................................................................. .an IDPNL_TARGETS_IPF The following makefile pseudo targets are available for the makefile within the *src\ipf* subdirectory: .pl bold compact break=none tsize=20 - nmake [[all]] = Build both the makefile INF and the project documentation INFs, but show none. . - nmake showhelp = Build and show this INF file (if outdated, this compiles the INF before). This is used by the [.IDPNL_TARGETS_MAIN main makefile] in order to bring up help if called with no target specified. - nmake neusr = Build and show the user guide INF. - nmake neprg = Build and show the programming guide INF. - nmake nefld = Build and show the folder HLP. . - nmake helpinf = Build this makefile in the *bin* subdirectory! - nmake neusrinf = Build the user guide INF in the *compile\netlabs\book* directory. - nmake neusrinf = Build the programming guide INF in the *compile\netlabs\book* directory. - nmake nefldhlp = Build the folder HLP file in the *compile\netlabs\help* directory. . - nmake clean = Remove the files created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .. ............................................................................. .3 src\rexx\makefile .. ............................................................................. .an IDPNL_TARGETS_REXX The following makefile pseudo targets are available for the makefile within the *src\rexx* subdirectory: .pl bold compact break=none tsize=20 - nmake [[all]] = Create POSTWPI.EXE in the *compile\netlabs\install* directory. . - nmake clean = Remove the file created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .. ............................................................................. .3 src\netlabs\makefile .. ............................................................................. .an IDPNL_TARGETS_NETLABS The following makefile pseudo targets are available for the makefile within the *src\netlabs* subdirectory: .pl bold compact break=none tsize=20 - nmake [[all]] = Copy all modified files below the *src\netlabs* directory to the *compile\netlabs* directory. . - nmake checksrc = Check only if some files have been modified. If not, the flag file *compile\srccopy.flag* is created, otherwise it is deleted. - nmake srccopy = Copy modified files anyway. . - nmake clean = Remove the flag file created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .. ............................................................................. .3 src\wis\makefile .. ............................................................................. .an IDPNL_TARGETS_WIS .at fc=red This makefile cannot be called directly. .at Instead it can only be processed by calling the main makefile by executing .sl compact - *nmake all* in the project base directory. This ensures that all other makefiles from within the *src* directory are called first which in turn ensures that all required files are available for building the WPI package. For testing purposes this makefile can called directly by specifying the symbol *CALLED=1*. The pseudo targets provided by *[=.IDPNL_TARGETS_WIS]* are described below. [=NOTE] .ul compact - Targets marked with (**) require a working internet connection for to download the EPM packages, if they are not available within the directory specified by the macro *ZIPSRCDIR* in the file *configure.in*. .at .pl bold compact break=none tsize=20 - nmake [[all]] = Downloads and unpacks files from Hobbes and builds complete Warpin package. This results in the *WarpIN* WPI package file created either in the *debug* or *release* directory, depending on the value of the *DEBUG* environment variable. (**) . - nmake inst = Like *nmake all*, but also starts Warpin to install the WPI file. (**) . - nmake remove = Quickly deinstalls all packages installed from the [=TITLE] without using the *WarpIN* GUI. This is intended for testing purposes only! See pseudo target *remove* of the [.IDPNL_TARGETS_MAIN] for further details. . - nmake prepare = Only downloads EPMBBS zip files from Hobbes and unpacks. (**) . - nmake check = Check prepared files for .ul compact - SYSxxxx errors during unpack - zero byte files, making WIC trap (fixed in newer WarpIN versions) - pkunzip2 does not unpack properly sometimes (zero byte files). .el - nmake clean = Remove the flag file created by this makefile. See the macro *FILESTOCLEAN* for a complete list. . [=NOTE] .ul compact - Directories are not removed by this pseudo target. For a complete cleanup, call *nmake clean* within the project working directory (root of the development tree). .include guide.inc .. ----------------------------------------------------------------------------- .2 Appendix: INI entries overview .. ----------------------------------------------------------------------------- .an IDPNL_APPENDIX_INIENTRIES [=TOPICS] .su V30 .. ............................................................................. .3 OS2.INI .. ............................................................................. .an IDPNL_APPENDIX_INIENTRIES_OS2INI The following entries are written to *OS2.INI*: .pl compact tsize=15 break=none .. ------------------------------------------- - Application = *NEPMD* - Key = *Language* .. - Description = Language information used by several programs. - Originator = Installation of the [=TITLE]. - Value = A [.IDPNL_APPENDIX_LANGIDS three letter language identification]. - Type = Alpha string (should be zero terminated). . .. ------------------------------------------- - Application = *NEPMD* - Key = *RootDir* .. - Description = Main installation directory used by several programs. - Originator = Installation of the [=TITLE]. - Value = A directory specification. - Type = Alpha string (should be zero terminated). . .. ------------------------------------------- - Application = *NEPMD* - Key = *UserDir* .. - Description = Main user directory - optional, defaults to RootDir'\myepm'. - Originator = Installation of the [=TITLE] if NEPMD__USERDIR__INST is set before the installation. This allows to create the user tree outside of RootDir, e.g. within the home tree. - Value = A directory specification. - Type = Alpha string (should be zero terminated). . .. .. ------------------------------------------- .. - Application .. = *recomp* .. - Key .. = *CONFIGDATA* .. .. .. - Description .. = Configuration data. .. - Originator .. = *RECOMP* utility. .. - Value .. = Internal. .. - Type .. = Binary. .. ----------------------------------------------------------------------------- .2 Appendix: Language identifiers overview .. ----------------------------------------------------------------------------- .an IDPNL_APPENDIX_LANGIDS The following language identifiers are currently used within the project: .lm 5 .pl bold compact break=none tsize=7 - eng = english - deu = deutsch (german) .. ----------------------------------------------------------------------------- .2 Appendix: Documentation comments for E functions .. ----------------------------------------------------------------------------- .an IDPNL_APPENDIX_DOCCOMMENTS [=TOPICS] .su V30 .. ............................................................................. .3 Doc comments in general .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_GENERAL All E functions provided by the [=TITLE] should be documented in the E functions reference of the INF file for the release package. In order to have this task accomplished, the following is required: .pl bold tsize=3 - The information to be put into the panels of the INF file: = This information has to be provided by the developer of the function within the .e source file within so-called documentation comments. - The generation of the panels into an appendix of the INF file: = This is done by the script *esrcscan.cmd*, which is called by the makefile generating all of the online help files. Having said this, once a developer has added the documentation comments to the respective source file [.IDPNL_APPENDIX_DOCCOMMENTS_FORMAT in correct format], the information about the function is automatically inlcuded in the functions reference. .. ............................................................................. .3 Format of doc comments .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_FORMAT The following rules apply to documentation comments: .ul - All documentation comments have to be embedded into comments for the E language, so that the *EPM macro compiler* does not see them. - For each function a set of documentation comments have to be defined, some others are optional. If required documentation comments are missing, the script reading them will display warnings when generating the reference information, but will not stop. - A documentation comment consists of the following: .ul compact - One line specifying the name of the function. This line must have the following information in one word (without spaces included): - two *@* characters - the name of the function - one *@* character - the type name of the comment (like [.IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX], [.IDPNL_APPENDIX_DOCCOMMENTS_PARM], .etc.). .el . For special comment types like [.IDPNL_APPENDIX_DOCCOMMENTS_CATEGORY] and [.IDPNL_APPENDIX_DOCCOMMENTS_PARM] another *@* character and an additional parameter (here either the category name or the name of the parameter) must be appended. Please see the descriptions about the comment types in this section for details. .el - All following lines up to the next documentation comment used as text for the INF file panel. .at fc=red This text must conform to the [.IDPNL_REQUIREMENTS_HTEXT] syntax, as this preprocessor is used for generation the online help. .at fc=black - Especially important is to take care for the characters ** __ ## [[ ]], as they are escape characters for *HyperText/2*. They to switch bold, underline and italic print of characters on and off and they create hyperlinks. In order to use those characters within the documentaion comments just repeat the character, as each escape character escapes itself. - Also make sure that no line begins with a dot, because that may be interpreted as a HyperText command. - To print text in non-formatted style, you may want to use the .FORMAT command of HyperText/2, switching formatting off and later on again. .at - The documentation comment is closed with the [.IDPNL_APPENDIX_DOCCOMMENTS_ENDMARKER], which is a line made up of two *@* characters. - Multiple comments may be spread over a source file and can include information about several functions, as long as each documentation comment is followed either by the next one or an [.IDPNL_APPENDIX_DOCCOMMENTS_ENDMARKER]. .. ............................................................................. .3 Linking to sections created by doc comments .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_LINKAGE It may be very useful to link between panels created by documentation comments. When doing this, keep in mind that the text included in these panels must be compatible to the [.IDPNL_REQUIREMENTS_HTEXT] syntax, so that a link is easily created by the following syntax: .fo off This is a link to a panel: [[. linktext as much as you want]] .fo on . where *anchorname* is the name of the anchor being set for a panel by the *.ANCHOR* command that has been generated by [.IDPNL_APPENDIX_DOCCOMMENTS_GENERAL escansrc.cmd]. The above example would look like this (here with a dead link though): This is a link to a panel: [.IDPNL_APPENDIX_DOCCOMMENTS_LINKAGE linktext as much as you want] The anchor names being used for the generated part of the online help consist of the following: .ul compact - the basename *IDPNL__EFUNC__* - the function name in uppercase characters - the type name of the comment (like [.IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX], [.IDPNL_APPENDIX_DOCCOMMENTS_PARM], .etc.) preceded by an underscore - if it is a link to a dedicated parameter section, an additional underscore plus the name of the parameter in uppercase characters. The following examples show you how to write a link in [.IDPNL_REQUIREMENTS_HTEXT] syntax, but without specifying a link text (so these examples would display the title of the linked panel instead, which would mostly not be useful in this case). Just include the link text between the anchorname (separated by a space character) and the closing square bracket: .pl tsize=3 - [[.IDPNL__EFUNC__NEPMDWRITESTRINGEA]] = links main panel of function NepmdWriteStringEa - [[.IDPNL__EFUNC__NEPMDQUERYFULLNAME__SYNTAX]] = links syntax panel of function NepmdQueryFullname - [[.IDPNL__EFUNC__NEPMDDELETESTRINGEA__PARM]] = links parameter overview panel of function NepmdDeleteStringEa - [[.IDPNL__EFUNC__NEPMDERRORMSGBOX__PARM__BOXMESSAGE]] = links panel for parameter BoxMessage of function NepmdErrorMsgBox - [[.IDPNL__EFUNC__NEPMDGETINSTVALUE__RETURNS]] = links results panel of function NepmdGetInstValue - [[.IDPNL__EFUNC__NEPMDINFO__REMARKS]] = links remarks panel of the function NepmdInfo - [[.IDPNL__EFUNC__NEPMDGETNEXTFILE__EXAMPLE]] = links example panel of the function NepmdGetNextFile [=NOTE] .ul compact - Don't forget the point when inserting the anchorname in square brackets, otherwise the name is not recognized as an anchorname. - Note: you cannot link to a panel created by the documentation comments [.IDPNL_APPENDIX_DOCCOMMENTS_PROTOTYPE] and [.IDPNL_APPENDIX_DOCCOMMENTS_CATEGORY], as these do not create a panel, but are used only to further specify information about a function to be added to other panels. .. ............................................................................. .3 PROTOTYPE .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_PROTOTYPE The prototype comment specifies the prototype being inserted in non-formatted font into the syntax panel for a given function. [=NOTE] .ul compact - The text of this comment should not be longer than one or at least as few lines, as possible. - Make sure that the names of the parameters match the names specified in the [.IDPNL_APPENDIX_DOCCOMMENTS_PARM] comments for this function, so that links can be created. *Example:* .fo off /** @@MyFunction@PROTOTYPE ResultValue = MyFunction( Parm1, Parm2, Parm3); @@ **/ .fo on .. ............................................................................. .3 SYNTAX .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX The syntax comment specifies the text to be displayed in the *Syntax* panel for the specified function. Please don't take the text in the below example too serious, your explanation for a function should be much more sensible. If you have very important remarks to state, you may want to insert these also here, but for remarks longer than one sentence you should use the optional [.IDPNL_APPENDIX_DOCCOMMENTS_REMARKS] comment and link to that from the text here in the *[=.IDPNL_APPENDIX_DOCCOMMENTS_SYNTAX]* comment. *Example:* .fo off /** @@MyFunction@SYNTAX This function intends to return valuable information and requires three parameters. @@ **/ .fo on .. ............................................................................. .3 CATEGORY .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_CATEGORY The category comment specifies the category that the specified function should be included. [=NOTE] .ul compact - This comment does not specify text, but instead requires the category name appended to the comment name. - The main source file for the online help must include a .SET command to define the title for a category, where the name of the setting must be *CATEGORY__*#categoryname#. The following example specifies the function *MyFunction()* being a member of the category *SPECIAL*: *Example:* .fo off /** @@MyFunction@CATEGORY@SPECIAL @@ **/ .fo on The title for this category must be defined in the main source file like .fo off .SET CATEGORY__SPECIAL=This is my very special category .fo on .. ............................................................................. .3 PARM .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_PARM The parameter comment specifies the information about a parameter passed to the specified function. Therefore this comment must be included for each parameter of the function. [=NOTE] .ul compact - This comment requires the parameter name appended to the comment name. - Make sure that it matches identically the parameters in the [.IDPNL_APPENDIX_DOCCOMMENTS_PROTOTYPE] comment, so that a link from the prototype to the parameter section is automatically created. *Example:* .fo off /** @@MyFunction@PARM@Parm1 This is parameter 1 for this function and passes an important value. @@MyFunction@PARM@Parm2 This is parameter 1 for this function and passes an even more important value. @@MyFunction@PARM@Parm3 This is parameter 3 for this function and passes an optional value. @@ **/ .fo on .. ............................................................................. .3 RETURNS .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_RETURNS The comment for the return value is intended for information about the return value. *Example:* .fo off /** @@MyFunction@RETURNS The function MyFunction() returns an OS/2 error code. @@ **/ .fo on .. ............................................................................. .3 REMARKS .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_REMARKS The remarks comment is optional and is intended for very special information about the function. *Example:* .fo off /** @@MyFunction@REMARKS For using the function MyFunction() some very specific details are important to know: ... @@ **/ .fo on .. ............................................................................. .3 EXAMPLE .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_EXAMPLE The examples comment is optional and is intended for to give a sample snippet for usage of the specified function. [=NOTE] .ul compact - Take care for the *HyperText/2* [.IDPNL_APPENDIX_DOCCOMMENTS_FORMAT escape characters] and other formatting issues. *Example:* .fo off /** @@MyFunction@EXAMPLE Here is an example for calling the function: .fo off ResultValue = MyFunction( Parm1, Parm2, Parm3); .fo on ... @@ **/ .fo on .. ............................................................................. .3 Documentation comment end marker .. ............................................................................. .an IDPNL_APPENDIX_DOCCOMMENTS_ENDMARKER In order to let the source scanner script know that no more documentation comments follow after the last one, just add a line with one word of two *@* characters at the end of the last documentation comment. *Example:* .fo off /** @@MyFunction@RETURNS This is the last documentation comment and has to be followed by a documentation comment end marker of two @ characters, see following line: @@ **/ .fo on