1 Compiling and installing LyX
2 ============================
4 Quick compilation guide
5 -----------------------
7 These four steps will compile, test and install LyX:
9 0) Linux users beware: You need qt4 and qt4-devel packages
10 of the same version to compile LyX.
12 In general, it is also recommended to have pkg-config
13 installed (the name might vary depending on your
16 1) ./configure configures LyX according to your system. You
17 may have to set --with-qt4-dir=<path-to-your-qt4-installation>
18 (for example, "--with-qt4-dir=/usr/share/qt4/") if the
19 environment variable QTDIR is not set and pkg-config is not
22 See Note below if ./configure script is not present.
28 runs the program so you can check it out.
31 will install it. You can use "make install-strip" instead
32 if you want a smaller binary.
35 Note for Git checkouts
36 -----------------------------
38 If you have checked this out from Git, you need to have:
41 Then type "./autogen.sh" to build the needed configuration
42 files and proceed as stated above/below.
44 You will also probably need GNU m4 (perhaps installed as gm4).
50 First of all, you will need a recent C++ compiler, where recent means
51 that the compilers are close to C++ standard conforming (gcc 4.x).
53 LyX makes great use of the C++ Standard Template Library (STL).
54 This means that gcc users will have to install the relevant libstdc++
55 library to be able to compile this version of LyX.
57 For full LyX usability we suggest to use at least Qt 4.8 which has been
58 widely tested. For compilation you need to compile against at least
59 Qt 4.5.0. The only special point to make is that you must ensure that both
60 LyX and the Qt libraries are compiled with the same C++ compiler.
62 To build LyX with spell checking capabilities included you have to
63 install at least one of the development packages of the spell checker
64 libraries. See the RELEASE-NOTES for details.
67 * Other things to note
69 The two following programs should be available at configuration time:
71 o LaTeX2e should be correctly setup for the user you are logged in
72 as. Otherwise, LyX will not be able to run a number of tests. Note
73 that users can run these tests manually with Tools>Reconfigure.
75 o Python 2.4 or newer must be installed. Python is used for many
76 simple tasks that are executed by external scripts, such as the
77 automatic configuration step and the import of older LyX documents
78 with the lyx2lyx script (this script is called automatically when
79 opening a file). Python 3.0 or later is not supported.
85 LyX can be configured using GNU autoconf utility which attempts to guess
86 the configuration needed to suit your system. The standard way to use it
87 is described in the file INSTALL.autoconf. In most cases you will be able
88 to create the Makefile by typing
92 For more complicated cases, LyX configure honors the following specific
95 o --enable-build-type=[rel(ease), pre(release), dev(elopment), prof(iling), gprof]
96 allows to tweak the compiled code. The following table describes
97 the settings in terms of various options that are described later
99 release prerelease development profiling gprof
100 optimization -O2 -O2 -O -O2 -O2
107 The defaults are as follows in terms of version number
108 release: stable release (1.x.y)
109 prerelease: version number contains alpha, beta, rc or pre.
110 development: version number contains dev.
112 The `profiling' build type uses the -fno-omit-frame-pointer option with gcc
114 The `gprof' build type compiles and links with -pg option with gcc.
116 o --with-extra-lib=DIRECTORY that specifies the path where LyX will
117 find extra libraries (qt4) it needs. Defaults to NONE
118 (i.e. search in standard places). You can specify several
119 directories, separated by colons.
121 o --with-extra-inc=DIRECTORY that gives the place where LyX will find
122 extra headers. Defaults to NONE (i.e. search in standard places).
123 You can specify several directories, separated by colons.
125 o --with-extra-prefix[=DIRECTORY] that is equivalent to
126 --with-extra-lib=DIRECTORY/lib --with-extra-inc=DIRECTORY/include
127 If DIRECTORY is not specified, the current prefix is used.
129 o --with-version-suffix[=SUFFIX] will install LyX as lyxSUFFIX. The
130 LyX data directory will be something like <whatever>/lyxSUFFIX/.
131 Additionally your user configuration files will be found in e.g.
132 $HOME/.lyxSUFFIX. The default for SUFFIX is "-<currentversion>",
135 You can use this feature to install more than one version of LyX
136 on the same system. You can optionally specify a "version" of your
137 own, by doing something like :
138 ./configure --with-version-suffix=-latestdev
140 Note that the standard configure options --program-prefix,
141 --program-suffix and the others will not affect the shared LyX
142 directory etc. so it is recommended that you use --with-version-suffix
143 (or --prefix) instead.
145 There are also flags to control the internationalization support in
148 o --disable-nls suppresses all internationalization support,
149 yielding somewhat smaller code.
151 o You can also set the environment variable LINGUAS to a list of
152 languages in case you do not want to install all the translation
153 files. For example, if you are only interested in German and
154 Finnish, you can type (with sh or bash)
155 export LINGUAS='de fi'
156 before running configure.
158 Moreover, the following generic configure flags may be useful:
160 o --prefix=DIRECTORY specifies the root directory to use for
161 installation. [defaults to /usr/local]
163 o --datadir=DIRECTORY gives the directory where all extra LyX
164 files (documentation, templates and layout definitions)
166 [defaults to ${prefix}/share/lyx${program_suffix}]
168 o --bindir=DIRECTORY gives the directory where the lyx binary
169 will be installed. [defaults to ${prefix}/bin]
171 o --mandir=DIRECTORY gives the directory where the man pages will go.
172 [defaults to ${prefix}/man]
174 o --enable-maintainer-mode enables some code that automatically
175 rebuilds the configure script, makefiles templates and other useful
176 files when needed. This is off by default on releases, to avoid
179 Note that the --with-extra-* commands are not really robust when it
180 comes to using relative paths. If you really want to use a relative path
181 here, you can prepend it with "`pwd`/".
183 If you do not like the default compile flags used (-g -O2 on gcc), you can
184 set CXXFLAGS variable to other values as follows:
186 o CXXFLAGS='-O2' (sh, bash)
187 o setenv CXXFLAGS '-O2' (csh, tcsh)
189 Similarly, if you want to force the use of a specific compiler, you can
190 give a value to the CXX variable.
192 If you encounter problems, please read the section 'Problems' at the end of
195 The following options allow you to tweak the generated code more precisely (see the description of --enable-build-type for the default values):
197 o --enable-optimization=VALUE enables you to set optimization to a
198 higher level than the default, for example --enable-optimization=-O3.
200 o --disable-optimization - you can use this to disable compiler
201 optimization of LyX. The compile may be much quicker with some
202 compilers, but LyX will run more slowly.
204 o --enable-debug will add debug information to your binary. This
205 requires a lot more disk space, but is a must if you want to try
206 to debug problems in LyX. There is no run-time penalty.
208 o --enable-warnings that make the compiler output more warnings during
209 the compilation of LyX. Opposite is --disable-warnings.
211 o --enable-assertions that make the compiler generate run-time
212 code which checks that some variables have sane values. Opposite
213 is --disable-assertions.
215 o --enable-stdlib-debug adds some debug code in the standard
216 library; this slows down the code, but has been helpful in the
219 o --enable-concept-checks adds some compile-time checks. There is no
222 o --without-latex-config that disables the automatic detection of your
223 latex configuration. This detection is automatically disabled if
224 latex cannot be found. If you find that you have to use this
225 flag, please report it as a bug.
227 o --enable-monolithic-build[=boost,client,insets,mathed,core,tex2lyx,frontend-qt4]
228 that enables monolithic build of the given parts of the source
229 code. This should reduce the compilation time provided you have
230 enough memory (>500MB).
233 Compiling and installing LyX
234 ----------------------------
236 Once you've got the Makefile created, you just have to type:
243 Since the binaries with debug information tend to be huge (although
244 this does not affect the run-time memory footprint), you might want
245 to strip the lyx binary. In this case replace "make install" with
249 BTW: in the images subdirectory there is also a small icon "lyx.png",
250 that can be used to display lyx-documents in filemanagers.
252 If configure fails for some strange reason
253 ------------------------------------------
255 Even when configure fails, it creates a Makefile. You can always check
256 the contents of this file, modify it and run 'make'.
258 Compiling For Multiple Architectures
259 ------------------------------------
261 You can compile LyX for more than one kind of computer at the same
262 time, by placing the object files for each architecture in their own
263 directory. To do this, you must use a version of `make' that supports
264 the `VPATH' variable, such as GNU `make'. `cd' to the directory where
265 you want the object files and executables to go and run the
266 `configure' script. `configure' automatically checks for the source
267 code in the directory that `configure' is in and in `..'.
269 If you have to use a `make' that does not supports the `VPATH'
270 variable, you have to compile LyX for one architecture at a time in
271 the source code directory. After you have installed LyX for one
272 architecture, use `make distclean' before reconfiguring for another
278 This section provides several hints that have been submitted by LyX
279 team members or users to help compiling on some particular
280 architectures. If you find that some of these hints are wrong, please
283 o On SUN Sparc Solaris, you need gnumake. The LyX makefiles do not
284 work with Solaris make.
286 The Solaris 8 ar seg-faults trying to build the insets library. You
287 will need to use the ar from the GNU binutils for this subdirectory.
288 There is no problem with the Solaris 9 and 10 ar.
290 Qt4 uses the Xrender X11 extension for antialiased fonts. This
291 extension was added to Xsun starting from the Solaris 10 8/07
292 release, but it is not activated by default. To activate it, you
293 must issue (as root) the following command:
294 svccfg -s svc:/application/x11/x11-server setprop options/server_args=+xrender
295 and then restart the X server.
297 There is a problem with the fontconfig library shipped with
298 Solaris 10 8/07 causing a seg-fault when it is used by Qt4.
299 Until this is fixed, a workaround is replacing the shared library
300 /usr/lib/libfontconfig.so.1 with a copy from a previous release or
301 installing a new version of fontconfig from http://www.sunfreeware.com/
303 On Solaris, the default fontconfig configuration gives preference
304 to bitmap fonts at (not so small) sizes. As bitmapped fonts are not
305 antialiased, you may prefer changing this configuration. This may be
306 done by adding the following stanza
308 <match target="pattern">
309 <edit name="prefer_bitmap">
314 to either ~/.fonts.conf (for a per-user change) or /etc/fonts/local.conf
315 (for a global system change). The stanza should be added between the
316 <fontconfig> and </fontconfig> tags. If neither ~/.fonts.conf nor
317 /etc/fonts/local.conf exists, you can create them with the following
320 <?xml version="1.0"?>
321 <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
323 <match target="pattern">
324 <edit name="prefer_bitmap">