Small fixups to r40663

[lyx.git] / INSTALL.scons

diff --git a/INSTALL.scons b/INSTALL.scons
index aa3992281911888e7863818ca8249f5beec983e7..0969efa7e4df3e61cb5215f07fefdc3de67b7bd1 100644 (file)
--- a/INSTALL.scons
+++ b/INSTALL.scons
@@ -2,7 +2,7 @@
 Building LyX with SCons
 =========================
 
 Building LyX with SCons
 =========================
 

-June, 2006 
+July, 2006

 
 
 The GNU Build System (autoconf, automake and make) has been used to build
 
 
 The GNU Build System (autoconf, automake and make) has been used to build


@@ -11,15 +11,16 @@ 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
 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
 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
 
 
 1. General usage of scons


@@ -29,38 +30,44 @@ Prerequisites:
 --------------
 
 * Python:
 --------------
 
 * 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:

-  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
   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.
   from http://www.scons.org. Note that LyX source may ship with scons-base
   in the near future.

- 
+

 * Other libraries:
 * 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:
 ------------
 
   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
 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
 
 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).
     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).


@@ -76,24 +83,25 @@ command 'scons -h'.
 
 Components to use/build:
 
 
 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
     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.
   * 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.
 
 
 
 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_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
     $qt_dir/include
   * extra_inc_path, extra_inc_path1, extra_lib_path, extra_lib_path1:
     additional paths to other libraries


@@ -102,29 +110,39 @@ Paths: Most of them will be probed if not specified.
 
 Convenience options:
 
 
 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
     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
   * 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
     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
 
 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:
 
 
 Targets:


@@ -132,15 +150,15 @@ Targets:
 
 You can specify one or more of the following 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:
   Programs:
     tex2lyx, client, lyx, all = tex2lyx + client + lyx
   Installation:

-    po, install = all + po
+    po, install = all + po, installer (windows only, need NSIS)

   Misc:
   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
 
 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


@@ -148,11 +166,15 @@ directory structure is:
   $build_dir
     - common: most of the intermediate files, mostly object files
     - libs: all static libraries
   $build_dir
     - common: most of the intermediate files, mostly object files
     - libs: all static libraries

-    - qt3/qt4: lyx built with the frontend
-    - executables: lyxclient, tex2lyx, lyx 
+    - executables: lyxclient, tex2lyx, lyx

 
 

- MSVS projects will be put to development/scons (and you should invoke
- scons from there for this target).
+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:
 
 
 A typical working sequence:


@@ -160,21 +182,18 @@ A typical working sequence:
 
   > cd development/scons
   > scons frontend=qt4 qt_dir=/path/to/qt4
 
   > 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
   > 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
     (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)
 
 
     (lyx is built for /usr/site, but install to /install/dir)
 
 

-

 2. *nix systems (Linux, Solaris and Mac OSX)
 ============================================
 
 2. *nix systems (Linux, Solaris and Mac OSX)
 ============================================
 


@@ -186,7 +205,6 @@ problems.
 ================
 
   * install mingw with the following packages:
 ================
 
   * install mingw with the following packages:

-    FIXME: we only need gcc/g++ and win32 api.

       binutils-2.16.91-...tar.gz
       gcc-core-3.4.5-...tar.gz
       gcc-g++-3.4.5-...tar.gz
       binutils-2.16.91-...tar.gz
       gcc-core-3.4.5-...tar.gz
       gcc-g++-3.4.5-...tar.gz


@@ -194,66 +212,77 @@ problems.
       mingw-utils-0.3.tar.gz
       MSYS-1.0.11-...exe
       msysDTK-1.0.1.exe
       mingw-utils-0.3.tar.gz
       MSYS-1.0.11-...exe
       msysDTK-1.0.1.exe

-      msys-libtool-1.5.tar.bz2
-      w32api-3.6.tar.g 
+      w32api-3.6.tar.gz

 
   * install the latest Qt official "open source" binary package for
 
   * install the latest Qt official "open source" binary package for

-    Windows/Mingw
+    Windows/Mingw (required)

 
 

-  * install iconv (libiconv): 
-    Download 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 (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 .

 
 

-    You may also try gnuwin32/libiconv from 
-    http://gnuwin32.sourceforge.net/packages/libiconv.htm
+  * install iconv (optional):
+    Download libiconv from http://gnuwin32.sourceforge.net/packages/libiconv.htm
+    The complete package (without source) is recommended.

 
 

-  * install gettext (libintl):
-    Download 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/) and decompress.
-    
-    You may also try gnuwin32/libintl from
-    http://gnuwin32.sourceforge.net/packages/libintl.htm
+    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:
-    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 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/).

 
 

-  * aspell: this is difficult. Everybody has his own compiled library.
-    Mine is in D:\program\Aspell-0.60.4.
+  * 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.
 
 
   * Open a mingw xterm, and start scons as usual.
 

-Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no 
+Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no

 extra_inc_path etc is needed.
 
 
 4. Windows/cygwin
 =================
 
 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.
-

 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:
 
 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    libiconv
-    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.
 
 
   * 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
 ===============
 
 
 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
 
   * install msvc
     It is recommended that you use MSVC2005 Express edition which is


@@ -263,11 +292,11 @@ To build lyx with msvc, you should
     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.
     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++ 
+    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/.
 
     directories in VCProjectEngine.dll.express.config, as suggested in
     http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/.
 

-  * build qt4
+  * build qt4 

     - download qt4 source from trolltech (not the binary version, which
       only works with mingw)
     - get q../free patch for qt4
     - download qt4 source from trolltech (not the binary version, which
       only works with mingw)
     - get q../free patch for qt4


@@ -275,40 +304,34 @@ To build lyx with msvc, you should
 
   * download and install the official zlib library from www.zlib.org.
 
 
   * download and install the official zlib library from www.zlib.org.
 

-  * install iconv (libiconv): 
-    Download 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.
-
-    You may also try gnuwin32/libiconv from 
-    http://gnuwin32.sourceforge.net/packages/libiconv.htm
-
-  * install gettext (libintl):
-    Download 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/) and decompress.
-    
-    You may also try gnuwin32/libintl from
-    http://gnuwin32.sourceforge.net/packages/libintl.htm
-
-  * 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.
 
 
   * 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)
       - go to development/scons (important)

-      - run 
+      - run

         > scons [other options] msvs_projects
         > scons [other options] msvs_projects

-    Note that 
+    Note that

       - The resulting project files will use scons to build lyx
       - The resulting project files will use scons to build lyx

-      - All command line options, including rebuild, can be used as usual 
+      - 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).
 
 
         (when msvs invoke scons).
       - To use the msvc debugger, you have to use mode=debug (default).
 
 

-6. Troubleshooting
+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:
 ==================
 
 When you get an error: