source: trunk/README.DEV @ 574

Last change on this file since 574 was 574, checked in by Gregg Young, 5 years ago

Updated readme.dev to hopefully reflect reality. Since we talk about se.cmd in this readme I am adding se.cmd to the tools directory for easy access.

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