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 README file is organized as follows:
17 1. General usage of scons
18 2. *nix systems (Linux, Solaris and Mac OSX)
25 1. General usage of scons
26 =========================
32 Python >= 1.5.2 is required to run scons, but Python >= 2.2 is used by
33 lyx itself so the newer version is recommended. Python is widely
34 available on non-windows systems. Windows users can download and install
35 python from http://www.python.org.
38 scons >= 0.96.92 is needed. You can either use a full system-wide scons
39 distribution or a light-weight one (called scons-local) installed along
40 with the lyx source tree. Both variants of scons are freely available
41 from http://www.scons.org. Note that LyX source may ship with scons-base
45 These include zlib (required), qt3 or qt4 (required), gettext
46 (optional), boost (optional), aspell (optional) and Aiksaurus
47 (optional). Please refer to the system-specific sections regarding the
48 availability and installation of them.
54 The scons system resides under development/scons. You can invoke it from
55 either development/scons by, for example:
56 > cd development/scons
57 > scons frontend=qt4 qt_dir=d:/qt4 -j3 lyx
58 or from top source directory by:
59 > scons -f development/scons/SConstruct frontend=qt4 all
61 There are three types of command line options:
62 * key=value are user options. They are used to tell scons which
63 frontend to use, whether or not use included boost libraries etc.
64 You can use 'scons -h' to list all of the options.
65 * parameters start with - or -- are scons options. Useful ones include
66 -j3 (with three threads) and --config=force (force reconfiguration).
67 * others options are targets, which are lyx objects to build.
73 Here I only list important options that you will likely use. Full option
74 list with detailed description and default value can be displayed using
77 Components to use/build:
79 * frontend=qt3/qt4: qt3 is the default for all *nix systems including
80 windows cygwin. qt4 is the default for windows/mingw and windows/
81 msvc. xform and gtk are not currently supported.
82 * mode=debug/release: lyx will be built under the debug or release
83 directory, with different default build options.
84 * boost=included/system/auto: whether or not use included boost, system
85 boost, or try to detect system boost first
86 * gettext=included/system/auto
87 * nls=yes/no whether or not enable natural language support.
88 * spell=aspell/pspell/ispell/auto: spell engine
91 Paths: Most of them will be probed if not specified.
93 * qt_dir: top level directory of qt (with subdirectory include, lib)
94 * qt_lib_path: path to the qt library, use only if there is no
96 * qt_inc_path: path to qt include directory, use only if there is no
98 * extra_inc_path, extra_inc_path1, extra_lib_path, extra_lib_path1:
99 additional paths to other libraries
100 * extra_bin_path: a convenient way to add an extra path to $PATH
105 * fast_start=yes/no: if true, bypass initial configuration step and use
106 existing src/config.h
107 * load_option=yes/no: if true, load previously saved command line
108 options so you can run 'scons install' directly after a long
109 'scons all' building command.
110 * rebuild=target1,target2... By default, scons will exam all components
111 when you build lyx. You can free scons from some hard work and save
112 yourself some time by telling scons to rebuild only specified
114 * log_file: a log file of executed commands, default to scons_lyx.log
117 Installation options:
119 * prefix: directory where lyx will be installed
120 * exec_dir: directory where lyx binaries will be installed.
121 Default to $prefix/bin
122 * dest_dir: if specified, install to this directory instead of $prefix.
124 Compiler choice and flags:
125 * use_vc: use msvc instead of mingw g++ under windows
126 * CC, LINK, CPP, CXX, CCFLAGS, LDFLAGS etc: compiler commands and
127 flags. They can be set as environment variables as well.
133 You can specify one or more of the following targets:
135 Static libraries (names correspond to their directories):
136 boost, intl, support, mathed, insets, frontends, graphics,
137 controllers, client, qt3, qt4, lyxbase
139 tex2lyx, client, lyx, all = tex2lyx + client + lyx
141 po, install = all + po
145 Your built targets are put into $build_dir, which is debug (mode=debug),
146 release (mode=release) or any name specified via build_dir=name. The
147 directory structure is:
149 - common: most of the intermediate files, mostly object files
150 - libs: all static libraries
151 - qt3/qt4: lyx built with the frontend
152 - executables: lyxclient, tex2lyx, lyx
154 MSVS projects will be put to development/scons (and you should invoke
155 scons from there for this target).
158 A typical working sequence:
159 ---------------------------
161 > cd development/scons
162 > scons frontend=qt4 qt_dir=/path/to/qt4
163 (build lyx, and all necessary libraries...)
165 (build lyx, client and tex2lyx, options like qt_dir will be carried
167 > scons rebuild=lyxbase
168 (working on lyx_main.C, so only need to rebuild lyxbase)
170 (build again, only lyxbase will be rebuilt)
171 > scons fast_start=no --config=force
172 (need to regenerate src/config.h)
173 > scons prefix=/usr/site dest_dir=/install/dir
174 (lyx is built for /usr/site, but install to /install/dir)
178 2. *nix systems (Linux, Solaris and Mac OSX)
179 ============================================
181 Proper use of extra_inc_path, qt_dir etc should solve most of the
188 * install mingw with the following packages:
189 FIXME: we only need gcc/g++ and win32 api.
190 binutils-2.16.91-...tar.gz
191 gcc-core-3.4.5-...tar.gz
192 gcc-g++-3.4.5-...tar.gz
193 mingw-runtime-3.9.tar.gz
194 mingw-utils-0.3.tar.gz
197 msys-libtool-1.5.tar.bz2
200 * install the latest Qt official "open source" binary package for
203 * install iconv (libiconv):
204 Download the windows binary (libiconv-x.x.x.bin.woe32.zip) of iconv
205 from one of the GNU mirrors listed in http://www.gnu.org/prep/ftp.html.
207 You may also try gnuwin32/libiconv from
208 http://gnuwin32.sourceforge.net/packages/libiconv.htm
210 * install gettext (libintl):
211 Download the windows binary (gettext-runtime-x.x.x.bin.woe32.zip and
212 gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors
213 (e.g. http://mirrors.usc.edu/pub/gnu/gettext/) and decompress.
215 You may also try gnuwin32/libintl from
216 http://gnuwin32.sourceforge.net/packages/libintl.htm
218 * install mingw/zlib:
219 Download zlib binaries and developer files (zlib-1.2.3-bin.zip and
220 zlib-1.2.3-lib.zip) from http://gnuwin32.sourceforge.net/packages/zlib.htm .
222 * aspell: this is difficult. Everybody has his own compiled library.
223 Mine is in D:\program\Aspell-0.60.4.
225 * Open a mingw xterm, and start scons as usual.
227 Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no
228 extra_inc_path etc is needed.
234 LyX should be easy to compile, but the qt3 library in the cygwin
235 distribution does not work with the current cygwin dll (version 1.5.19-4
236 as of June 2006) due to broken threading support. You should either wait
237 for the forthcoming 1.5.20 version or install a recent snapshot from
238 http://cygwin.com/snapshots.
240 To build lyx for cygwin, you should
242 * install (using the cygwin setup program) at least the following
243 packages and all other packages pulled in by dependencies:
245 aspell grep libintl1 qt3-bin tar
246 coreutils jbigkit libintl2 qt3-devel libiconv
247 diffutils jpeg libpng python
248 gettext libintl libpng2 sed
250 * run scons as you would do under linux.
256 To build lyx with msvc, you should
259 It is recommended that you use MSVC2005 Express edition which is
260 freely available from microsoft.
262 * get windows platform SDK
263 Please follow the link in the MSVC webpage to download and configure.
264 It is important that you add SDK paths to %INCLUDE% and %LIB% in, e.g.,
265 C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat.
266 If you plan to use the MSVS IDE, you should also update the Visual C++
267 directories in VCProjectEngine.dll.express.config, as suggested in
268 http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/.
271 - download qt4 source from trolltech (not the binary version, which
272 only works with mingw)
273 - get q../free patch for qt4
274 - compile qt4 as instructed
276 * download and install the official zlib library from www.zlib.org.
278 * install iconv (libiconv):
279 Download the windows binary (libiconv-x.x.x.bin.woe32.zip) of iconv
280 from one of the GNU mirrors listed in http://www.gnu.org/prep/ftp.html.
282 You may also try gnuwin32/libiconv from
283 http://gnuwin32.sourceforge.net/packages/libiconv.htm
285 * install gettext (libintl):
286 Download the windows binary (gettext-runtime-x.x.x.bin.woe32.zip and
287 gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors
288 (e.g. http://mirrors.usc.edu/pub/gnu/gettext/) and decompress.
290 You may also try gnuwin32/libintl from
291 http://gnuwin32.sourceforge.net/packages/libintl.htm
293 * set up other optional libraries like aspell (following mingw
296 * start from msvc command prompt, use the use_vc option to build lyx.
297 You may need to use extra_inc_path etc to point to zlib paths.
299 * you can use the msvs_projects target to obtain msvc project files
300 for each lyx component.
301 - go to development/scons (important)
303 > scons [other options] msvs_projects
305 - The resulting project files will use scons to build lyx
306 - All command line options, including rebuild, can be used as usual
307 (when msvs invoke scons).
308 - To use the msvc debugger, you have to use mode=debug (default).
314 When you get an error:
316 Q. Some path is not found.
317 A, Try options such as extra_inc_path, extra_lib_path.
319 Q. A test fails (failed to find zlib etc).
320 A. Have a look at config.log.
322 Q. I get a linking error.
323 A. Get the command sequence from scons_lyx.log and see what could
324 have gone wrong. You usually only need to tweak the last linking
327 Q. Still can not figure it out.
328 A. Send an email to lyx-devel mailing list.
330 Q. Feeling too impatient/adventurous to wait for list response.
331 A. Read SConstruct and SConscript and see what went wrong. Trust me, they
332 are much easier to decipher than the autoconf/m4 files.