1 =========================
2 Building LyX with SCons
3 =========================
8 The GNU Build System (autoconf, automake and make) has been used to build
9 and distribute lyx. These de facto *nix tools are readily available and
10 widely supported on the *nix systems, but not so under windows. They are
11 not necessarily easy to use and maintain (at least to non-m4 experts)
12 either. Because of these, a scons (http://www.scons.org) build system has
13 been set up as an alternative way to build lyx. As of writing, this system
14 only supports qt3 and qt4 frontends.
16 This file is organized as follows:
17 1. General usage of scons
18 2. *nix systems (Linux, Solaris and Mac OSX)
22 6. Other versions of lyx (1.4.x)
27 1. General usage of scons
28 =========================
34 Python >= 1.5.2 is required to run scons, but Python >= 2.3 is used by
35 lyx itself so the newer version is needed. Python is widely
36 available on non-windows systems. Windows users can download and install
37 python from http://www.python.org.
40 scons >= 0.96.92 is needed. You can either use a full system-wide scons
41 distribution or a light-weight one (called scons-local) installed along
42 with the lyx source tree. Both variants of scons are freely available
43 from http://www.scons.org. Note that LyX source may ship with scons-base
47 These include zlib (required), qt3 or qt4 (required), gettext
48 (optional), boost (optional), aspell (optional) and Aiksaurus
49 (optional). Please refer to the system-specific sections regarding the
50 availability and installation of them.
56 The scons system resides under development/scons. You can invoke it from
57 either development/scons by, for example:
58 > cd development/scons
59 > scons frontend=qt4 qt_dir=d:/qt4 -j3 lyx
60 or from top source directory by:
61 > scons -f development/scons/SConstruct frontend=qt4 all
63 There are three types of command line options:
64 * key=value are user options. They are used to tell scons which
65 frontend to use, whether or not use included boost libraries etc.
66 You can use 'scons -h' to list all of the options.
67 * parameters start with - or -- are scons options. Useful ones include
68 -j3 (with three threads) and --config=force (force reconfiguration).
69 * others options are targets, which are lyx objects to build.
75 Here I only list important options that you will likely use. Full option
76 list with detailed description and default value can be displayed using
79 Components to use/build:
81 * frontend=qt3/qt4: qt3 is the default for all *nix systems including
82 windows cygwin. qt4 is the default for windows/mingw and windows/
83 msvc. xform and gtk are not currently supported.
84 * mode=debug/release: lyx will be built under the debug or release
85 directory, with different default build options.
86 * boost=included/system/auto: whether or not use included boost, system
87 boost, or try to detect system boost first. Note that boost=included
88 is safer if system boost has a different version from the included
90 * gettext=included/system/auto
91 * nls=yes/no whether or not enable natural language support.
92 * spell=aspell/pspell/ispell/auto: spell engine
95 Paths: Most of them will be probed if not specified.
97 * qt_dir: top level directory of qt (with at least subdirectory bin
98 containing commands uic and moc)
99 * qt_lib_path: path to the qt library, use only if there is no
101 * qt_inc_path: path to qt include directory, use only if there is no
103 * extra_inc_path, extra_inc_path1, extra_lib_path, extra_lib_path1:
104 additional paths to other libraries
105 * extra_bin_path: a convenient way to add an extra path to $PATH
110 * fast_start=yes/no: if true, bypass initial configuration step and use
111 existing src/config.h
112 * load_option=yes/no/opt1,opt2/-opt1,opt2: if true, load previously saved
113 command line options so you can run 'scons install' directly after a
114 long 'scons all' building command. You can load selected options using
115 load_option=opt1,opt2,... or exclude options using the - version of it.
116 * rebuild=target1,target2... By default, scons will exam all components
117 when you build lyx. You can free scons from some hard work and save
118 yourself some time by telling scons to rebuild only specified
120 * log_file: a log file of executed commands, default to scons_lyx.log
123 Installation options:
125 * prefix: directory where lyx will be installed
126 * exec_dir: directory where lyx binaries will be installed.
127 Default to $prefix/bin
128 * dest_dir: if specified, install to this directory instead of $prefix.
131 Compiler choice and flags:
132 * use_vc: use msvc instead of mingw g++ under windows
133 * optimization: optimization flag to use (e.g. -O2)
134 * CC, LINK, CPP, CXX, CCFLAGS, LINKFLAGS etc: compiler commands and
135 flags. Setting CCFLAGS etc will replace default flags. These variables
136 can be set as environment variables as well.
142 You can specify one or more of the following targets:
144 Static libraries (names correspond to their directories):
145 boost, intl, support, mathed, insets, frontends, graphics,
146 controllers, client, qt3, qt4, lyxbase
148 tex2lyx, client, lyx, all = tex2lyx + client + lyx
150 po, install = all + po
154 Your built targets are put into $build_dir, which is debug (mode=debug),
155 release (mode=release) or any name specified via build_dir=name. The
156 directory structure is:
158 - common: most of the intermediate files, mostly object files
159 - libs: all static libraries
160 - qt3 etc: lyx executable built with the frontend
161 - executables: lyxclient, tex2lyx, lyx
163 MSVS projects will be put to development/scons (and you should invoke
164 scons from there for this target).
167 A typical working sequence:
168 ---------------------------
170 > cd development/scons
171 > scons frontend=qt4 qt_dir=/path/to/qt4
172 (build lyx, and all needed libraries...)
174 (build lyx, client and tex2lyx, options like qt_dir will be carried
176 > scons rebuild=lyxbase
177 (working on lyx_main.C, so only need to rebuild lyxbase)
179 (build again, only lyxbase will be rebuilt)
180 > scons fast_start=no --config=force
181 (need to regenerate src/config.h)
182 > scons prefix=/usr/site dest_dir=/install/dir
183 (lyx is built for /usr/site, but install to /install/dir)
186 2. *nix systems (Linux, Solaris and Mac OSX)
187 ============================================
189 Proper use of extra_inc_path, qt_dir etc should solve most of the
196 * install mingw with the following packages:
197 binutils-2.16.91-...tar.gz
198 gcc-core-3.4.5-...tar.gz
199 gcc-g++-3.4.5-...tar.gz
200 mingw-runtime-3.9.tar.gz
201 mingw-utils-0.3.tar.gz
206 * install the latest Qt official "open source" binary package for
207 Windows/Mingw (required)
209 * install mingw/zlib (required):
210 Download zlib binaries and developer files (zlib-1.2.3-bin.zip and
211 zlib-1.2.3-lib.zip) from http://gnuwin32.sourceforge.net/packages/zlib.htm .
213 * install iconv (optional):
214 Download libiconv from http://gnuwin32.sourceforge.net/packages/libiconv.htm
215 The complete package (without source) is recommended.
217 You may also try the windows binary (libiconv-x.x.x.bin.woe32.zip) of
218 iconv from one of the GNU mirrors listed in http://www.gnu.org/prep/ftp.html.
220 * install gettext (optional):
221 Download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm
222 The complete package (without source) is recommended.
224 You may also try the windows binary (gettext-runtime-x.x.x.bin.woe32.zip
225 and gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors
226 (e.g. http://mirrors.usc.edu/pub/gnu/gettext/).
228 * install aspell (optional):
229 LyX uses aspell 0.60.4 and there is no, as of now, official windows
230 version. If you do not want to compile aspell from source by yourself,
231 your best bet is using Abdel's lyx 1.5.0svn experimental package located
232 at http://wiki.lyx.org/Windows/LyX150Experimental. The link to his
233 pre-built aspell package is http://younes.a.free.fr/Lyx-15-experimental
235 * install aiksaurus (optional):
236 Try to build aiksaurus from source (both mingw or msvc should work),
237 or look for pre-built package from the lyx 1.5.0svn experimental page.
239 * Open a mingw xterm, and start scons as usual.
241 Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no
242 extra_inc_path etc is needed.
248 LyX should be easy to compile, but the qt3 library in the cygwin
249 distribution does not work with the current cygwin dll (version 1.5.19-4
250 as of June 2006) due to broken threading support. You should either wait
251 for the forthcoming 1.5.20 version or install a recent snapshot from
252 http://cygwin.com/snapshots.
254 To build lyx for cygwin, you should
256 * install (using the cygwin setup program) at least the following
257 packages and all other packages pulled in by dependencies:
259 aspell grep libintl1 qt3-bin tar
260 coreutils jbigkit libintl2 qt3-devel libiconv
261 diffutils jpeg libpng python
262 gettext libintl libpng2 sed
264 * run scons as you would do under linux.
266 Note: cygwin/qt does not follow the usual $qt_dir/include, $qt_dir/bin,
267 $qt_dir/lib directory structure. For example, cygwin/qt3 uses directories
268 /usr/include/qt3, /usr/lib/qt3/bin and /usr/lib/qt3/lib. If these
269 directories can not be detected automatically, use options, for example,
270 qt_dir=/usr/lib/qt3 qt_inc_path=/usr/include/qt3
277 To build lyx with msvc, you should
280 It is recommended that you use MSVC2005 Express edition which is
281 freely available from microsoft.
283 * get windows platform SDK
284 Please follow the link in the MSVC webpage to download and configure.
285 It is important that you add SDK paths to %INCLUDE% and %LIB% in, e.g.,
286 C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat.
287 If you plan to use the MSVS IDE, you should also update the Visual C++
288 directories in VCProjectEngine.dll.express.config, as suggested in
289 http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/.
292 - download qt4 source from trolltech (not the binary version, which
293 only works with mingw)
294 - get q../free patch for qt4
295 - compile qt4 as instructed
297 * download and install the official zlib library from www.zlib.org.
299 * optionally install iconv, gettext, aspell, aiksaurus following
300 the mingw instructions.
302 * start from msvc command prompt, use the use_vc option to build lyx.
303 You may need to use extra_inc_path etc to point to zlib paths.
305 * you can use the msvs_projects target to obtain msvc project files
306 for each lyx component.
307 - go to development/scons (important)
309 > scons [other options] msvs_projects
311 - The resulting project files will use scons to build lyx
312 - All command line options, including rebuild, can be used as usual
313 (when msvs invoke scons).
314 - To use the msvc debugger, you have to use mode=debug (default).
317 6. Other versions of lyx (1.4.x)
318 ================================
320 The scons build system is not yet distributed with lyx1.4.x. Support for
321 the qt2 frontend of lyx1.4.x is, however, added to the trunk (1.5.x). If
322 you have checked out both 1.4.x and the trunk, you can build lyx 1.4.x
323 using commands similar to
326 > scons -f ../lyx-1.5.x/development/scons/SConstruct
328 Note that lyx 1.4.x does not use the latest version of the boost library
329 so option boost=included is recommended.
335 * Using external boost libraries (install boost libraries and use
336 option boost=system) can speed up scons' starting time a lot, since
337 the boost headers will then be considered as system headers and will
338 not be included in the dependency tree.
344 When you get an error:
346 Q. Some path is not found.
347 A, Try options such as extra_inc_path, extra_lib_path.
349 Q. A test fails (failed to find zlib etc).
350 A. Have a look at config.log.
352 Q. I get a linking error.
353 A. Get the command sequence from scons_lyx.log and see what could
354 have gone wrong. You usually only need to tweak the last linking
357 Q. Still can not figure it out.
358 A. Send an email to lyx-devel mailing list.
360 Q. Feeling too impatient/adventurous to wait for list response.
361 A. Read SConstruct and SConscript and see what went wrong. Trust me, they
362 are much easier to decipher than the autoconf/m4 files.