Changes between Version 10 and Version 11 of BuildingInstructions

Timestamp:

Sep 3, 2016, 5:14:11 AM (8 years ago)

Author:

Lewis Rosenthal

Comment:

Complete re-write of this page, concurrent with the 1.3.6 release cycle

BuildingInstructions

@@ -1 +1 @@
 == How to build ==
 
-This page is completely outdated since version 1.3 of lucide. We stiched to kmk build system and everything builds out of the box.
-
- 
-First, you need Borland's make for OS/2 for makefile processing. (updating makefiles to work with !OpenWatcom is on our !ToDo list). You may download Borland make and implib here - ftp://weird.da.ru/eros2/borland-tools-os2.zip. Store them in a separate directory (e.g. \tools).
-
-For build Lucide you need !OpenWatcom 1.8.
-To build djvu library/plugin you need GCC 3.3.5 CSD 3.
-
-=== 1. setup your environment ===
-adjust the paths in file
- * \env.cmd
-Then execute '{{{env.cmd}}}'
-
-=== 2. build the poppler library ===
-execute {{{'make'}}} in directories
-
- * \poppler\freetype2\src
- * \poppler\fc-emulate-os2\fontconfig
- * \poppler\mypoppler\fofi
- * \poppler\mypoppler\goo
- * \poppler\mypoppler\poppler
- * \poppler\mypoppler\splash
-
-Then execute '{{{\poppler\mklib.cmd}}}', \poppler\poppler.lib will be created.
-
-=== 3. build the djvu library ===
-execute '{{{make}}}' in directory
- * \libdjvu
-
-=== 4. build the jpeg library ===
-execute '{{{wmake -f makefile.wat}}}' in directory
- * \libjpeg
-
-=== 5. build the plugins ===
-execute '{{{make}}}' in directories:
- * \Lucide\SOURCE\plugins\ludoc     (should be build first)
- * \Lucide\SOURCE\plugins\lupoppler
- * \Lucide\SOURCE\plugins\lujpeg   (useless plugin, just for fun)
-
-=== 6. build the djvu plugin ===
-execute '{{{make -f makefile.gcc}}}' in directory
- * \Lucide\SOURCE\plugins\ludjvu
-
-=== 7. build the Lucide GUI ===
-execute '{{{make}}}' in directory
- * \Lucide\SOURCE\gui
-
-
-If everything was successful the executable and all plugins are available in directory
- * \Lucide\BIN
+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}}}. 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.
+}}}