X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=INSTALL.scons;h=0969efa7e4df3e61cb5215f07fefdc3de67b7bd1;hb=35b580fb30f266767938755140c9496141b297da;hp=2a43e6245a66ced6bff6fb8f2e0b4df8f933c94b;hpb=8caaf338c387c5496d94b57363d657055a243e78;p=lyx.git diff --git a/INSTALL.scons b/INSTALL.scons index 2a43e6245a..0969efa7e4 100644 --- a/INSTALL.scons +++ b/INSTALL.scons @@ -2,7 +2,7 @@ Building LyX with SCons ========================= -June, 2006 +July, 2006 The GNU Build System (autoconf, automake and make) has been used to build @@ -11,15 +11,16 @@ widely supported on the *nix systems, but not so under windows. They are not necessarily easy to use and maintain (at least to non-m4 experts) either. Because of these, a scons (http://www.scons.org) build system has been set up as an alternative way to build lyx. As of writing, this system -only supports qt3 and qt4 frontends. +only supports the qt4 frontend. This file is organized as follows: 1. General usage of scons 2. *nix systems (Linux, Solaris and Mac OSX) 3. Windows/mingw 4. Windows/cygwin -5. windows/msvc -6. Troubleshooting +5. Windows/msvc +6. Tips and hints +7. Troubleshooting 1. General usage of scons @@ -29,38 +30,44 @@ Prerequisites: -------------- * Python: - Python >= 1.5.2 is required to run scons, but Python >= 2.3 is used by - lyx itself so the newer version is needed. Python is widely - available on non-windows systems. Windows users can download and install - python from http://www.python.org. + Python >= 2.6.0 is required to run scons, while LyX itself requires + Python >= 2.4.0 for scripts such as configure.py. Python is widely + available on non-windows systems. Windows users can download and + install python from http://www.python.org. * SCons: - scons >= 0.96.92 is needed. You can either use a full system-wide scons + scons >= 1.1.0 is needed. You can either use a full system-wide scons distribution or a light-weight one (called scons-local) installed along - with the lyx source tree. Both variants of scons are freely available + with the lyx source tree. Both variants of scons are freely available from http://www.scons.org. Note that LyX source may ship with scons-base in the near future. - + * Other libraries: - These include zlib (required), qt3 or qt4 (required), gettext - (optional), boost (optional), aspell (optional) and Aiksaurus - (optional). Please refer to the system-specific sections regarding the + These include zlib (required), qt4 (required), gettext + (optional), boost (optional), aspell (optional) and Aiksaurus + (optional). Please refer to the system-specific sections regarding the availability and installation of them. Start scons: ------------ -The scons system resides under development/scons. You can invoke it from +The scons system resides under development/scons. You can invoke it from either development/scons by, for example: > cd development/scons > scons frontend=qt4 qt_dir=d:/qt4 -j3 lyx -or from top source directory by: - > scons -f development/scons/SConstruct frontend=qt4 all +or from any other directory and use -f option to point to the SConstruct +file: + > mkdir build + > cd build + > scons -f ../development/scons/SConstruct frontend=qt4 all +If you are tired of typing development/scons/SConstruct, you can link +development/scons/SConstruct to the top source directory and use this +SConstruct file. There are three types of command line options: * key=value are user options. They are used to tell scons which - frontend to use, whether or not use included boost libraries etc. + frontend to use, whether or not use included boost libraries etc. You can use 'scons -h' to list all of the options. * parameters start with - or -- are scons options. Useful ones include -j3 (with three threads) and --config=force (force reconfiguration). @@ -76,24 +83,25 @@ command 'scons -h'. Components to use/build: - * frontend=qt3/qt4: qt3 is the default for all *nix systems including - windows cygwin. qt4 is the default for windows/mingw and windows/ - msvc. xform and gtk are not currently supported. - * mode=debug/release: lyx will be built under the debug or release + * frontend=qt4: qt4 is the only option right now. + * mode=debug/release: lyx will be built under the debug or release directory, with different default build options. * boost=included/system/auto: whether or not use included boost, system - boost, or try to detect system boost first + boost, or try to detect system boost first. Note that boost=included + is safer if system boost has a different version from the included + one. * gettext=included/system/auto * nls=yes/no whether or not enable natural language support. - * spell=aspell/pspell/ispell/auto: spell engine + * spell=aspell/auto: spell engine Paths: Most of them will be probed if not specified. - * qt_dir: top level directory of qt (with subdirectory include, lib) - * qt_lib_path: path to the qt library, use only if there is no + * qt_dir: top level directory of qt (with at least subdirectory bin + containing commands uic and moc) + * qt_lib_path: path to the qt library, use only if there is no $qt_dir/lib - * qt_inc_path: path to qt include directory, use only if there is no + * qt_inc_path: path to qt include directory, use only if there is no $qt_dir/include * extra_inc_path, extra_inc_path1, extra_lib_path, extra_lib_path1: additional paths to other libraries @@ -102,31 +110,37 @@ Paths: Most of them will be probed if not specified. Convenience options: - * fast_start=yes/no: if true, bypass initial configuration step and use - existing src/config.h * load_option=yes/no/opt1,opt2/-opt1,opt2: if true, load previously saved - command line options so you can run 'scons install' directly after a + command line options so you can run 'scons install' directly after a long 'scons all' building command. You can load selected options using load_option=opt1,opt2,... or exclude options using the - version of it. - * rebuild=target1,target2... By default, scons will exam all components + Note that the option 'bundle' is not reloaded. + * rebuild=target1,target2... By default, scons will exam all components when you build lyx. You can free scons from some hard work and save yourself some time by telling scons to rebuild only specified - component(s). + component(s). rebuild=no, none, yes or all can be used as well. * log_file: a log file of executed commands, default to scons_lyx.log Installation options: * prefix: directory where lyx will be installed - * exec_dir: directory where lyx binaries will be installed. + * exec_dir: directory where lyx binaries will be installed. Default to $prefix/bin - * dest_dir: if specified, install to this directory instead of $prefix. + * DESTDIR: if specified, install to this directory instead of $prefix. + * version_suffix=yes/no/something : if specified, this suffix will be + appended to the user data directory. + * win_installer: if specified under windows, and if 'installer' target + is given, generate NSIS installer specifed as win_installer which can + be a full path name. The default is lyx-version-timestamp-Installer.exe + for a development version, and lyx-version-Installer.exe for a released + version. Compiler choice and flags: * use_vc: use msvc instead of mingw g++ under windows * optimization: optimization flag to use (e.g. -O2) - * CC, LINK, CPP, CXX, CCFLAGS, LINKFLAGS etc: compiler commands and + * CC, LINK, CPP, CXX, CCFLAGS, LINKFLAGS etc: compiler commands and flags. Setting CCFLAGS etc will replace default flags. These variables can be set as environment variables as well. @@ -136,15 +150,15 @@ Targets: You can specify one or more of the following targets: - Static libraries (names correspond to their directories): - boost, intl, support, mathed, insets, frontends, graphics, - controllers, client, qt3, qt4, lyxbase + Static libraries (names correspond to their directories): + boost, intl, support, mathed, insets, frontends, graphics, + controllers, client, qt4, lyxbase Programs: tex2lyx, client, lyx, all = tex2lyx + client + lyx Installation: - po, install = all + po + po, install = all + po, installer (windows only, need NSIS) Misc: - msvs_projects + msvs_projects, update_po Your built targets are put into $build_dir, which is debug (mode=debug), release (mode=release) or any name specified via build_dir=name. The @@ -152,12 +166,16 @@ directory structure is: $build_dir - common: most of the intermediate files, mostly object files - libs: all static libraries - - qt3 etc: lyx executable built with the frontend - - executables: lyxclient, tex2lyx, lyx + - executables: lyxclient, tex2lyx, lyx MSVS projects will be put to development/scons (and you should invoke scons from there for this target). +update_po is similar to 'cd po; make update-po' but does not generate +.gmo files, which is the task of the install target. Note that this +target is the only target that changes files (po/*.po in this case) +of the lyx source tree. + A typical working sequence: --------------------------- @@ -169,12 +187,10 @@ A typical working sequence: (build lyx, client and tex2lyx, options like qt_dir will be carried over here) > scons rebuild=lyxbase - (working on lyx_main.C, so only need to rebuild lyxbase) + (working on LyX.cpp, so only need to rebuild lyxbase) > scons (build again, only lyxbase will be rebuilt) - > scons fast_start=no --config=force - (need to regenerate src/config.h) - > scons prefix=/usr/site dest_dir=/install/dir + > scons prefix=/usr/site DESTDIR=/install/dir (lyx is built for /usr/site, but install to /install/dir) @@ -196,13 +212,13 @@ problems. mingw-utils-0.3.tar.gz MSYS-1.0.11-...exe msysDTK-1.0.1.exe - w32api-3.6.tar.g + w32api-3.6.tar.gz * install the latest Qt official "open source" binary package for Windows/Mingw (required) * install mingw/zlib (required): - Download zlib binaries and developer files (zlib-1.2.3-bin.zip and + Download zlib binaries and developer files (zlib-1.2.3-bin.zip and zlib-1.2.3-lib.zip) from http://gnuwin32.sourceforge.net/packages/zlib.htm . * install iconv (optional): @@ -217,7 +233,7 @@ problems. The complete package (without source) is recommended. You may also try the windows binary (gettext-runtime-x.x.x.bin.woe32.zip - and gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors + and gettext-tools-x.x.x.bin.woe32.zip) from one of the GNU mirrors (e.g. http://mirrors.usc.edu/pub/gnu/gettext/). * install aspell (optional): @@ -233,36 +249,40 @@ problems. * Open a mingw xterm, and start scons as usual. -Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no +Note: gettext, iconv and zlib are usually decompressed to c:/mingw so no extra_inc_path etc is needed. 4. Windows/cygwin ================= -LyX should be easy to compile, but the qt3 library in the cygwin -distribution does not work with the current cygwin dll (version 1.5.19-4 -as of June 2006) due to broken threading support. You should either wait -for the forthcoming 1.5.20 version or install a recent snapshot from -http://cygwin.com/snapshots. - To build lyx for cygwin, you should * install (using the cygwin setup program) at least the following packages and all other packages pulled in by dependencies: - aspell grep libintl1 qt3-bin tar - coreutils jbigkit libintl2 qt3-devel libiconv - diffutils jpeg libpng python - gettext libintl libpng2 sed + aspell gzip libiconv libQtGui4 + aspell-dev gettext libpng libQtGui4-devel + gcc gettext-devel libQtCore4 pkg-config + gcc4 libintl8 libQtCore4-devel python + + * install aiksaurus (http://aiksaurus.sourceforge.net/, optional): + There is no cygwin package for aiksaurus, so you should build it from + source. However, aiksaurus builds smoothly on cygwin. * run scons as you would do under linux. +Note: cygwin/qt does not follow the usual $qt_dir/include, $qt_dir/bin, +$qt_dir/lib directory structure. For example, cygwin/qt4 uses directories +/usr/include/qt4, /usr/lib/qt4/bin and /usr/lib/qt4/lib. If these +directories can not be detected automatically, use options, for example, + qt_dir=/usr/lib/qt4 qt_inc_path=/usr/include/qt4 + 5. Windows/msvc =============== -To build lyx with msvc, you should +To build lyx with msvc, you should * install msvc It is recommended that you use MSVC2005 Express edition which is @@ -272,11 +292,11 @@ To build lyx with msvc, you should Please follow the link in the MSVC webpage to download and configure. It is important that you add SDK paths to %INCLUDE% and %LIB% in, e.g., C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat. - If you plan to use the MSVS IDE, you should also update the Visual C++ + If you plan to use the MSVS IDE, you should also update the Visual C++ directories in VCProjectEngine.dll.express.config, as suggested in http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/. - * build qt4 + * build qt4 - download qt4 source from trolltech (not the binary version, which only works with mingw) - get q../free patch for qt4 @@ -284,25 +304,34 @@ To build lyx with msvc, you should * download and install the official zlib library from www.zlib.org. - * optionally install iconv, gettext, aspell, aiksaurus following + * optionally install iconv, gettext, aspell, aiksaurus following the mingw instructions. * start from msvc command prompt, use the use_vc option to build lyx. You may need to use extra_inc_path etc to point to zlib paths. - * you can use the msvs_projects target to obtain msvc project files - for each lyx component. + * you can use the msvs_projects target to obtain msvc project files + for each lyx component. - go to development/scons (important) - - run + - run > scons [other options] msvs_projects - Note that + Note that - The resulting project files will use scons to build lyx - - All command line options, including rebuild, can be used as usual + - All command line options, including rebuild, can be used as usual (when msvs invoke scons). - To use the msvc debugger, you have to use mode=debug (default). -6. Troubleshooting +6. Tips and hints +================= + + * Using external boost libraries (install boost libraries and use + option boost=system) can speed up scons' starting time a lot, since + the boost headers will then be considered as system headers and will + not be included in the dependency tree. + + +7. Troubleshooting ================== When you get an error: