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 the qt4 frontend.
16 This file is organized as follows:
17 1. General usage of scons
18 2. *nix systems (Linux, Solaris and Mac OSX)
26 1. General usage of scons
27 =========================
33 Python >= 1.5.2 is required to run scons, but Python >= 2.3 is used by
34 lyx itself so the newer version is needed. Python is widely
35 available on non-windows systems. Windows users can download and install
36 python from http://www.python.org.
39 scons >= 0.96.92 is needed. You can either use a full system-wide scons
40 distribution or a light-weight one (called scons-local) installed along
41 with the lyx source tree. Both variants of scons are freely available
42 from http://www.scons.org. Note that LyX source may ship with scons-base
46 These include zlib (required), qt4 (required), gettext
47 (optional), boost (optional), aspell (optional) and Aiksaurus
48 (optional). Please refer to the system-specific sections regarding the
49 availability and installation of them.
55 The scons system resides under development/scons. You can invoke it from
56 either development/scons by, for example:
57 > cd development/scons
58 > scons frontend=qt4 qt_dir=d:/qt4 -j3 lyx
59 or from any other directory and use -f option to point to the SConstruct
63 > scons -f ../development/scons/SConstruct frontend=qt4 all
65 There are three types of command line options:
66 * key=value are user options. They are used to tell scons which
67 frontend to use, whether or not use included boost libraries etc.
68 You can use 'scons -h' to list all of the options.
69 * parameters start with - or -- are scons options. Useful ones include
70 -j3 (with three threads) and --config=force (force reconfiguration).
71 * others options are targets, which are lyx objects to build.
77 Here I only list important options that you will likely use. Full option
78 list with detailed description and default value can be displayed using
81 Components to use/build:
83 * frontend=qt4: qt4 is the only option right now.
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 * load_option=yes/no/opt1,opt2/-opt1,opt2: if true, load previously saved
111 command line options so you can run 'scons install' directly after a
112 long 'scons all' building command. You can load selected options using
113 load_option=opt1,opt2,... or exclude options using the - version of it.
114 Note that the option 'bundle' is not reloaded.
115 * rebuild=target1,target2... By default, scons will exam all components
116 when you build lyx. You can free scons from some hard work and save
117 yourself some time by telling scons to rebuild only specified
118 component(s). rebuild=no, none, yes or all can be used as well.
119 * log_file: a log file of executed commands, default to scons_lyx.log
122 Installation options:
124 * prefix: directory where lyx will be installed
125 * exec_dir: directory where lyx binaries will be installed.
126 Default to $prefix/bin
127 * DESTDIR: if specified, install to this directory instead of $prefix.
128 * version_suffix=yes/no/something : if specified, this suffix will be
129 appended to the user data directory.
130 * win_installer: if specified under windows, and if 'installer' target
131 is given, generate NSIS installer specifed as win_installer which can
132 be a full path name. The default is lyx-version-timestamp-Installer.exe
133 for a development version, and lyx-version-Installer.exe for a released
137 Compiler choice and flags:
138 * use_vc: use msvc instead of mingw g++ under windows
139 * optimization: optimization flag to use (e.g. -O2)
140 * CC, LINK, CPP, CXX, CCFLAGS, LINKFLAGS etc: compiler commands and
141 flags. Setting CCFLAGS etc will replace default flags. These variables
142 can be set as environment variables as well.
148 You can specify one or more of the following targets:
150 Static libraries (names correspond to their directories):
151 boost, intl, support, mathed, insets, frontends, graphics,
152 controllers, client, qt4, lyxbase
154 tex2lyx, client, lyx, all = tex2lyx + client + lyx
156 po, install = all + po, installer (windows only, need NSIS)
158 msvs_projects, update_po
160 Your built targets are put into $build_dir, which is debug (mode=debug),
161 release (mode=release) or any name specified via build_dir=name. The
162 directory structure is:
164 - common: most of the intermediate files, mostly object files
165 - libs: all static libraries
166 - executables: lyxclient, tex2lyx, lyx
168 MSVS projects will be put to development/scons (and you should invoke
169 scons from there for this target).
171 update_po is similar to 'cd po; make update-po' but does not generate
172 .gmo files, which is the task of the install target. Note that this
173 target is the only target that changes files (po/*.po in this case)
174 of the lyx source tree.
177 A typical working sequence:
178 ---------------------------
180 > cd development/scons
181 > scons frontend=qt4 qt_dir=/path/to/qt4
182 (build lyx, and all needed libraries...)
184 (build lyx, client and tex2lyx, options like qt_dir will be carried
186 > scons rebuild=lyxbase
187 (working on LyX.cpp, so only need to rebuild lyxbase)
189 (build again, only lyxbase will be rebuilt)
190 > scons prefix=/usr/site DESTDIR=/install/dir
191 (lyx is built for /usr/site, but install to /install/dir)
194 2. *nix systems (Linux, Solaris and Mac OSX)
195 ============================================
197 Proper use of extra_inc_path, qt_dir etc should solve most of the
204 * install mingw with the following packages:
205 binutils-2.16.91-...tar.gz
206 gcc-core-3.4.5-...tar.gz
207 gcc-g++-3.4.5-...tar.gz
208 mingw-runtime-3.9.tar.gz
209 mingw-utils-0.3.tar.gz
214 * install the latest Qt official "open source" binary package for
215 Windows/Mingw (required)
217 * install mingw/zlib (required):
218 Download zlib binaries and developer files (zlib-1.2.3-bin.zip and
219 zlib-1.2.3-lib.zip) from http://gnuwin32.sourceforge.net/packages/zlib.htm .
221 * install iconv (optional):
222 Download libiconv from http://gnuwin32.sourceforge.net/packages/libiconv.htm
223 The complete package (without source) is recommended.
225 You may also try the windows binary (libiconv-x.x.x.bin.woe32.zip) of
226 iconv from one of the GNU mirrors listed in http://www.gnu.org/prep/ftp.html.
228 * install gettext (optional):
229 Download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm
230 The complete package (without source) is recommended.
232 You may also try the windows binary (gettext-runtime-x.x.x.bin.woe32.zip
233 and gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors
234 (e.g. http://mirrors.usc.edu/pub/gnu/gettext/).
236 * install aspell (optional):
237 LyX uses aspell 0.60.4 and there is no, as of now, official windows
238 version. If you do not want to compile aspell from source by yourself,
239 your best bet is using Abdel's lyx 1.5.0svn experimental package located
240 at http://wiki.lyx.org/Windows/LyX150Experimental. The link to his
241 pre-built aspell package is http://younes.a.free.fr/Lyx-15-experimental
243 * install aiksaurus (optional):
244 Try to build aiksaurus from source (both mingw or msvc should work),
245 or look for pre-built package from the lyx 1.5.0svn experimental page.
247 * Open a mingw xterm, and start scons as usual.
249 Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no
250 extra_inc_path etc is needed.
256 LyX should be easy to compile, but you must use the most recent cygwin
257 dll (version 1.5.20-1 as of July 2006) because qt library in older
258 cygwin distribution does not work with previous versions due to broken
261 To build lyx for cygwin, you should
263 * install (using the cygwin setup program) at least the following
264 packages and all other packages pulled in by dependencies:
266 aspell gzip libiconv qt4-bin
267 aspell-dev jpeg libpng qt4-devel
269 gettext libintl1 jpeg
270 gettext-devel libintl2 python
272 * install aiksaurus (http://aiksaurus.sourceforge.net/, optional):
273 There is no cygwin package for aiksaurus, so you should build it from
274 source. However, aiksaurus builds smoothly on cygwin.
276 * run scons as you would do under linux.
278 Note: cygwin/qt does not follow the usual $qt_dir/include, $qt_dir/bin,
279 $qt_dir/lib directory structure. For example, cygwin/qt4 uses directories
280 /usr/include/qt4, /usr/lib/qt4/bin and /usr/lib/qt4/lib. If these
281 directories can not be detected automatically, use options, for example,
282 qt_dir=/usr/lib/qt4 qt_inc_path=/usr/include/qt4
288 To build lyx with msvc, you should
291 It is recommended that you use MSVC2005 Express edition which is
292 freely available from microsoft.
294 * get windows platform SDK
295 Please follow the link in the MSVC webpage to download and configure.
296 It is important that you add SDK paths to %INCLUDE% and %LIB% in, e.g.,
297 C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat.
298 If you plan to use the MSVS IDE, you should also update the Visual C++
299 directories in VCProjectEngine.dll.express.config, as suggested in
300 http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/.
303 - download qt4 source from trolltech (not the binary version, which
304 only works with mingw)
305 - get q../free patch for qt4
306 - compile qt4 as instructed
308 * download and install the official zlib library from www.zlib.org.
310 * optionally install iconv, gettext, aspell, aiksaurus following
311 the mingw instructions.
313 * start from msvc command prompt, use the use_vc option to build lyx.
314 You may need to use extra_inc_path etc to point to zlib paths.
316 * you can use the msvs_projects target to obtain msvc project files
317 for each lyx component.
318 - go to development/scons (important)
320 > scons [other options] msvs_projects
322 - The resulting project files will use scons to build lyx
323 - All command line options, including rebuild, can be used as usual
324 (when msvs invoke scons).
325 - To use the msvc debugger, you have to use mode=debug (default).
331 * Using external boost libraries (install boost libraries and use
332 option boost=system) can speed up scons' starting time a lot, since
333 the boost headers will then be considered as system headers and will
334 not be included in the dependency tree.
340 When you get an error:
342 Q. Some path is not found.
343 A, Try options such as extra_inc_path, extra_lib_path.
345 Q. A test fails (failed to find zlib etc).
346 A. Have a look at config.log.
348 Q. I get a linking error.
349 A. Get the command sequence from scons_lyx.log and see what could
350 have gone wrong. You usually only need to tweak the last linking
353 Q. Still can not figure it out.
354 A. Send an email to lyx-devel mailing list.
356 Q. Feeling too impatient/adventurous to wait for list response.
357 A. Read SConstruct and SConscript and see what went wrong. Trust me, they
358 are much easier to decipher than the autoconf/m4 files.