Building LyX with SCons
=========================
-June, 2006
+July, 2006
The GNU Build System (autoconf, automake and make) has been used to build
not necessarily easy to use and maintain (at least to non-m4 experts)
either. Because of these, a scons (http://www.scons.org) build system has
been set up as an alternative way to build lyx. As of writing, this system
-only supports qt3 and qt4 frontends.
+only supports the qt4 frontend.
-This README file is organized as follows:
+This file is organized as follows:
1. General usage of scons
2. *nix systems (Linux, Solaris and Mac OSX)
3. Windows/mingw
4. Windows/cygwin
-5. windows/msvc
-6. Troubleshooting
+5. Windows/msvc
+6. Tips and hints
+7. Troubleshooting
1. General usage of scons
--------------
* Python:
- Python >= 1.5.2 is required to run scons, but Python >= 2.2 is used by
- lyx itself so the newer version is recommended. Python is widely
- available on non-windows systems. Windows users can download and install
- python from http://www.python.org.
+ Python >= 2.6.0 is required to run scons, while LyX itself requires
+ Python >= 2.4.0 for scripts such as configure.py. Python is widely
+ available on non-windows systems. Windows users can download and
+ install python from http://www.python.org.
* SCons:
- scons >= 0.96.92 is needed. You can either use a full system-wide scons
+ scons >= 1.1.0 is needed. You can either use a full system-wide scons
distribution or a light-weight one (called scons-local) installed along
- with the lyx source tree. Both variants of scons are freely available
+ with the lyx source tree. Both variants of scons are freely available
from http://www.scons.org. Note that LyX source may ship with scons-base
in the near future.
-
+
* Other libraries:
- These include zlib (required), qt3 or qt4 (required), gettext
- (optional), boost (optional), aspell (optional) and Aiksaurus
- (optional). Please refer to the system-specific sections regarding the
+ These include zlib (required), qt4 (required), gettext
+ (optional), boost (optional), aspell (optional) and Aiksaurus
+ (optional). Please refer to the system-specific sections regarding the
availability and installation of them.
Start scons:
------------
-The scons system resides under development/scons. You can invoke it from
+The scons system resides under development/scons. You can invoke it from
either development/scons by, for example:
> cd development/scons
> scons frontend=qt4 qt_dir=d:/qt4 -j3 lyx
-or from top source directory by:
- > scons -f development/scons/SConstruct frontend=qt4 all
+or from any other directory and use -f option to point to the SConstruct
+file:
+ > mkdir build
+ > cd build
+ > scons -f ../development/scons/SConstruct frontend=qt4 all
+If you are tired of typing development/scons/SConstruct, you can link
+development/scons/SConstruct to the top source directory and use this
+SConstruct file.
There are three types of command line options:
* key=value are user options. They are used to tell scons which
- frontend to use, whether or not use included boost libraries etc.
+ frontend to use, whether or not use included boost libraries etc.
You can use 'scons -h' to list all of the options.
* parameters start with - or -- are scons options. Useful ones include
-j3 (with three threads) and --config=force (force reconfiguration).
Components to use/build:
- * frontend=qt3/qt4: qt3 is the default for all *nix systems including
- windows cygwin. qt4 is the default for windows/mingw and windows/
- msvc. xform and gtk are not currently supported.
- * mode=debug/release: lyx will be built under the debug or release
+ * frontend=qt4: qt4 is the only option right now.
+ * mode=debug/release: lyx will be built under the debug or release
directory, with different default build options.
* boost=included/system/auto: whether or not use included boost, system
- boost, or try to detect system boost first
+ boost, or try to detect system boost first. Note that boost=included
+ is safer if system boost has a different version from the included
+ one.
* gettext=included/system/auto
* nls=yes/no whether or not enable natural language support.
- * spell=aspell/pspell/ispell/auto: spell engine
+ * spell=aspell/auto: spell engine
+
Paths: Most of them will be probed if not specified.
- * qt_dir: top level directory of qt (with subdirectory include, lib)
- * qt_lib_path: path to the qt library, use only if there is no
+ * qt_dir: top level directory of qt (with at least subdirectory bin
+ containing commands uic and moc)
+ * qt_lib_path: path to the qt library, use only if there is no
$qt_dir/lib
- * qt_inc_path: path to qt include directory, use only if there is no
+ * qt_inc_path: path to qt include directory, use only if there is no
$qt_dir/include
* extra_inc_path, extra_inc_path1, extra_lib_path, extra_lib_path1:
additional paths to other libraries
+ * extra_bin_path: a convenient way to add an extra path to $PATH
Convenience options:
- * fast_start=yes/no: if true, bypass initial configuration step and use
- existing src/config.h
- * load_option=yes/no: if true, load previously saved command line
- options so you can run 'scons install' directly after a long
- 'scons all' building command.
- * rebuild=target1,target2... By default, scons will exam all components
+ * load_option=yes/no/opt1,opt2/-opt1,opt2: if true, load previously saved
+ command line options so you can run 'scons install' directly after a
+ long 'scons all' building command. You can load selected options using
+ load_option=opt1,opt2,... or exclude options using the - version of it.
+ Note that the option 'bundle' is not reloaded.
+ * rebuild=target1,target2... By default, scons will exam all components
when you build lyx. You can free scons from some hard work and save
yourself some time by telling scons to rebuild only specified
- component(s).
+ component(s). rebuild=no, none, yes or all can be used as well.
* log_file: a log file of executed commands, default to scons_lyx.log
Installation options:
* prefix: directory where lyx will be installed
- * exec_dir: directory where lyx binaries will be installed.
+ * exec_dir: directory where lyx binaries will be installed.
Default to $prefix/bin
- * dest_dir: if specified, install to this directory instead of $prefix.
+ * DESTDIR: if specified, install to this directory instead of $prefix.
+ * version_suffix=yes/no/something : if specified, this suffix will be
+ appended to the user data directory.
+ * win_installer: if specified under windows, and if 'installer' target
+ is given, generate NSIS installer specifed as win_installer which can
+ be a full path name. The default is lyx-version-timestamp-Installer.exe
+ for a development version, and lyx-version-Installer.exe for a released
+ version.
+
Compiler choice and flags:
* use_vc: use msvc instead of mingw g++ under windows
- * CC, LINK, CPP, CXX, CCFLAGS, LDFLAGS etc: compiler commands and
- flags. They can be set as environment variables as well.
+ * optimization: optimization flag to use (e.g. -O2)
+ * CC, LINK, CPP, CXX, CCFLAGS, LINKFLAGS etc: compiler commands and
+ flags. Setting CCFLAGS etc will replace default flags. These variables
+ can be set as environment variables as well.
Targets:
You can specify one or more of the following targets:
- Static libraries (names correspond to their directories):
- boost, intl, support, mathed, insets, frontends, graphics,
- controllers, client, qt3, qt4, lyxbase
+ Static libraries (names correspond to their directories):
+ boost, intl, support, mathed, insets, frontends, graphics,
+ controllers, client, qt4, lyxbase
Programs:
tex2lyx, client, lyx, all = tex2lyx + client + lyx
Installation:
- po, install = all + po
+ po, install = all + po, installer (windows only, need NSIS)
Misc:
- msvs_projects
+ msvs_projects, update_po
+
+Your built targets are put into $build_dir, which is debug (mode=debug),
+release (mode=release) or any name specified via build_dir=name. The
+directory structure is:
+ $build_dir
+ - common: most of the intermediate files, mostly object files
+ - libs: all static libraries
+ - executables: lyxclient, tex2lyx, lyx
+
+MSVS projects will be put to development/scons (and you should invoke
+scons from there for this target).
+
+update_po is similar to 'cd po; make update-po' but does not generate
+.gmo files, which is the task of the install target. Note that this
+target is the only target that changes files (po/*.po in this case)
+of the lyx source tree.
A typical working sequence:
> cd development/scons
> scons frontend=qt4 qt_dir=/path/to/qt4
- (build lyx, and all necessary libraries...)
+ (build lyx, and all needed libraries...)
> scons all -j3
(build lyx, client and tex2lyx, options like qt_dir will be carried
over here)
> scons rebuild=lyxbase
- (working on lyx_main.C, so only need to rebuild lyxbase)
+ (working on LyX.cpp, so only need to rebuild lyxbase)
> scons
(build again, only lyxbase will be rebuilt)
- > scons fast_start=no --config=force
- (need to regenerate src/config.h)
- > scons prefix=/usr/site dest_dir=/install/dir
+ > scons prefix=/usr/site DESTDIR=/install/dir
(lyx is built for /usr/site, but install to /install/dir)
-
2. *nix systems (Linux, Solaris and Mac OSX)
============================================
3. Windows/mingw
-=======================
+================
* install mingw with the following packages:
- - FIXME
-
+ binutils-2.16.91-...tar.gz
+ gcc-core-3.4.5-...tar.gz
+ gcc-g++-3.4.5-...tar.gz
+ mingw-runtime-3.9.tar.gz
+ mingw-utils-0.3.tar.gz
+ MSYS-1.0.11-...exe
+ msysDTK-1.0.1.exe
+ w32api-3.6.tar.gz
+
* install the latest Qt official "open source" binary package for
- Windows/Mingw
+ Windows/Mingw (required)
+
+ * install mingw/zlib (required):
+ Download zlib binaries and developer files (zlib-1.2.3-bin.zip and
+ zlib-1.2.3-lib.zip) from http://gnuwin32.sourceforge.net/packages/zlib.htm .
+
+ * install iconv (optional):
+ Download libiconv from http://gnuwin32.sourceforge.net/packages/libiconv.htm
+ The complete package (without source) is recommended.
- * install iconv: latest gnuwin32 package installed in mingw tree
- (or elsewhere)
+ You may also try the windows binary (libiconv-x.x.x.bin.woe32.zip) of
+ iconv from one of the GNU mirrors listed in http://www.gnu.org/prep/ftp.html.
- * install mingw/zlib: ditto
+ * install gettext (optional):
+ Download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm
+ The complete package (without source) is recommended.
- * aspell: this is difficult. Everybody has his own compiled library.
- Mine is in D:\program\Aspell-0.60.4.
+ You may also try the windows binary (gettext-runtime-x.x.x.bin.woe32.zip
+ and gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors
+ (e.g. http://mirrors.usc.edu/pub/gnu/gettext/).
+
+ * install aspell (optional):
+ LyX uses aspell 0.60.4 and there is no, as of now, official windows
+ version. If you do not want to compile aspell from source by yourself,
+ your best bet is using Abdel's lyx 1.5.0svn experimental package located
+ at http://wiki.lyx.org/Windows/LyX150Experimental. The link to his
+ pre-built aspell package is http://younes.a.free.fr/Lyx-15-experimental
+
+ * install aiksaurus (optional):
+ Try to build aiksaurus from source (both mingw or msvc should work),
+ or look for pre-built package from the lyx 1.5.0svn experimental page.
* Open a mingw xterm, and start scons as usual.
+Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no
+extra_inc_path etc is needed.
-4. Windows/cygwin
-=======================
-LyX should be easy to compile, but the qt3 library in the cygwin
-distribution does not work with the current cygwin dll (version 1.5.19-4
-as of June 2006) due to broken threading support. You should either wait
-for the forthcoming 1.5.20 version or install a recent snapshot from
-http://cygwin.com/snapshots.
+4. Windows/cygwin
+=================
To build lyx for cygwin, you should
* install (using the cygwin setup program) at least the following
packages and all other packages pulled in by dependencies:
- aspell grep libintl1 qt3-bin tar
- coreutils jbigkit libintl2 qt3-devel
- diffutils jpeg libpng python
- gettext libintl libpng2 sed
+ aspell gzip libiconv libQtGui4
+ aspell-dev gettext libpng libQtGui4-devel
+ gcc gettext-devel libQtCore4 pkg-config
+ gcc4 libintl8 libQtCore4-devel python
+
+ * install aiksaurus (http://aiksaurus.sourceforge.net/, optional):
+ There is no cygwin package for aiksaurus, so you should build it from
+ source. However, aiksaurus builds smoothly on cygwin.
* run scons as you would do under linux.
+Note: cygwin/qt does not follow the usual $qt_dir/include, $qt_dir/bin,
+$qt_dir/lib directory structure. For example, cygwin/qt4 uses directories
+/usr/include/qt4, /usr/lib/qt4/bin and /usr/lib/qt4/lib. If these
+directories can not be detected automatically, use options, for example,
+ qt_dir=/usr/lib/qt4 qt_inc_path=/usr/include/qt4
+
5. Windows/msvc
-=====================
+===============
-To build lyx with msvc, you should
+To build lyx with msvc, you should
* install msvc
It is recommended that you use MSVC2005 Express edition which is
freely available from microsoft.
* get windows platform SDK
- Please follow the link in the MSVC webpage to download and configure
-
- * build qt4
+ Please follow the link in the MSVC webpage to download and configure.
+ It is important that you add SDK paths to %INCLUDE% and %LIB% in, e.g.,
+ C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat.
+ If you plan to use the MSVS IDE, you should also update the Visual C++
+ directories in VCProjectEngine.dll.express.config, as suggested in
+ http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/.
+
+ * build qt4
- download qt4 source from trolltech (not the binary version, which
only works with mingw)
- get q../free patch for qt4
* download and install the official zlib library from www.zlib.org.
- * set up other optional libraries like aspell (following mingw
- instructions)
+ * optionally install iconv, gettext, aspell, aiksaurus following
+ the mingw instructions.
* start from msvc command prompt, use the use_vc option to build lyx.
You may need to use extra_inc_path etc to point to zlib paths.
- * you can use the msvs_projects target to obtain msvc project files
- for each lyx component.
+ * you can use the msvs_projects target to obtain msvc project files
+ for each lyx component.
- go to development/scons (important)
- - run
+ - run
> scons [other options] msvs_projects
- Note that
- - the resulting project files will use scons to build lyx
- - all command line options are used as usual (when msvs invoke
- scons)
+ Note that
+ - The resulting project files will use scons to build lyx
+ - All command line options, including rebuild, can be used as usual
+ (when msvs invoke scons).
+ - To use the msvc debugger, you have to use mode=debug (default).
+
+
+6. Tips and hints
+=================
+
+ * Using external boost libraries (install boost libraries and use
+ option boost=system) can speed up scons' starting time a lot, since
+ the boost headers will then be considered as system headers and will
+ not be included in the dependency tree.
-6. Troubleshooting
+7. Troubleshooting
==================
When you get an error:
projects / lyx.git / blobdiff