tufte layout files:
[lyx.git] / INSTALL.scons
1 =========================
2 Building LyX with SCons
3 =========================
5 July, 2006
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)
19 3. Windows/mingw
20 4. Windows/cygwin
21 5. Windows/msvc
22 6. Tips and hints
23 7. Troubleshooting
26 1. General usage of scons
27 =========================
29 Prerequisites:
30 --------------
32 * Python:
33   Python >= 2.6.0 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.
38 * SCons:
39   scons >= 1.1.0 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
43   in the near future.
45 * Other libraries:
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.
52 Start scons:
53 ------------
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
60 file:
61   > mkdir build
62   > cd build
63   > scons -f ../development/scons/SConstruct frontend=qt4 all
64 If you are tired of typing development/scons/SConstruct, you can link 
65 development/scons/SConstruct to the top source directory and use this
66 SConstruct file.
68 There are three types of command line options:
69   * key=value are user options. They are used to tell scons which
70     frontend to use, whether or not use included boost libraries etc.
71     You can use 'scons -h' to list all of the options.
72   * parameters start with - or -- are scons options. Useful ones include
73     -j3 (with three threads) and --config=force (force reconfiguration).
74   * others options are targets, which are lyx objects to build.
77 User Options:
78 -------------
80 Here I only list important options that you will likely use. Full option
81 list with detailed description and default value can be displayed using
82 command 'scons -h'.
84 Components to use/build:
86   * frontend=qt4: qt4 is the only option right now.
87   * mode=debug/release: lyx will be built under the debug or release
88     directory, with different default build options.
89   * boost=included/system/auto: whether or not use included boost, system
90     boost, or try to detect system boost first. Note that boost=included
91     is safer if system boost has a different version from the included
92     one.
93   * gettext=included/system/auto
94   * nls=yes/no whether or not enable natural language support.
95   * spell=aspell/auto: spell engine
98 Paths: Most of them will be probed if not specified.
100   * qt_dir: top level directory of qt (with at least subdirectory bin
101     containing commands uic and moc)
102   * qt_lib_path: path to the qt library, use only if there is no
103     $qt_dir/lib
104   * qt_inc_path: path to qt include directory, use only if there is no
105     $qt_dir/include
106   * extra_inc_path, extra_inc_path1, extra_lib_path, extra_lib_path1:
107     additional paths to other libraries
108   * extra_bin_path: a convenient way to add an extra path to $PATH
111 Convenience options:
113   * load_option=yes/no/opt1,opt2/-opt1,opt2: if true, load previously saved
114     command line options so you can run 'scons install' directly after a
115     long 'scons all' building command. You can load selected options using
116     load_option=opt1,opt2,... or exclude options using the - version of it.
117     Note that the option 'bundle' is not reloaded.
118   * rebuild=target1,target2... By default, scons will exam all components
119     when you build lyx. You can free scons from some hard work and save
120     yourself some time by telling scons to rebuild only specified
121     component(s). rebuild=no, none, yes or all can be used as well.
122   * log_file: a log file of executed commands, default to scons_lyx.log
125 Installation options:
127   * prefix: directory where lyx will be installed
128   * exec_dir: directory where lyx binaries will be installed.
129     Default to $prefix/bin
130   * DESTDIR: if specified, install to this directory instead of $prefix.
131   * version_suffix=yes/no/something : if specified, this suffix will be 
132     appended to the user data directory.
133   * win_installer: if specified under windows, and if 'installer' target
134     is given, generate NSIS installer specifed as win_installer which can 
135     be a full path name. The default is lyx-version-timestamp-Installer.exe
136     for a development version, and lyx-version-Installer.exe for a released
137     version.
140 Compiler choice and flags:
141   * use_vc: use msvc instead of mingw g++ under windows
142   * optimization: optimization flag to use (e.g. -O2)
143   * CC, LINK, CPP, CXX, CCFLAGS, LINKFLAGS etc: compiler commands and
144     flags. Setting CCFLAGS etc will replace default flags. These variables
145     can be set as environment variables as well.
148 Targets:
149 --------
151 You can specify one or more of the following targets:
153   Static libraries (names correspond to their directories):
154     boost, intl, support, mathed, insets, frontends, graphics,
155     controllers, client, qt4, lyxbase
156   Programs:
157     tex2lyx, client, lyx, all = tex2lyx + client + lyx
158   Installation:
159     po, install = all + po, installer (windows only, need NSIS)
160   Misc:
161     msvs_projects, update_po
163 Your built targets are put into $build_dir, which is debug (mode=debug),
164 release (mode=release) or any name specified via build_dir=name. The
165 directory structure is:
166   $build_dir
167     - common: most of the intermediate files, mostly object files
168     - libs: all static libraries
169     - executables: lyxclient, tex2lyx, lyx
171 MSVS projects will be put to development/scons (and you should invoke
172 scons from there for this target).
174 update_po is similar to 'cd po; make update-po' but does not generate
175 .gmo files, which is the task of the install target. Note that this 
176 target is the only target that changes files (po/*.po in this case)
177 of the lyx source tree.
180 A typical working sequence:
181 ---------------------------
183   > cd development/scons
184   > scons frontend=qt4 qt_dir=/path/to/qt4
185     (build lyx, and all needed libraries...)
186   > scons all -j3
187     (build lyx, client and tex2lyx, options like qt_dir will be carried
188     over here)
189   > scons rebuild=lyxbase
190     (working on LyX.cpp, so only need to rebuild lyxbase)
191   > scons
192     (build again, only lyxbase will be rebuilt)
193   > scons prefix=/usr/site DESTDIR=/install/dir
194     (lyx is built for /usr/site, but install to /install/dir)
197 2. *nix systems (Linux, Solaris and Mac OSX)
198 ============================================
200 Proper use of extra_inc_path, qt_dir etc should solve most of the
201 problems.
204 3. Windows/mingw
205 ================
207   * install mingw with the following packages:
208       binutils-2.16.91-...tar.gz
209       gcc-core-3.4.5-...tar.gz
210       gcc-g++-3.4.5-...tar.gz
211       mingw-runtime-3.9.tar.gz
212       mingw-utils-0.3.tar.gz
213       MSYS-1.0.11-...exe
214       msysDTK-1.0.1.exe
215       w32api-3.6.tar.gz
217   * install the latest Qt official "open source" binary package for
218     Windows/Mingw (required)
220   * install mingw/zlib (required):
221     Download zlib binaries and developer files (zlib-1.2.3-bin.zip and
222     zlib-1.2.3-lib.zip) from http://gnuwin32.sourceforge.net/packages/zlib.htm .
224   * install iconv (optional):
225     Download libiconv from http://gnuwin32.sourceforge.net/packages/libiconv.htm
226     The complete package (without source) is recommended.
228     You may also try the windows binary (libiconv-x.x.x.bin.woe32.zip) of
229     iconv from one of the GNU mirrors listed in http://www.gnu.org/prep/ftp.html.
231   * install gettext (optional):
232     Download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm
233     The complete package (without source) is recommended.
235     You may also try the windows binary (gettext-runtime-x.x.x.bin.woe32.zip
236     and gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors
237     (e.g. http://mirrors.usc.edu/pub/gnu/gettext/).
239   * install aspell (optional):
240     LyX uses aspell 0.60.4 and there is no, as of now, official windows
241     version. If you do not want to compile aspell from source by yourself,
242     your best bet is using Abdel's lyx 1.5.0svn experimental package located
243     at http://wiki.lyx.org/Windows/LyX150Experimental. The link to his
244     pre-built aspell package is http://younes.a.free.fr/Lyx-15-experimental
246   * install aiksaurus (optional):
247     Try to build aiksaurus from source (both mingw or msvc should work),
248     or look for pre-built package from the lyx 1.5.0svn experimental page.
250   * Open a mingw xterm, and start scons as usual.
252 Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no
253 extra_inc_path etc is needed.
256 4. Windows/cygwin
257 =================
259 LyX should be easy to compile, but you must use the most recent cygwin
260 dll (version 1.5.20-1 as of July 2006) because qt library in older
261 cygwin distribution does not work with previous versions due to broken
262 threading support.
264 To build lyx for cygwin, you should
266   * install (using the cygwin setup program) at least the following
267     packages and all other packages pulled in by dependencies:
269     aspell        gzip       libiconv     qt4-bin
270     aspell-dev    jpeg       libpng       qt4-devel
271     gcc           libintl    libpng2
272     gettext       libintl1   jpeg
273     gettext-devel libintl2   python
275   * install aiksaurus (http://aiksaurus.sourceforge.net/, optional):
276     There is no cygwin package for aiksaurus, so you should build it from
277     source. However, aiksaurus builds smoothly on cygwin.
279   * run scons as you would do under linux.
281 Note: cygwin/qt does not follow the usual $qt_dir/include, $qt_dir/bin,
282 $qt_dir/lib directory structure. For example, cygwin/qt4 uses directories
283 /usr/include/qt4, /usr/lib/qt4/bin and /usr/lib/qt4/lib. If these
284 directories can not be detected automatically, use options, for example,
285   qt_dir=/usr/lib/qt4 qt_inc_path=/usr/include/qt4
288 5. Windows/msvc
289 ===============
291 To build lyx with msvc, you should
293   * install msvc
294     It is recommended that you use MSVC2005 Express edition which is
295     freely available from microsoft.
297   * get windows platform SDK
298     Please follow the link in the MSVC webpage to download and configure.
299     It is important that you add SDK paths to %INCLUDE% and %LIB% in, e.g.,
300     C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat.
301     If you plan to use the MSVS IDE, you should also update the Visual C++
302     directories in VCProjectEngine.dll.express.config, as suggested in
303     http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/.
305   * build qt4 
306     - download qt4 source from trolltech (not the binary version, which
307       only works with mingw)
308     - get q../free patch for qt4
309     - compile qt4 as instructed
311   * download and install the official zlib library from www.zlib.org.
313   * optionally install iconv, gettext, aspell, aiksaurus following
314     the mingw instructions.
316   * start from msvc command prompt, use the use_vc option to build lyx.
317     You may need to use extra_inc_path etc to point to zlib paths.
319   * you can use the msvs_projects target to obtain msvc project files
320     for each lyx component.
321       - go to development/scons (important)
322       - run
323         > scons [other options] msvs_projects
324     Note that
325       - The resulting project files will use scons to build lyx
326       - All command line options, including rebuild, can be used as usual
327         (when msvs invoke scons).
328       - To use the msvc debugger, you have to use mode=debug (default).
331 6. Tips and hints
332 =================
334   * Using external boost libraries (install boost libraries and use
335     option boost=system) can speed up scons' starting time a lot, since
336     the boost headers will then be considered as system headers and will
337     not be included in the dependency tree.
340 7. Troubleshooting
341 ==================
343 When you get an error:
345 Q. Some path is not found.
346 A, Try options such as extra_inc_path, extra_lib_path.
348 Q. A test fails (failed to find zlib etc).
349 A. Have a look at config.log.
351 Q. I get a linking error.
352 A. Get the command sequence from scons_lyx.log and see what could
353    have gone wrong. You usually only need to tweak the last linking
354    command.
356 Q. Still can not figure it out.
357 A. Send an email to lyx-devel mailing list.
359 Q. Feeling too impatient/adventurous to wait for list response.
360 A. Read SConstruct and SConscript and see what went wrong. Trust me, they
361    are much easier to decipher than the autoconf/m4 files.