INSTALL.scons

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