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