Changes between Version 10 and Version 11 of BuildingInstructions


Ignore:
Timestamp:
Sep 3, 2016, 5:14:11 AM (3 years ago)
Author:
lewisr
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • BuildingInstructions

    v10 v11  
    11== How to build ==
    22
    3 This page is completely outdated since version 1.3 of lucide. We stiched to kmk build system and everything builds out of the box.
    4 
    5  
    6 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).
    7 
    8 For build Lucide you need !OpenWatcom 1.8.
    9 To build djvu library/plugin you need GCC 3.3.5 CSD 3.
    10 
    11 === 1. setup your environment ===
    12 adjust the paths in file
    13  * \env.cmd
    14 Then execute '{{{env.cmd}}}'
    15 
    16 === 2. build the poppler library ===
    17 execute {{{'make'}}} in directories
    18 
    19  * \poppler\freetype2\src
    20  * \poppler\fc-emulate-os2\fontconfig
    21  * \poppler\mypoppler\fofi
    22  * \poppler\mypoppler\goo
    23  * \poppler\mypoppler\poppler
    24  * \poppler\mypoppler\splash
    25 
    26 Then execute '{{{\poppler\mklib.cmd}}}', \poppler\poppler.lib will be created.
    27 
    28 === 3. build the djvu library ===
    29 execute '{{{make}}}' in directory
    30  * \libdjvu
    31 
    32 === 4. build the jpeg library ===
    33 execute '{{{wmake -f makefile.wat}}}' in directory
    34  * \libjpeg
    35 
    36 === 5. build the plugins ===
    37 execute '{{{make}}}' in directories:
    38  * \Lucide\SOURCE\plugins\ludoc     (should be build first)
    39  * \Lucide\SOURCE\plugins\lupoppler
    40  * \Lucide\SOURCE\plugins\lujpeg   (useless plugin, just for fun)
    41 
    42 === 6. build the djvu plugin ===
    43 execute '{{{make -f makefile.gcc}}}' in directory
    44  * \Lucide\SOURCE\plugins\ludjvu
    45 
    46 === 7. build the Lucide GUI ===
    47 execute '{{{make}}}' in directory
    48  * \Lucide\SOURCE\gui
    49 
    50 
    51 If everything was successful the executable and all plugins are available in directory
    52  * \Lucide\BIN
     3The 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.
     4
     5
     6=== Requirements ===
     7
     8In order to build Lucide, you will need the following tools:
     9
     10  - kBuild version 0.1.5 (r2206) or later. Get it with the following command:
     11
     12      {{{svn co !http://svn.netlabs.org/repos/kbuild/trunk/kBuild -r 2206}}}
     13
     14  - 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.
     15
     16  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:
     17
     18  {{{kbuild gcc gcc-wlink gcc-wrc libc-devel poppler poppler-devel pthread pthread-devel os2tk45 os2tk45-headers os2tk45-libs}}}
     19
     20  - 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.)
     21
     22  - A recent version of the CURL library (headers and .a/.lib files).
     23
     24  - RC.EXE version 4 or 5 which should be located in a directory listed in PATH.
     25
     26  - !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:
     27
     28  http://www.os2site.com/sw/util/archiver/lxlt133.zip
     29 
     30  - poppler_dll.a (part of poppler-devel, installed above via yum or Arca Noae Package Manager).
     31
     32  - OS/2 Toolkit (installed with eCS, ArcaOS, or as above via yum or Arca Noae Package Manager).
     33
     34
     35=== Setting up the environment ===
     36
     37Copy {{{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.
     38
     39You 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.
     40
     41
     42=== Building the product ===
     43
     44Start {{{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.
     45
     46If 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:
     47
     48  ftp://ftp.netlabs.org/pub/qt4/tools/se10.zip
     49
     50
     51=== Generating Distribution Archives ===
     52
     53In 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):
     54
     55  {{{kmk packing}}}
     56
     57Note 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:
     58
     59  {{{kmk fastpacking}}}
     60
     61which will only generate the distribution archives from the existing build.
     62
     63'''IMPORTANT (for the release builder):'''
     64
     65    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.
     66
     67
     68=== Useful kBuild targets ===
     69
     70The following {{{kmk}}} targets (commands) may be of interest:
     71
     72  - clean           Cleans up the build by deleting all generated output.
     73  - uninstall       Deletes all installed files.
     74  - packing         Creates distribution archives in the output directory
     75  - fastpacking     (see GENERATING DISTRIBUTION ARCHIVES above).
     76
     77
     78=== Useful kBuild variables ===
     79
     80These 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
     81{{{LocalConfig.kmk}}}, or pass them to {{{kmk}}} as command line arguments in the form of:
     82
     83  {{{VARIABLE=VALUE}}}
     84
     85  * BUILD_TYPE
     86
     87    Build type. May be set to "release" (default) or "debug".
     88
     89    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".
     90
     91    Hint: If you use {{{se.cmd}}}, you may pass arguments to {{{env.cmd}}} and start {{{kmk}}} in one step, as in:
     92
     93  {{{se @(debug) kmk}}}
     94
     95  * KBUILD_VERBOSE
     96
     97    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.
     98
     99== Useful links ==
     100
     101  * poppler library is found on poppler.freedesktop.org
     102  * djvu library is found djvu.sourceforge.net
     103  * jpeg library www.ijg.com
     104
     105
     106== kBuild notes ==
     107
     108The following is provided by Steven Levine, and should assist with getting to know kBuild.
     109
     110
     111=== Revision history (these notes) ===
     112
     1132015-08-24 SHL Baseline
     1142016-03-05 SHL Update
     1152016-08-23 SHL Start of all T of O details
     116
     117
     118=== kBuild releases ===
     119
     120kbuild-0.1.5-p2
     121  svn !r2373
     122
     123kBuild-0.1.5-p1
     124  svn !r2336
     125
     126kBuild-0.1.5
     127  svn !r2262
     128
     129
     130=== Errata ===
     131
     132BUILD_PLATFORM must be '''os2''' ({{{gccenv.cmd}}} sets it to '''OS2'''.
     133
     134
     135=== Files and directories ===
     136
     137\sla_dev2_browse\kbuild.svn\kBuild\
     138  envos2.cmd \\
     139  header.kmk \\
     140  subheader.kmk \\
     141  footer.kmk \\
     142
     143\sla_dev2_browse\kbuild.svn\kBuild\doc\
     144  !QuickReference-kmk.txt \\
     145  !QuickReference-kBuild.txt \\
     146
     147Build directory
     148  Config.kmk \\
     149  Makefile.kmk \\
     150  Extra.kmk     (optional - see USES prop (see Odin)) \\
     151
     152
     153=== makefile debugging ===
     154
     155==== environment variables/macros ====
     156
     157  KBUILD_VERBOSE                1, 2 (anything else is max verbosity) \\
     158  KBUILD_QUIET \\
     159  KMK_OPTS_PRETTY_COMMAND_PRINTING \\
     160
     161==== command line ====
     162
     163||-d||Print lots of debugging information.||
     164||--debug[=FLAGS]||Print various types of debugging information.||
     165||a||DB_ALL||
     166||b||DB_BASIC||
     167||i||DB_BASIC | DB_IMPLICIT||
     168||j||DB_JOBS||
     169||m||DB_BASIC | DB_MAKEFILES||
     170||v||DB_BASIC | DB_VERBOSE||
     171||-p, --print-data-base||Print make's internal database.||
     172||--pretty-command-printing||Makes the command echo easier to read.||
     173
     174
     175=== Environment variables - other ===
     176
     177||BUILD_PLATFORM||must be os2 (lowercase)||
     178||KBUILD_BLD_TYPES||release profile debug, default is release||
     179||KBUILD_OSES||os2 (etc.)||
     180||KBUILD_ARCHES||x86 (etc.)||
     181
     182
     183=== envos2.cmd ===
     184
     185  \sla_dev2_browse\kbuild-0.1.5-p2\kBuild\envos2.cmd
     186
     187  Sets up
     188
     189
     190== Theory of Operation ==
     191
     192=== Passes ===
     193
     194Defined in header.kmk
     195
     196  DEFAULT_PASSES := BLDPROGS LIBRARIES DLLS BINARIES OTHERS INSTALLS \\
     197  PASSES := FETCHES PATCHES $(DEFAULT_PASSES) TESTING PACKING CLEAN NOTHING \\
     198
     199=== Legacy variables known to kBuild ===
     200
     201||PATH_KBUILD_...||replaced by KBUILD_PATH...||
     202||BUILD_...||replaced by KBUILD_...||
     203
     204
     205=== Standard variables defined by envos2.cmd ===
     206
     207||KBUILD_PATH||...\kBuild||
     208||KBUILD_BIN_PATH||...\kBuild\bin||
     209||KBUILD_TYPE||release debug profile (one of KBUILD_BLD_TYPES)||
     210||KBUILD_TARGET||win nt os2 (target platform)||
     211||KBUILD_TARGET_ARCH||||
     212||KBUILD_TARGET_CPU||||
     213||KBUILD_HOST||win nt os2 (build platform)
     214||KBUILD_HOST_ARCH||||
     215||KBUILD_HOST_CPU||||
     216
     217
     218=== TOOL_... variables ===
     219
     220 - defined in tools subdirectory as toolname.kmk (i.e. GCC3OMF.kmk)
     221 - referenced in Config.kmk templates
     222
     223
     224=== External variables used by kBuild makefiles ===
     225
     226KBUILD_... \\
     227KBUILD_QUIET \\
     228
     229PATH_OUT_BASE \\
     230
     231
     232=== Internal variables used by kBuild makefiles ===
     233
     234KBUILD_... \\
     235
     236||QUIET||@ or nothing||
     237||APPEND||kmk_builtin_append.exe||
     238||REDIRECT||kmk_redirect.exe||
     239
     240
     241=== Standard variables defined by kmk ===
     242
     243== Command line ==
     244
     245{{{
     246  Usage: kmk.exe [options] [target] ...
     247  Options:
     248    -b, -m                      Ignored for compatibility.
     249    -B, --always-make           Unconditionally make all targets.
     250    -C DIRECTORY, --directory=DIRECTORY
     251                                Change to DIRECTORY before doing anything.
     252    -d                          Print lots of debugging information.
     253    --debug[=FLAGS]             Print various types of debugging information.
     254    -e, --environment-overrides
     255                                Environment variables override makefiles.
     256    --eval=STRING               Evaluate STRING as a makefile statement.
     257    -f FILE, --file=FILE, --makefile=FILE
     258                                Read FILE as a makefile.
     259    -h, --help                  Print this message and exit.
     260    -i, --ignore-errors         Ignore errors from recipes.
     261    -I DIRECTORY, --include-dir=DIRECTORY
     262                                Search DIRECTORY for included makefiles.
     263    -j [N], --jobs[=N]          Allow N jobs at once; infinite jobs with no arg.
     264                                The default is the number of active CPUs.
     265    -k, --keep-going            Keep going when some targets can't be made.
     266    -l [N], --load-average[=N], --max-load[=N]
     267                                Don't start multiple jobs unless load is below N.
     268    -L, --check-symlink-times   Use the latest mtime between symlinks and target.
     269    -n, --just-print, --dry-run, --recon
     270                                Don't actually run any recipe; just print them.
     271    -o FILE, --old-file=FILE, --assume-old=FILE
     272                                Consider FILE to be very old and don't remake it.
     273    -p, --print-data-base       Print make's internal database.
     274    -q, --question              Run no recipe; exit status says if up to date.
     275    -r, --no-builtin-rules      Disable the built-in implicit rules.
     276    -R, --no-builtin-variables  Disable the built-in variable settings.
     277    -s, --silent, --quiet       Don't echo recipes.
     278    -S, --no-keep-going, --stop
     279                                Turns off -k.
     280    -t, --touch                 Touch targets instead of remaking them.
     281    -v, --version               Print the version number of make and exit.
     282    -w, --print-directory       Print the current directory.
     283    --no-print-directory        Turn off -w, even if it was turned on implicitly.
     284    -W FILE, --what-if=FILE, --new-file=FILE, --assume-new=FILE
     285                                Consider FILE to be infinitely new.
     286    --warn-undefined-variables  Warn when an undefined variable is referenced.
     287    --affinity=mask             Sets the CPU affinity on some hosts.
     288    --priority=1-5              Sets the process priority / nice level:
     289                                  1 = idle / max nice;
     290                                  2 = below normal / nice 10;
     291                                  3 = normal / nice 0;
     292                                  4 = high / nice -10;
     293                                  5 = realtime / nice -19;
     294    --pretty-command-printing   Makes the command echo easier to read.
     295    --print-stats               Print make statistics.
     296    --print-time[=MIN-SEC]      Print file build times starting at arg.
     297}}}