INSTALL.scons

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