This file contains instructions on building Lucide. REQUIREMENTS In order to build Lucide, you will need the following tools: - kBuild version 0.1.5 (r2206) or later. Get it with the following command: svn co http://svn.netlabs.org/repos/kbuild/trunk/kBuild -r 2206 - GCC compiler version 4.9.2 for OS/2 and the patched OpenWatcom linker. The GCC compiler must be set up to use the OpenWatcom linker for linking. Note that GCC 4.4.4 is known to have problems with the _System modifier and is not suitable for building Lucide SOM DLLs for this reason. If you do not have a working GCC environment with the above requirements, it is recommended that you use the ANPM to install GCC 4.9.2 distribution from the Netlabs RPM repository. Follow the installation instructions contained in the README file to set up the GCC environment. - The 2.0 Beta 1 Open Watcom linker (wl.exe), resource compiler (wrc.exe) and the ipf (help file) compiler (wipfc.exe). - Mapxqs.exe for the exceptq-devel package Exceptq-devel, Watcom-Wlink-hll, Watcom-rc and Watcom-ipfc are available from the Netlabs RPM repository using ANPM or the appropriate yum commands. Note wipfc.exe is currently in the tools directory pending adding it to the netlabs repository - SOM SDK 2.x. The one that is part of the OS/2 Tooklit version 4.5 is known to work and recommended. Note that installing the Toolkit is not required (though it will also work) -- you may simply extract the "som" subdirectory (with all its contents) out of the Toolkit and place it to some directory. You don't need to put any statements in CONFIG.SYS in this case. - A recent version of the CURL library (headers and .a/.lib files). libcurl-devel and curl-debug are available on the Netlabs RPM repository - LxLite 1.3.3 or above should also be located in PATH, otherwise packing the resulting EXEs and DLLs will be disabled. You can take LxLite here: http://www.os2site.com/sw/util/archiver/lxlt133.zip - poppler_dll.a.and its include files which are part of poppler-devl - poppler yum install poppler poppler-devl from http://rpm.netlabs.org/release - djvulibre_dll.a.and its include files which are part of djvulibre-devl - djvulibre-libs yum install djvulibre-libs djvulibre-devl from http://rpm.netlabs.org/release - jpeg.a.and its include files which are part of libjpeg-devl - libjpeg yum install libjpeg libjpeg-devl from http://rpm.netlabs.org/release SETTING UP THE ENVIRONMENT Copy "LocalEnv.cmd.tpl" to "LocalEnv.cmd" and adjust the copy to match your environment. Each option in "LocalEnv.cmd.tpl" has a comment describing what it does. You may also want to adjust the configuration of the Lucide build according to your needs. To do so, copy "LocalConfig.kmk.tpl" to "LocalConfig.kmk" and adjust the copy to match your requirements. Each option in "LocalConfig.kmk.tpl" has a comment describing what it does. BUILDING THE PRODUCT Now, start "env.cmd" to setup the environment and type "kmk" in the root directory of the Lucide source tree to start kBuild and build the release version of Lucide and all plugins. Note kmk runs one job per processor by default. This creates a race condition when building lucide with unpredictable results. To prevent this problem you need to use kmk -j1 or kmk --jobs=1 If you are a developer, you may prefer to use the "se.cmd" script instead of starting "env.cmd" in each new shell. This script will allow you to run "kmk" in the correct environment from any directory inside the Lucide source tree by simply typing "se kmk" (se kmk -j1) in that directory. This is especially handy if you use e.g. File Commander as your development IDE. The "se.cmd" script may be obtained from: Can be found in the tools directory. GENERATING DISTRIBUTION ARCHIVES In order to generate WPI and ZIP distribution archives in the output directory, issue the following command in the root of the source tree (prefixed with "se" if you use it): kmk packing Note that this command will perform a complete cleanup before packing, to make sure everything is rebuilt from scratch. For testing purposes, you may omit the cleanup pass by invoking the "kmk fastpacking" which will only generate the distribution archives from the existing build. IMPORTANT (for the release builder): Do not forget to update VERSION, BUILD/WPIBUILD and VERSIONDATE in Config.kmk. Note that you should immediately increase the version number in SVN after the release (after tagging the SVN trunk with the release tag) and set BUILD to "beta" to indicate a new development phase. Right before the release, you end the development phase by changing BUILD from "beta" to "GA" and create a corresponding release tag in SVN. The version also needs to be updated in the lng files. The build level strings in the def files also need to be updated. USEFUL KBUILD TARGETS The following kmk targets may be of interest: - clean Cleans up the build by deleting all generated output. - uninstall Deletes all installed files. - packing, Creates distribution archives in the output directory fastpacking (see GENERATING DISTRIBUTION ARCHIVES above). USEFUL KBUILD VARIABLES These are the frequently used variables that change the Lucide build or behavior. You may set them in the OS/2 environment or put to your "LocalConfig.kmk" or pass to "kmk" as command line arguments in the form of "VARIABLE=VALUE". * BUILD_TYPE Build type. May be set to "release" (default) or "debug". Note that you may also pass "debug" or "release" as the first argument to the "env.cmd" script to set the build type to "debug". Hint: If you use "se.cmd", you may pass arguments to "env.cmd" and start "kmk" in one step, like that: "se @(debug) kmk". * KBUILD_VERBOSE Level of kBuild verbosity, 1 to 3 (default is nothing which means almost quiet). The highest level will make kBuild print every command it executes which is useful when something does not work like you want. USEFUL LINKS * poppler library is found on poppler.freedesktop.org * djvu library is found djvu.sourceforge.net * jpeg library www.ijg.com