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 _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.

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 install on 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:

​http://www.os2site.com/sw/util/archiver/lxlt133.zip

• 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 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.

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.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, 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

• ​poppler library
• ​djvu library
• ​jpeg library

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.