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 the qt4 frontend.
  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), 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 any other directory and use -f option to point to the SConstruct
  60 file:
  61   > mkdir build
  62   > cd build
  63   > scons -f ../development/scons/SConstruct frontend=qt4 all
  64
  65 There are three types of command line options:
  66   * key=value are user options. They are used to tell scons which
  67     frontend to use, whether or not use included boost libraries etc.
  68     You can use 'scons -h' to list all of the options.
  69   * parameters start with - or -- are scons options. Useful ones include
  70     -j3 (with three threads) and --config=force (force reconfiguration).
  71   * others options are targets, which are lyx objects to build.
  72
  73
  74 User Options:
  75 -------------
  76
  77 Here I only list important options that you will likely use. Full option
  78 list with detailed description and default value can be displayed using
  79 command 'scons -h'.
  80
  81 Components to use/build:
  82
  83   * frontend=qt4: qt4 is the only option right now.
  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   * load_option=yes/no/opt1,opt2/-opt1,opt2: if true, load previously saved
 111     command line options so you can run 'scons install' directly after a
 112     long 'scons all' building command. You can load selected options using
 113     load_option=opt1,opt2,... or exclude options using the - version of it.
 114     Note that the option 'bundle' is not reloaded.
 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   * DESTDIR: 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   * win_installer: if specified under windows, and if 'installer' target
 131     is given, generate NSIS installer specifed as win_installer which can
 132     be a full path name. The default is lyx-version-timestamp-Installer.exe
 133     for a development version, and lyx-version-Installer.exe for a released
 134     version.
 135
 136
 137 Compiler choice and flags:
 138   * use_vc: use msvc instead of mingw g++ under windows
 139   * optimization: optimization flag to use (e.g. -O2)
 140   * CC, LINK, CPP, CXX, CCFLAGS, LINKFLAGS etc: compiler commands and
 141     flags. Setting CCFLAGS etc will replace default flags. These variables
 142     can be set as environment variables as well.
 143
 144
 145 Targets:
 146 --------
 147
 148 You can specify one or more of the following targets:
 149
 150   Static libraries (names correspond to their directories):
 151     boost, intl, support, mathed, insets, frontends, graphics,
 152     controllers, client, qt4, lyxbase
 153   Programs:
 154     tex2lyx, client, lyx, all = tex2lyx + client + lyx
 155   Installation:
 156     po, install = all + po, installer (windows only, need NSIS)
 157   Misc:
 158     msvs_projects, update_po
 159
 160 Your built targets are put into $build_dir, which is debug (mode=debug),
 161 release (mode=release) or any name specified via build_dir=name. The
 162 directory structure is:
 163   $build_dir
 164     - common: most of the intermediate files, mostly object files
 165     - libs: all static libraries
 166     - executables: lyxclient, tex2lyx, lyx
 167
 168 MSVS projects will be put to development/scons (and you should invoke
 169 scons from there for this target).
 170
 171 update_po is similar to 'cd po; make update-po' but does not generate
 172 .gmo files, which is the task of the install target. Note that this
 173 target is the only target that changes files (po/*.po in this case)
 174 of the lyx source tree.
 175
 176
 177 A typical working sequence:
 178 ---------------------------
 179
 180   > cd development/scons
 181   > scons frontend=qt4 qt_dir=/path/to/qt4
 182     (build lyx, and all needed libraries...)
 183   > scons all -j3
 184     (build lyx, client and tex2lyx, options like qt_dir will be carried
 185     over here)
 186   > scons rebuild=lyxbase
 187     (working on LyX.cpp, so only need to rebuild lyxbase)
 188   > scons
 189     (build again, only lyxbase will be rebuilt)
 190   > scons prefix=/usr/site DESTDIR=/install/dir
 191     (lyx is built for /usr/site, but install to /install/dir)
 192
 193
 194 2. *nix systems (Linux, Solaris and Mac OSX)
 195 ============================================
 196
 197 Proper use of extra_inc_path, qt_dir etc should solve most of the
 198 problems.
 199
 200
 201 3. Windows/mingw
 202 ================
 203
 204   * install mingw with the following packages:
 205       binutils-2.16.91-...tar.gz
 206       gcc-core-3.4.5-...tar.gz
 207       gcc-g++-3.4.5-...tar.gz
 208       mingw-runtime-3.9.tar.gz
 209       mingw-utils-0.3.tar.gz
 210       MSYS-1.0.11-...exe
 211       msysDTK-1.0.1.exe
 212       w32api-3.6.tar.gz
 213
 214   * install the latest Qt official "open source" binary package for
 215     Windows/Mingw (required)
 216
 217   * install mingw/zlib (required):
 218     Download zlib binaries and developer files (zlib-1.2.3-bin.zip and
 219     zlib-1.2.3-lib.zip) from http://gnuwin32.sourceforge.net/packages/zlib.htm .
 220
 221   * install iconv (optional):
 222     Download libiconv from http://gnuwin32.sourceforge.net/packages/libiconv.htm
 223     The complete package (without source) is recommended.
 224
 225     You may also try the windows binary (libiconv-x.x.x.bin.woe32.zip) of
 226     iconv from one of the GNU mirrors listed in http://www.gnu.org/prep/ftp.html.
 227
 228   * install gettext (optional):
 229     Download gettext from http://gnuwin32.sourceforge.net/packages/gettext.htm
 230     The complete package (without source) is recommended.
 231
 232     You may also try the windows binary (gettext-runtime-x.x.x.bin.woe32.zip
 233     and gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors
 234     (e.g. http://mirrors.usc.edu/pub/gnu/gettext/).
 235
 236   * install aspell (optional):
 237     LyX uses aspell 0.60.4 and there is no, as of now, official windows
 238     version. If you do not want to compile aspell from source by yourself,
 239     your best bet is using Abdel's lyx 1.5.0svn experimental package located
 240     at http://wiki.lyx.org/Windows/LyX150Experimental. The link to his
 241     pre-built aspell package is http://younes.a.free.fr/Lyx-15-experimental
 242
 243   * install aiksaurus (optional):
 244     Try to build aiksaurus from source (both mingw or msvc should work),
 245     or look for pre-built package from the lyx 1.5.0svn experimental page.
 246
 247   * Open a mingw xterm, and start scons as usual.
 248
 249 Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no
 250 extra_inc_path etc is needed.
 251
 252
 253 4. Windows/cygwin
 254 =================
 255
 256 LyX should be easy to compile, but you must use the most recent cygwin
 257 dll (version 1.5.20-1 as of July 2006) because qt library in older
 258 cygwin distribution does not work with previous versions due to broken
 259 threading support.
 260
 261 To build lyx for cygwin, you should
 262
 263   * install (using the cygwin setup program) at least the following
 264     packages and all other packages pulled in by dependencies:
 265
 266     aspell        gzip       libiconv     qt4-bin
 267     aspell-dev    jpeg       libpng       qt4-devel
 268     gcc           libintl    libpng2
 269     gettext       libintl1   jpeg
 270     gettext-devel libintl2   python
 271
 272   * install aiksaurus (http://aiksaurus.sourceforge.net/, optional):
 273     There is no cygwin package for aiksaurus, so you should build it from
 274     source. However, aiksaurus builds smoothly on cygwin.
 275
 276   * run scons as you would do under linux.
 277
 278 Note: cygwin/qt does not follow the usual $qt_dir/include, $qt_dir/bin,
 279 $qt_dir/lib directory structure. For example, cygwin/qt4 uses directories
 280 /usr/include/qt4, /usr/lib/qt4/bin and /usr/lib/qt4/lib. If these
 281 directories can not be detected automatically, use options, for example,
 282   qt_dir=/usr/lib/qt4 qt_inc_path=/usr/include/qt4
 283
 284
 285 5. Windows/msvc
 286 ===============
 287
 288 To build lyx with msvc, you should
 289
 290   * install msvc
 291     It is recommended that you use MSVC2005 Express edition which is
 292     freely available from microsoft.
 293
 294   * get windows platform SDK
 295     Please follow the link in the MSVC webpage to download and configure.
 296     It is important that you add SDK paths to %INCLUDE% and %LIB% in, e.g.,
 297     C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat.
 298     If you plan to use the MSVS IDE, you should also update the Visual C++
 299     directories in VCProjectEngine.dll.express.config, as suggested in
 300     http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/.
 301
 302   * build qt4
 303     - download qt4 source from trolltech (not the binary version, which
 304       only works with mingw)
 305     - get q../free patch for qt4
 306     - compile qt4 as instructed
 307
 308   * download and install the official zlib library from www.zlib.org.
 309
 310   * optionally install iconv, gettext, aspell, aiksaurus following
 311     the mingw instructions.
 312
 313   * start from msvc command prompt, use the use_vc option to build lyx.
 314     You may need to use extra_inc_path etc to point to zlib paths.
 315
 316   * you can use the msvs_projects target to obtain msvc project files
 317     for each lyx component.
 318       - go to development/scons (important)
 319       - run
 320         > scons [other options] msvs_projects
 321     Note that
 322       - The resulting project files will use scons to build lyx
 323       - All command line options, including rebuild, can be used as usual
 324         (when msvs invoke scons).
 325       - To use the msvc debugger, you have to use mode=debug (default).
 326
 327
 328 6. Tips and hints
 329 =================
 330
 331   * Using external boost libraries (install boost libraries and use
 332     option boost=system) can speed up scons' starting time a lot, since
 333     the boost headers will then be considered as system headers and will
 334     not be included in the dependency tree.
 335
 336
 337 7. Troubleshooting
 338 ==================
 339
 340 When you get an error:
 341
 342 Q. Some path is not found.
 343 A, Try options such as extra_inc_path, extra_lib_path.
 344
 345 Q. A test fails (failed to find zlib etc).
 346 A. Have a look at config.log.
 347
 348 Q. I get a linking error.
 349 A. Get the command sequence from scons_lyx.log and see what could
 350    have gone wrong. You usually only need to tweak the last linking
 351    command.
 352
 353 Q. Still can not figure it out.
 354 A. Send an email to lyx-devel mailing list.
 355
 356 Q. Feeling too impatient/adventurous to wait for list response.
 357 A. Read SConstruct and SConscript and see what went wrong. Trust me, they
 358    are much easier to decipher than the autoconf/m4 files.
 359
 360