== 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. 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 the command line: {{{kbuild gcc gcc-wlink gcc-wrc libc-devel poppler poppler-devel pthread pthread-devel os2tk45 os2tk45-headers os2tk45-libs}}} - 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). === 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 here: ftp://ftp.netlabs.org/pub/qt4/tools/se10.zip === 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 the{{{lng 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 is found on poppler.freedesktop.org * djvu library is found djvu.sourceforge.net * jpeg library www.ijg.com == 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. }}}