root/lyx-devel/branches/BRANCH_1_4_X/INSTALL.scons

=========================
Building LyX with SCons
=========================

Aug, 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 qt frontends.

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 >= 1.5.2 is required to run scons, but Python >= 2.2.0 is used by
  LyX itself so the newer version is needed. 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
  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), qt3 (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

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=qt2: qt2 is the default, and there is no other choice
  * 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/pspell/ispell/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:

  * fast_start=yes/no: if true, bypass initial configuration step and use
    existing src/config.h
  * 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.
  * 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
  * dest_dir: 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.


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, qt2, lyxbase
  Programs:
    tex2lyx, client, lyx, all = tex2lyx + client + lyx
  Installation:
    po, install = all + po
  Misc:
    msvs_projects

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
    - qt2: lyx executable built with the qt frontend
    - executables: lyxclient, tex2lyx, lyx

MSVS projects will be put to development/scons (and you should invoke
scons from there for this target).


A typical working sequence:
---------------------------

  > cd development/scons
  > scons qt_dir=/path/to/qt3
    (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)
  > 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
    (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
=================

LyX should be easy to compile, but you must use the most recent cygwin
dll (version 1.5.20-1 as of July 2006) because the qt3 library in the
cygwin distribution does not work with previous versions due to broken
threading support.

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     qt3-bin
    aspell-dev    jpeg       libpng       qt3-devel
    gcc           libintl    libpng2
    gettext       libintl1   jpeg
    gettext-devel libintl2   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/qt3 uses directories
/usr/include/qt3, /usr/lib/qt3/bin and /usr/lib/qt3/lib. If these
directories can not be detected automatically, use options, for example,
  qt_dir=/usr/lib/qt3 qt_inc_path=/usr/include/qt3


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 qt3
    - download qt3 source from Q../Free sourceforge.net website (not from 
      trolltech).
    - compile qt3 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.