source: trunk/README.DEV

Last change on this file was 701, checked in by Gregg Young, 3 years ago

Updated make files and documentation for 1.41 GA

File size: 6.8 KB
Line 
1This file contains instructions on building Lucide.
2
3
4
5REQUIREMENTS
6
7In order to build Lucide, you will need the following tools:
8
9  - kBuild version 0.1.998 or later. Get it from the netlabs-rel RPM repository
10    either use ANPM or YUM install kbuild
11     
12  - GCC compiler version 4.9.2 for OS/2 and the patched OpenWatcom
13    linker. The GCC compiler must be set up to use the OpenWatcom linker for
14    linking. Note that GCC 4.4.4 is known to have problems with the _System
15    modifier and is not suitable for building Lucide SOM DLLs for this reason.
16
17      If you do not have a working GCC environment with the above requirements, it
18      is recommended that you use the ANPM to install GCC 4.9.2 distribution from
19      the Netlabs RPM repository. Follow the installation instructions contained
20      in the README file to set up the GCC environment.
21   
22  - The 2.0 Beta 1 or later  Open Watcom linker (wl.exe), resource compiler
23    (wrc.exe) and the ipf (help file) compiler (wipfc.exe).
24   
25  - Mapxqs.exe from the exceptq-devel package
26 
27      Exceptq-devel, Watcom-Wlink-hll, Watcom-rc and Watcom-ipfc are available
28      from the Netlabs RPM repository using ANPM or the appropriate yum commands.
29      Note wipfc.exe is currently also in the tools directory.
30
31  - SOM SDK 2.x. The one that is part of the OS/2 Tooklit version 4.5 is known
32    to work and recommended. Note that installing the Toolkit is not required
33    (though it will also work) -- you may simply extract the "som" subdirectory
34    (with all its contents) out of the Toolkit and place it to some directory.
35    You don't need to put any statements in CONFIG.SYS in this case.
36   
37  - A recent version of the CURL library (headers and .a/.lib files). libcurl-devel
38    and curl-debug are available on the Netlabs RPM repository
39
40  - LxLite 1.3.9 or above should also be located in PATH, otherwise packing the
41    resulting EXEs and DLLs will be disabled. Lxlite is available on the
42    netlabs-rel RPM repository.
43 
44  - poppler_dll.a.and its include files which are part of poppler-devl
45  - poppler 0.59.0
46 
47      yum install poppler poppler-devl   from http://rpm.netlabs.org/release
48     
49  - djvulibre_dll.a.and its include files which are part of djvulibre-devl
50  - djvulibre-libs
51 
52      yum install djvulibre-libs djvulibre-devl  from http://rpm.netlabs.org/release   
53
54  - jpeg_dll.a and its include files which are part of libjpeg-devl
55  - libjpeg
56 
57      yum install libjpeg libjpeg-devl   from http://rpm.netlabs.org/release
58 
59  - GBMDLL and GBM-DEVEL also from the netlabs RPM repository.   
60
61SETTING UP THE ENVIRONMENT
62
63Copy "LocalEnv.cmd.tpl" to "LocalEnv.cmd" and adjust the copy to match your
64environment. Each option in "LocalEnv.cmd.tpl" has a comment describing what it
65does.
66
67You may also want to adjust the configuration of the Lucide build according to
68your needs. To do so, copy "LocalConfig.kmk.tpl" to "LocalConfig.kmk" and adjust
69the copy to match your requirements. Each option in "LocalConfig.kmk.tpl" has a
70comment describing what it does.
71
72
73BUILDING THE PRODUCT
74
75Now, start "env.cmd" to setup the environment and type "kmk" in the root
76directory of the Lucide source tree to start kBuild and build the release
77version of Lucide and all plugins. Note kmk runs one job per processor
78by default. This creates a race condition when building lucide with unpredictable
79results. To prevent this problem you need to use kmk -j1 or kmk --jobs=1
80
81If you are a developer, you may prefer to use the "se.cmd" script instead of
82starting "env.cmd" in each new shell. This script will allow you to run "kmk"
83in the correct environment from any directory inside the Lucide source tree by
84simply typing "se kmk" (se kmk -j1) in that directory. This is especially handy
85if you use e.g. File Commander as your development IDE. The "se.cmd" script can
86be found in the tools directory.
87
88Copysyms.cmd copies the sym and xqs files to the bin directory for testing from
89there. It is not necessary to run it for releases as the PACKING logic packs
90the correct version.
91
92GENERATING DISTRIBUTION ARCHIVES
93
94In order to generate WPI and ZIP distribution archives in the output directory,
95issue the following command in the root of the source tree (prefixed with "se"
96if you use it):
97
98  kmk -j1 DEFINES - Updates the def files with the settings from Config.kmk
99  kmk -j1 PACKING - Both are case sensitive
100 
101Note that this command will perform a complete cleanup before packing, to make
102sure everything is rebuilt from scratch. For testing purposes, you may omit
103the cleanup pass by invoking the "kmk fastpacking" which will only generate
104the distribution archives from the existing build.
105
106IMPORTANT (for the release builder):
107
108    Do not forget to update VERSION, GBMVERSION (if appropriate), BUILD/WPIBUILD
109    VERSIONDATE, VERSIONTIME and BUILDMACHINE in Config.kmk before running
110    kmk -j1 DEFINES. Note that you should immediately increase the version number
111    in SVN after the release (after tagging the SVN trunk with the release tag)
112    and set BUILD to "beta" to indicate a new development phase. Right before
113    the release, you end the development phase by changing BUILD from "beta"
114    to "GA" and create a corresponding release tag in SVN.
115   
116    The version also needs to be updated in the lng files. The build level
117    strings in the def files also need to be updated using kmk -j1 DEFINES.
118
119
120USEFUL KBUILD TARGETS
121
122The following kmk targets may be of interest:
123
124  - clean           Cleans up the build by deleting all generated output.
125  - uninstall       Deletes all installed files.
126  - DEFINES         Builds the def files from the Config.kmk and the def.tpl files
127  - PACKING,        Creates distribution archives in the output directory
128    fastpacking     (see GENERATING DISTRIBUTION ARCHIVES above).
129
130
131
132USEFUL KBUILD VARIABLES
133
134These are the frequently used variables that change the Lucide build or
135behavior. You may set them in the OS/2 environment or put to your
136"LocalConfig.kmk" or pass to "kmk" as command line arguments in the form of
137"VARIABLE=VALUE".
138
139  * BUILD_TYPE
140
141    Build type. May be set to "release" (default) or "debug".
142
143    Note that you may also pass "debug" or "release" as the first argument to
144    the "env.cmd" script to set the build type to "debug".
145
146    Hint: If you use "se.cmd", you may pass arguments to "env.cmd" and start
147    "kmk" in one step, like that: "se @(debug) kmk".
148
149  * KBUILD_VERBOSE
150
151    Level of kBuild verbosity, 1 to 3 (default is nothing which means almost
152    quiet). The highest level will make kBuild print every command it executes
153    which is useful when something does not work like you want.
154
155
156USEFUL LINKS
157
158  * poppler library is found on poppler.freedesktop.org
159  * djvu library is found djvu.sourceforge.net
160  * jpeg library www.ijg.com
Note: See TracBrowser for help on using the repository browser.