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