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 README 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.2 is used by
  33   lyx itself so the newer version is recommended. 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 Paths: Most of them will be probed if not specified.
  91
  92   * qt_dir: top level directory of qt (with subdirectory include, lib)
  93   * qt_lib_path: path to the qt library, use only if there is no
  94     $qt_dir/lib
  95   * qt_inc_path: path to qt include directory, use only if there is no
  96     $qt_dir/include
  97   * extra_inc_path, extra_inc_path1, extra_lib_path, extra_lib_path1:
  98     additional paths to other libraries
  99
 100
 101 Convenience options:
 102
 103   * fast_start=yes/no: if true, bypass initial configuration step and use
 104     existing src/config.h
 105   * load_option=yes/no: if true, load previously saved command line
 106     options so you can run 'scons install' directly after a long
 107     'scons all' building command.
 108   * rebuild=target1,target2... By default, scons will exam all components
 109     when you build lyx. You can free scons from some hard work and save
 110     yourself some time by telling scons to rebuild only specified
 111     component(s).
 112   * log_file: a log file of executed commands, default to scons_lyx.log
 113
 114
 115 Installation options:
 116
 117   * prefix: directory where lyx will be installed
 118   * exec_dir: directory where lyx binaries will be installed.
 119     Default to $prefix/bin
 120   * dest_dir: if specified, install to this directory instead of $prefix.
 121
 122 Compiler choice and flags:
 123   * use_vc: use msvc instead of mingw g++ under windows
 124   * CC, LINK, CPP, CXX, CCFLAGS, LDFLAGS etc: compiler commands and
 125     flags. They can be set as environment variables as well.
 126
 127
 128 Targets:
 129 --------
 130
 131 You can specify one or more of the following targets:
 132
 133   Static libraries (names correspond to their directories):
 134     boost, intl, support, mathed, insets, frontends, graphics,
 135     controllers, client, qt3, qt4, lyxbase
 136   Programs:
 137     tex2lyx, client, lyx, all = tex2lyx + client + lyx
 138   Installation:
 139     po, install = all + po
 140   Misc:
 141     msvs_projects
 142
 143
 144 A typical working sequence:
 145 ---------------------------
 146
 147   > cd development/scons
 148   > scons frontend=qt4 qt_dir=/path/to/qt4
 149     (build lyx, and all necessary libraries...)
 150   > scons all -j3
 151     (build lyx, client and tex2lyx, options like qt_dir will be carried
 152     over here)
 153   > scons rebuild=lyxbase
 154     (working on lyx_main.C, so only need to rebuild lyxbase)
 155   > scons
 156     (build again, only lyxbase will be rebuilt)
 157   > scons fast_start=no --config=force
 158     (need to regenerate src/config.h)
 159   > scons prefix=/usr/site dest_dir=/install/dir
 160     (lyx is built for /usr/site, but install to /install/dir)
 161
 162
 163
 164 2. *nix systems (Linux, Solaris and Mac OSX)
 165 ============================================
 166
 167 Proper use of extra_inc_path, qt_dir etc should solve most of the
 168 problems.
 169
 170
 171 3. Windows/mingw
 172 =======================
 173
 174   * install mingw with the following packages:
 175     - FIXME
 176
 177   * install the latest Qt official "open source" binary package for
 178     Windows/Mingw
 179
 180   * install iconv: latest gnuwin32 package installed in mingw tree
 181     (or elsewhere)
 182
 183   * install mingw/zlib: ditto
 184
 185   * aspell: this is difficult. Everybody has his own compiled library.
 186     Mine is in D:\program\Aspell-0.60.4.
 187
 188   * Open a mingw xterm, and start scons as usual.
 189
 190
 191 4. Windows/cygwin
 192 =======================
 193
 194 LyX should be easy to compile, but the qt3 library in the cygwin
 195 distribution does not work with the current cygwin dll (version 1.5.19-4
 196 as of June 2006) due to broken threading support. You should either wait
 197 for the forthcoming 1.5.20 version or install a recent snapshot from
 198 http://cygwin.com/snapshots.
 199
 200 To build lyx for cygwin, you should
 201
 202   * install (using the cygwin setup program) at least the following
 203     packages and all other packages pulled in by dependencies:
 204
 205     aspell        grep       libintl1       qt3-bin      tar
 206     coreutils     jbigkit    libintl2       qt3-devel
 207     diffutils     jpeg       libpng         python
 208     gettext       libintl    libpng2        sed
 209
 210   * run scons as you would do under linux.
 211
 212
 213 5. Windows/msvc
 214 =====================
 215
 216 To build lyx with msvc, you should
 217
 218   * install msvc
 219     It is recommended that you use MSVC2005 Express edition which is
 220     freely available from microsoft.
 221
 222   * get windows platform SDK
 223     Please follow the link in the MSVC webpage to download and configure
 224
 225   * build qt4
 226     - download qt4 source from trolltech (not the binary version, which
 227       only works with mingw)
 228     - get q../free patch for qt4
 229     - compile qt4 as instructed
 230
 231   * download and install the official zlib library from www.zlib.org.
 232
 233   * set up other optional libraries like aspell (following mingw
 234     instructions)
 235
 236   * start from msvc command prompt, use the use_vc option to build lyx.
 237     You may need to use extra_inc_path etc to point to zlib paths.
 238
 239   * you can use the msvs_projects target to obtain msvc project files
 240     for each lyx component.
 241       - go to development/scons (important)
 242       - run
 243         > scons [other options] msvs_projects
 244     Note that
 245       - the resulting project files will use scons to build lyx
 246       - all command line options are used as usual (when msvs invoke
 247         scons)
 248
 249
 250 6. Troubleshooting
 251 ==================
 252
 253 When you get an error:
 254
 255 Q. Some path is not found.
 256 A, Try options such as extra_inc_path, extra_lib_path.
 257
 258 Q. A test fails (failed to find zlib etc).
 259 A. Have a look at config.log.
 260
 261 Q. I get a linking error.
 262 A. Get the command sequence from scons_lyx.log and see what could
 263    have gone wrong. You usually only need to tweak the last linking
 264    command.
 265
 266 Q. Still can not figure it out.
 267 A. Send an email to lyx-devel mailing list.
 268
 269 Q. Feeling too impatient/adventurous to wait for list response.
 270 A. Read SConstruct and SConscript and see what went wrong. Trust me, they
 271    are much easier to decipher than the autoconf/m4 files.
 272
 273