How to build
The following should provide a basic outline of the requirements and steps to get Lucide building. Help is always available on the Lucide-dev mailing list.
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
_Systemmodifier 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.
Installing via yum or Arca Noae Package Manager is recommended. Copy the following list of packages and paste into Arca Noae Package Manager's Quick install dialog or pass to
yum installon one command line:
kbuild gcc gcc-wlink gcc-wrc watcom-wlink-hll watcom-rc libc-devel poppler poppler-devel pthread pthread-devel os2tk45 os2tk45-headers os2tk45-libs exceptq-devel djvulibre-libs djvulibre-devel libjpeg libjpeg-devel
- wipfc.exe, the Watcom ipf (help file) compiler (available from the Netlabs RPM repository using ANPM or yum. Note: wipfc.exe is currently in the tools directory pending adding it to the Netlabs repository.
- The 2.0 Beta 1 Open Watcom linker (wl.exe), resource compiler (wrc.exe) and (wipfc.exe - mentioned above).
- Mapxqs.exe from the exceptq-devel package
- 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) from the Toolkit and place it in 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).
- RC.EXE version 4 or 5 which should be located in a directory listed in PATH.
- LxLite 1.3.3 or above should also be located in PATH, otherwise packing the resulting EXEs and DLLs will be disabled. You may get LxLite from here:
- poppler_dll.a (part of poppler-devel, installed above via yum or Arca Noae Package Manager).
- OS/2 Toolkit (installed with eCS, ArcaOS, or as above via yum or Arca Noae Package Manager).
- djvulibre_dll.a (and its include files which are part of djvulibre-devel, installed above via yum or Arca Noae Package Manager).
- djvulibre-libs (installed above via yum or Arca Noae Package Manager).
- jpeg.a (and its include files which are part of libjpeg-devel, installed above via yum or Arca Noae Package Manager).
- libjpeg (installed above via yum or Arca Noae Package Manager).
Setting up the environment
Copy LocalEnv.cmd.tpl to LocalEnv.cmd, adjusting 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
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.
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 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 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 using:
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. This also needs to be updated in all thelng files. 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 tobetato indicate a new development phase. Right before the release, you end the development phase by changing BUILD frombetatoGAand create a corresponding release tag in SVN.
Useful kBuild targets
The following kmk targets (commands) 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 which change the Lucide build or behavior. You may set them in the OS/2 environment, put them in your
LocalConfig.kmk, or pass them 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.cmdscript to set the build type to "debug".
Hint: If you use
se.cmd, you may pass arguments toenv.cmdand startkmkin one step, as in:
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
kBuild notes
The following is provided by Steven Levine, and should assist with getting to know kBuild.
Revision history (these notes)
2015-08-24 SHL Baseline 2016-03-05 SHL Update 2016-08-23 SHL Start of all T of O details
kBuild releases
kbuild-0.1.5-p2
svn r2373
kBuild-0.1.5-p1
svn r2336
kBuild-0.1.5
svn r2262
Errata
BUILD_PLATFORM must be os2 (gccenv.cmd sets it to OS2.
Files and directories
\sla_dev2_browse\kbuild.svn\kBuild\
envos2.cmd
header.kmk
subheader.kmk
footer.kmk
\sla_dev2_browse\kbuild.svn\kBuild\doc\
QuickReference-kmk.txt
QuickReference-kBuild.txt
Build directory
Config.kmk
Makefile.kmk
Extra.kmk (optional - see USES prop (see Odin))
makefile debugging
environment variables/macros
KBUILD_VERBOSE 1, 2 (anything else is max verbosity)
KBUILD_QUIET
KMK_OPTS_PRETTY_COMMAND_PRINTING
command line
| -d | Print lots of debugging information. |
| --debug[=FLAGS] | Print various types of debugging information. |
| a | DB_ALL |
| b | DB_BASIC |
| i | DB_BASIC | DB_IMPLICIT |
| j | DB_JOBS |
| m | DB_BASIC | DB_MAKEFILES |
| v | DB_BASIC | DB_VERBOSE |
| -p, --print-data-base | Print make's internal database. |
| --pretty-command-printing | Makes the command echo easier to read. |
Environment variables - other
| BUILD_PLATFORM | must be os2 (lowercase) |
| KBUILD_BLD_TYPES | release profile debug, default is release |
| KBUILD_OSES | os2 (etc.) |
| KBUILD_ARCHES | x86 (etc.) |
envos2.cmd
\sla_dev2_browse\kbuild-0.1.5-p2\kBuild\envos2.cmd
Sets up
Theory of Operation
Passes
Defined in header.kmk
DEFAULT_PASSES := BLDPROGS LIBRARIES DLLS BINARIES OTHERS INSTALLS
PASSES := FETCHES PATCHES $(DEFAULT_PASSES) TESTING PACKING CLEAN NOTHING
Legacy variables known to kBuild
| PATH_KBUILD_... | replaced by KBUILD_PATH... |
| BUILD_... | replaced by KBUILD_... |
Standard variables defined by envos2.cmd
| KBUILD_PATH | ...\kBuild |
| KBUILD_BIN_PATH | ...\kBuild\bin |
| KBUILD_TYPE | release debug profile (one of KBUILD_BLD_TYPES) |
| KBUILD_TARGET | win nt os2 (target platform) |
| KBUILD_TARGET_ARCH | |
| KBUILD_TARGET_CPU | |
| KBUILD_HOST | win nt os2 (build platform) |
| KBUILD_HOST_ARCH | |
| KBUILD_HOST_CPU |
TOOL_... variables
- defined in tools subdirectory as toolname.kmk (i.e. GCC3OMF.kmk)
- referenced in Config.kmk templates
External variables used by kBuild makefiles
KBUILD_...
KBUILD_QUIET
PATH_OUT_BASE
Internal variables used by kBuild makefiles
KBUILD_...
| QUIET | @ or nothing |
| APPEND | kmk_builtin_append.exe |
| REDIRECT | kmk_redirect.exe |
Standard variables defined by kmk
Command line
Usage: kmk.exe [options] [target] ...
Options:
-b, -m Ignored for compatibility.
-B, --always-make Unconditionally make all targets.
-C DIRECTORY, --directory=DIRECTORY
Change to DIRECTORY before doing anything.
-d Print lots of debugging information.
--debug[=FLAGS] Print various types of debugging information.
-e, --environment-overrides
Environment variables override makefiles.
--eval=STRING Evaluate STRING as a makefile statement.
-f FILE, --file=FILE, --makefile=FILE
Read FILE as a makefile.
-h, --help Print this message and exit.
-i, --ignore-errors Ignore errors from recipes.
-I DIRECTORY, --include-dir=DIRECTORY
Search DIRECTORY for included makefiles.
-j [N], --jobs[=N] Allow N jobs at once; infinite jobs with no arg.
The default is the number of active CPUs.
-k, --keep-going Keep going when some targets can't be made.
-l [N], --load-average[=N], --max-load[=N]
Don't start multiple jobs unless load is below N.
-L, --check-symlink-times Use the latest mtime between symlinks and target.
-n, --just-print, --dry-run, --recon
Don't actually run any recipe; just print them.
-o FILE, --old-file=FILE, --assume-old=FILE
Consider FILE to be very old and don't remake it.
-p, --print-data-base Print make's internal database.
-q, --question Run no recipe; exit status says if up to date.
-r, --no-builtin-rules Disable the built-in implicit rules.
-R, --no-builtin-variables Disable the built-in variable settings.
-s, --silent, --quiet Don't echo recipes.
-S, --no-keep-going, --stop
Turns off -k.
-t, --touch Touch targets instead of remaking them.
-v, --version Print the version number of make and exit.
-w, --print-directory Print the current directory.
--no-print-directory Turn off -w, even if it was turned on implicitly.
-W FILE, --what-if=FILE, --new-file=FILE, --assume-new=FILE
Consider FILE to be infinitely new.
--warn-undefined-variables Warn when an undefined variable is referenced.
--affinity=mask Sets the CPU affinity on some hosts.
--priority=1-5 Sets the process priority / nice level:
1 = idle / max nice;
2 = below normal / nice 10;
3 = normal / nice 0;
4 = high / nice -10;
5 = realtime / nice -19;
--pretty-command-printing Makes the command echo easier to read.
--print-stats Print make statistics.
--print-time[=MIN-SEC] Print file build times starting at arg.
