1 =========================
2 Building LyX with CMake
3 =========================
5 Install CMake from www.cmake.org or your distribution (version >= 2.6.4).
12 Install Qt 4 and make sure qmake is found.
13 Add the folder with qmake to the environment variable PATH.
14 If you've compiled Qt by yourself or qmake is not found after
15 installing Qt fix PATH,
16 Linux/Unix: export PATH=<your path to qt>/bin:$PATH
17 Windows : set PATH=<your path to qt>\bin;%PATH%
19 When you want to run LyX without installing from an out-of-source
20 build directory you have to set the environment variable LYX_DIR_21x
21 and it must point to the lib dir in the source tree.
22 Linux/Unix: export LYX_DIR_21x=<lyx-source>/lib
23 Windows : set LYX_DIR_21x=<lyx-source>\lib
27 On Windows install the supplementary modules:
28 * Visual Studio 2010: ftp://ftp.lyx.org/pub/lyx/devel/win_deps/lyx20-deps-msvc2010.zip
29 or use the option LYX_DEPENDENCIES_DOWNLOAD, then you have to add
30 these paths to your PATH variable:
31 <build-dir>\msvc2010-deps\deps20\bin
32 <build-dir>\msvc2010-deps\deps20\python
33 <build-dir>\msvc2010-deps\deps20\imagemagick
34 <build-dir>\msvc2010-deps\deps20\ghostscript
35 <build-dir>\msvc2010-deps\deps20\gettext-tools
37 If cmake couldn't find these modules set GNUWIN32_DIR, e.g.
38 -DGNUWIN32_DIR=c:\gnuwin32. By default cmake searches in your
39 program folder. Or use the cmake GUI to set the GNUWIN32_DIR path.
41 The build process tries to find aspell on Windows
42 in %ProgramFiles%/GnuWin32/ and in /usr/ or in /usr/local
43 under Linux. If it could not find aspell, spell checking
48 Generating build system files
49 ------------------------------
51 CMake is a build system file generator. On all systems it could
52 generate files for several build systems, for instance Makefiles
53 for make, project files for Visual Studio, Xcode, Eclipse.
55 Running cmake without any argument lists all supported build
56 systems on your system. Passing one of them as -G"<build system name>"
57 argument when running cmake selects this.
61 Building out-of-source
62 -----------------------
64 The standard way of using CMake is to build in a folder that doesn't reside
65 in the source tree. This has the advantage that a complete fresh build could
66 be done by simply deleting all files in the build folder and re-running cmake
69 Another benefit of out-of-source builds is that several builds (debug, release,
70 command-line builds, IDE project files) could all use the same source tree.
72 Therefore when using CMake create a folder outside of the source tree and
73 select this folder when using CMake's GUI, cmake-gui, or go into this folder
74 when you call cmake from the shell.
76 Before performing an out-of-source build, ensure that all CMake generated
77 in-source build information is removed from the source directory,
78 e.g., CMakeFiles directory, CMakeCache.txt.
85 When calling cmake you must pass the path to the source tree (absolute or relative)
86 and optionally the generator (each system has its own default). Additional arguments
87 could be passed with the -D prefix.
89 Here some examples, assuming the build folder is in the same folder as the source tree:
94 * Project files for QtCreator:
95 Open the trunk/CMakeLists.txt file and select the build folder
96 or create the files in the command line using the -G"CodeBlocks *" option, eg
97 cmake ../trunk -G"CodeBlocks - Unix Makefiles"
99 * Project files for Xcode
100 cmake ../trunk -GXcode
102 * Project files for Visual Studio 10
103 cmake ..\trunk -G"Visual Studio 10"
105 * NMake files for Visual Studio
106 cmake ..\trunk -G"NMake Makefiles"
108 * Makefiles for MinGW
109 cmake ..\trunk -G"MinGW Makefiles"
114 * Re-running cmake is simple
118 The cmake build system scans the directories, so no need to update any file,
119 just re-run cmake. Also the mocing rules are generated.
121 * Unused source code file
122 Because cmake scans the directories for *.cpp and *.h files it will also
123 add files to the build system that are not mentioned to build. To exclude
124 them change their ending and re-run cmake.
132 Options could be passed by the -D prefix when running cmake.
133 Available options will be listed on each cmake run.
134 -Dhelp=1 lists all available options:
136 # Available on all systems/compilers
137 -- LYX_CPACK = OFF : Use the CPack management (Implies LYX_INSTALL option)
138 -- LYX_INSTALL = OFF : Build install projects/rules (implies a bunch of other options)
139 -- LYX_NLS = ON : Use nls
140 -- LYX_ASPELL = OFF : Require aspell
141 -- LYX_ENCHANT = OFF : Require Enchant
142 -- LYX_HUNSPELL = OFF : Require Hunspell
143 -- LYX_DEVEL_VERSION = OFF : Build developer version
144 -- LYX_RELEASE = OFF : Build release version, build debug when disabled
145 -- LYX_PACKAGE_SUFFIX = ON : Use version suffix for packaging
146 -- LYX_PCH = OFF : Use precompiled headers
147 -- LYX_MERGE_FILES = OFF : Merge source files into one compilation unit
148 -- LYX_MERGE_REBUILD = OFF : Rebuild generated files from merged files build
149 -- LYX_QUIET = OFF : Don't generate verbose makefiles
150 -- LYX_INSTALL_PREFIX = OFF : Install path for LyX
153 -- LYX_PROFILE = OFF : Build profile version
154 -- LYX_EXTERNAL_BOOST = OFF : Use external boost
155 -- LYX_PROGRAM_SUFFIX = ON : Append version suffix to binaries
156 -- LYX_DEBUG_GLIBC = OFF : Enable libstdc++ debug mode
157 -- LYX_DEBUG_GLIBC_PEDANTIC = OFF : Enable libstdc++ pedantic debug mode
158 -- LYX_STDLIB_DEBUG = OFF : Use debug stdlib
159 -- LYX_CONCEPT_CHECKS = OFF : Enable concept-checks
162 -- LYX_CONSOLE = ON : Show console on Windows
163 -- LYX_VLD = OFF : Use VLD with MSVC
164 -- LYX_WALL = OFF : Enable all warnings
165 -- LYX_CONFIGURE_CHECKS = OFF : Also run configure checks for MSVC
166 -- LYX_DEPENDENCIES_DOWNLOAD= OFF : Download precompiled 3rd party libraries for MSVC 10
170 Using the merged files build
171 -----------------------------
173 When the option 'LYX_MERGE_FILES' is used then for each library a file
174 is generated that includes all source files of this library, this speeds
175 up compilation by a factor of about 5.
177 When you heavily work on one file you could comment out the relevant
178 define in the '_allinone_const.C' file, so only the file _allinone_touched.C'
179 will be re-compiled again and again.
183 When you add new files the merging files have to be rebuilt:
184 cmake -DLYX_MERGE_REBUILD=1 .
185 Or start over by completely cleaning the build folder.
187 - Starting over with the same configuration
188 Delete all files except CMakeCache.txt and call
196 * Warnings: The default warning level of the msvc cmake builds
197 is /W3. To enable /W4 use
201 switches back to to /W3.
202 To disable a specific warning add it to MSVC_W_DISABLE in
203 cmake/CMakeLists.txt. To make the warning an error add it
206 * Memory leak detection
207 For MSVC the usage of 'Visual Leak Detection' could be enabled
208 (http://dmoulding.googlepages.com/vld): -DLYX_VLD=1
210 Building vld requires the 'Debugging Tools For Windows' (~16MB)
211 http://www.microsoft.com/whdc/devtools/debugging/default.mspx
212 Eventually you have to copy dbghelp.dll from your Visual Studio
213 Common7\IDE folder into the binary directory.
214 'vld.ini' is part of lyx.proj where you can configure vld.
216 The documentation for vld can be found in development/Win32/vld, or
217 http://www.codeproject.com/tools/visualleakdetector.asp
222 * the Release build links much faster
223 * for the 'Debug' and 'Release' build all precompiled headers are enabled
224 to compile without pch (non file merge mode) This could be used to check
225 if all necessary headers are included.
226 * use 'MinSizeRel' which only precompiles the STL and Boost headers
227 * use 'RelWithDebInfo' which does not use any precompiled headers
231 GCC/Windows (Win2k only works with MSYS, XP?)
232 ----------------------------------------------
234 export QMAKESPEC=win32-g++ (MSYS) or set QMAKESPEC=win32-g++ (CMD)
241 You need additionally these packages:
253 * Xcode prefers UTF8 when opening source files, though LyX usually uses
254 Latin1. To fix that select all source files in Xcode and click "Get Info"
255 in the context menu. Change the encoding to Latin1.
257 * You can run and debug LyX from Xcode. For LyX to find its resources, there
258 are two possibilities:
259 a) Put a resource directory, e.g. a link to the lib directory of the
260 source tree, at .../trunk/../build/bin/Resources
261 b) Select the lyx-qt4 executable in Xcode, click on "Get Info" in the
262 context menu and add "-sysdir a_valid_LyX_resource_directory"
263 pointing e.g. to a valid Contents/Resources of a LyX.app directory.
265 * LyX on Mac doesn't look for fonts in the resource directory if the
266 executable is not in an .app bundle. Instead you have to create a
267 symbolic link to the fonts directory in the place where the executable
268 is: ln -s .../trunk/lib/fonts .../trunk/../build/bin/Debug/
269 If you don't do that math characters will not show up correctly.
271 * CMake properly finds the Qt4 library bundles from Trolltech's binary
272 Qt4 package for Mac. So no need to compile Qt on your own.
276 Updating the translations
277 --------------------------
279 Read README.localization for information on the translation process.
280 Here we list only the CMake specific part. As with the autotools build
281 system the translations are only updated on demand.
283 - Update .po files and create .gmo files (does not touch the source tree):
286 - Copy the updated .po files into the source tree for committing:
289 - Update the layouttranslations file in the source tree:
290 make layouttranslations1
297 - Source .tar.gz, .tar.bz2, .zip:
300 - Binary .tar.gz and install .sh:
304 create : cpack -G DEB --config CPackConfig.cmake
305 list : dpkg-deb -c lyx-*.deb
306 install: dpkg -i lyx-*.deb
309 create : cpack -G RPM --config CPackConfig.cmake
310 list : rpm -qlp lyx-*.rpm
311 install: rpm -U lyx-*.rpm