mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-11-15 07:16:48 +00:00
a6aebc801a
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/branches/BRANCH_2_0_X@39565 a592a061-630c-0410-9148-cb99ea01b6c8
358 lines
13 KiB
Plaintext
358 lines
13 KiB
Plaintext
=========================
|
|
Building LyX with SCons
|
|
=========================
|
|
|
|
July, 2006
|
|
|
|
|
|
The GNU Build System (autoconf, automake and make) has been used to build
|
|
and distribute lyx. These de facto *nix tools are readily available and
|
|
widely supported on the *nix systems, but not so under windows. They are
|
|
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 the qt4 frontend.
|
|
|
|
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. Tips and hints
|
|
7. Troubleshooting
|
|
|
|
|
|
1. General usage of scons
|
|
=========================
|
|
|
|
Prerequisites:
|
|
--------------
|
|
|
|
* Python:
|
|
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 >= 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
|
|
from http://www.scons.org. Note that LyX source may ship with scons-base
|
|
in the near future.
|
|
|
|
* Other libraries:
|
|
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
|
|
either development/scons by, for example:
|
|
> cd development/scons
|
|
> scons frontend=qt4 qt_dir=d:/qt4 -j3 lyx
|
|
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.
|
|
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).
|
|
* others options are targets, which are lyx objects to build.
|
|
|
|
|
|
User Options:
|
|
-------------
|
|
|
|
Here I only list important options that you will likely use. Full option
|
|
list with detailed description and default value can be displayed using
|
|
command 'scons -h'.
|
|
|
|
Components to use/build:
|
|
|
|
* 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. 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/auto: spell engine
|
|
|
|
|
|
Paths: Most of them will be probed if not specified.
|
|
|
|
* 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_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:
|
|
|
|
* 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). 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.
|
|
Default to $prefix/bin
|
|
* 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
|
|
* 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, qt4, lyxbase
|
|
Programs:
|
|
tex2lyx, client, lyx, all = tex2lyx + client + lyx
|
|
Installation:
|
|
po, install = all + po, installer (windows only, need NSIS)
|
|
Misc:
|
|
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 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.cpp, so only need to rebuild lyxbase)
|
|
> scons
|
|
(build again, only lyxbase will be rebuilt)
|
|
> 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)
|
|
============================================
|
|
|
|
Proper use of extra_inc_path, qt_dir etc should solve most of the
|
|
problems.
|
|
|
|
|
|
3. Windows/mingw
|
|
================
|
|
|
|
* install mingw with the following packages:
|
|
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 (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.
|
|
|
|
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 gettext (optional):
|
|
Download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm
|
|
The complete package (without source) is recommended.
|
|
|
|
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
|
|
=================
|
|
|
|
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 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
|
|
|
|
* 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.
|
|
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
|
|
- compile qt4 as instructed
|
|
|
|
* download and install the official zlib library from www.zlib.org.
|
|
|
|
* 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.
|
|
- go to development/scons (important)
|
|
- run
|
|
> scons [other options] msvs_projects
|
|
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.
|
|
|
|
|
|
7. Troubleshooting
|
|
==================
|
|
|
|
When you get an error:
|
|
|
|
Q. Some path is not found.
|
|
A, Try options such as extra_inc_path, extra_lib_path.
|
|
|
|
Q. A test fails (failed to find zlib etc).
|
|
A. Have a look at config.log.
|
|
|
|
Q. I get a linking error.
|
|
A. Get the command sequence from scons_lyx.log and see what could
|
|
have gone wrong. You usually only need to tweak the last linking
|
|
command.
|
|
|
|
Q. Still can not figure it out.
|
|
A. Send an email to lyx-devel mailing list.
|
|
|
|
Q. Feeling too impatient/adventurous to wait for list response.
|
|
A. Read SConstruct and SConscript and see what went wrong. Trust me, they
|
|
are much easier to decipher than the autoconf/m4 files.
|
|
|
|
|