1 =========================
2 Building LyX with CMake
3 =========================
5 Install CMake from www.cmake.org or your distribution (version >= 3.1.0).
12 Install Qt 5 or Qt 6 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%
18 if you use -DLYX_USE_QT=AUTO, or do not use LYX_USE_QT, Qt 6 will be searched first
19 and if not found Qt 5 will be used.
20 If you want to use Qt 5, use -DLYX_USE_QT=QT5.
22 When you want to run LyX without installing from an out-of-source
23 build directory you have to set the environment variable LYX_DIR_24x
24 and it must point to the lib dir in the source tree.
25 Linux/Unix: export LYX_DIR_24x=<lyx-source>/lib
26 Windows : set LYX_DIR_24x=<lyx-source>\lib
30 On Windows install the supplementary modules:
31 * Visual Studio 2015: ftp://ftp.lyx.org/pub/lyx/devel/win_deps/lyx-windows-deps-msvc2015.zip
32 or use the option LYX_DEPENDENCIES_DOWNLOAD, then you have to add
33 these paths to your PATH variable:
34 <build-dir>\lyx-windows-deps-msvc2015\bin
35 <build-dir>\lyx-windows-deps-msvc2015\Python
36 <build-dir>\lyx-windows-deps-msvc2015\imagemagick
37 <build-dir>\lyx-windows-deps-msvc2015\ghostscript
38 <build-dir>\lyx-windows-deps-msvc2015\gettext-tools
40 If cmake couldn't find these modules set GNUWIN32_DIR, e.g.
41 -DGNUWIN32_DIR=c:\gnuwin32. By default cmake searches in your
42 program folder. Or use the cmake GUI to set the GNUWIN32_DIR path.
44 The build process tries to find aspell on Windows
45 in %ProgramFiles%/GnuWin32/ and in /usr/ or in /usr/local
46 under Linux. If it could not find aspell, spell checking
51 Generating build system files
52 ------------------------------
54 CMake is a build system file generator. On all systems it could
55 generate files for several build systems, for instance Makefiles
56 for make, project files for Visual Studio, Xcode, Eclipse.
58 Running cmake without any argument lists all supported build
59 systems on your system. Passing one of them as -G"<build system name>"
60 argument when running cmake selects this.
64 Building out-of-source
65 -----------------------
67 The standard way of using CMake is to build in a folder that doesn't reside
68 in the source tree. This has the advantage that a complete fresh build could
69 be done by simply deleting all files in the build folder and re-running cmake
72 Another benefit of out-of-source builds is that several builds (debug, release,
73 command-line builds, IDE project files) could all use the same source tree.
75 Therefore when using CMake create a folder outside of the source tree and
76 select this folder when using CMake's GUI, cmake-gui, or go into this folder
77 when you call cmake from the shell.
79 Before performing an out-of-source build, ensure that all CMake generated
80 in-source build information is removed from the source directory,
81 e.g., CMakeFiles directory, CMakeCache.txt.
88 When calling cmake you must pass the path to the source tree (absolute or relative)
89 and optionally the generator (each system has its own default). Additional arguments
90 could be passed with the -D prefix.
92 Here some examples, assuming the build folder is in the same folder as the source tree:
97 * Project files for QtCreator:
98 Open the trunk/CMakeLists.txt file and select the build folder
99 or create the files in the command line using the -G"CodeBlocks *" option, eg
100 cmake ../trunk -G"CodeBlocks - Unix Makefiles"
102 * Project files for Xcode
103 cmake ../trunk -GXcode
105 * Project files for Visual Studio 10
106 cmake ..\trunk -G"Visual Studio 10"
108 * NMake files for Visual Studio
109 cmake ..\trunk -G"NMake Makefiles"
111 * Makefiles for MinGW
112 cmake ..\trunk -G"MinGW Makefiles"
117 * Re-running cmake is simple
121 The cmake build system scans the directories, so no need to update any file,
122 just re-run cmake. Also the mocing rules are generated.
124 * Unused source code file
125 Because cmake scans the directories for *.cpp and *.h files it will also
126 add files to the build system that are not mentioned to build. To exclude
127 them change their ending and re-run cmake.
135 Options could be passed by the -D prefix when running cmake.
136 Available options will be listed on each cmake run.
137 "cmake -Dhelp=1 -S <lyx-source-dir> -B /tmp" lists all available options:
138 !!! Mark, that using this command creates CMakeCache.txt and CMakeFiles
139 !!! which have to be removed afterwards. Therefore it is better to explicitly
140 !!! specify a temporary build directory (/tmp in this example)
143 # Available on all systems/compilers
144 -- LYX_CPACK = OFF : Use the CPack management (Implies LYX_INSTALL option)
145 -- LYX_LOCALVERSIONING = ON : Add version info to created package name (only used if LYX_CPACK option set)
146 -- LYX_INSTALL = OFF : Build install projects/rules (implies a bunch of other options)
147 -- LYX_NLS = ON : Use nls
148 -- LYX_REQUIRE_SPELLCHECK = OFF : Abort if no spellchecker available
149 -- LYX_ASPELL = OFF : Require aspell
150 -- LYX_ENCHANT = OFF : Require Enchant
151 -- LYX_HUNSPELL = OFF : Require Hunspell
152 -- LYX_RELEASE = OFF : Build release version, build debug when disabled
153 -- LYX_DEBUG = ON : Enforce debug build
154 -- LYX_NO_OPTIMIZE = OFF : Don't use any optimization/debug flags
155 -- LYX_PACKAGE_SUFFIX = ON : Use version suffix for packaging
156 -- LYX_PCH = OFF : Use precompiled headers
157 -- LYX_MERGE_FILES = OFF : Merge source files into one compilation unit
158 -- LYX_MERGE_REBUILD = OFF : Rebuild generated files from merged files build
159 -- LYX_QUIET = OFF : Don't generate verbose makefiles
160 -- LYX_INSTALL_PREFIX = OFF : Install path for LyX
161 -- LYX_BUNDLE = OFF : Build bundle (experimental)
162 -- LYX_ENABLE_URLTESTS = OFF : Enable for URL tests
163 -- LYX_ENABLE_EXPORT_TESTS = ON : Enable for export tests
164 -- LYX_ENABLE_KEYTESTS = ON : Enable for keytests
165 -- LYX_ASAN = OFF : Use address sanitizer
166 -- LYX_USE_FILEDIALOG = NATI : Use native or QT file dialog (QT NATIVE)
167 -- LYX_USE_QT = QT6 : Use Qt version as frontend (AUTO QT5 QT6)
168 -- LYX_DISABLE_CALLSTACK_PRI= OFF : do not print a callstack when crashing
169 -- LYX_EXTERNAL_Z = ON : OFF := Build 3rdparty lib zlib
170 -- LYX_EXTERNAL_ICONV = ON : OFF := Build 3rdparty lib iconvlib
171 -- LYX_EXTERNAL_HUNSPELL = OFF : OFF := Build 3rdparty lib hunspelllib
172 -- LYX_EXTERNAL_MYTHES = OFF : OFF := Build 3rdparty lib mytheslib (AUTO OFF ON)
175 -- LYX_PROFILE = OFF : Build with options for gprof
176 -- LYX_EXTERNAL_BOOST = OFF : Use external boost
177 -- LYX_PROGRAM_SUFFIX = ON : Append version suffix to binaries
178 -- LYX_DEBUG_GLIBC = OFF : Enable libstdc++ debug mode
179 -- LYX_DEBUG_GLIBC_PEDANTIC = OFF : Enable libstdc++ pedantic debug mode
180 -- LYX_STDLIB_DEBUG = OFF : Use debug stdlib
183 -- LYX_CONSOLE = ON : Show console on Windows
184 -- LYX_VLD = OFF : Use VLD with MSVC
185 -- LYX_WALL = OFF : Enable all warnings
186 -- LYX_DEPENDENCIES_DOWNLOAD= OFF : Download precompiled 3rd party libraries for MSVC 10
189 -- LYX_DMG = OFF : Build as Mac bundle, needed for .dmg (experimental)
190 -- LYX_COCOA = OFF : Use Cocoa on Mac
193 Using the merged files build (Deprecated)
194 -----------------------------
196 When the option 'LYX_MERGE_FILES' is used then for each library a file
197 is generated that includes all source files of this library, this speeds
198 up compilation by a factor of about 5.
200 When you heavily work on one file you could comment out the relevant
201 define in the '_allinone_const.C' file, so only the file _allinone_touched.C'
202 will be re-compiled again and again.
206 When you add new files the merging files have to be rebuilt:
207 cmake -DLYX_MERGE_REBUILD=1 .
208 Or start over by completely cleaning the build folder.
210 - Starting over with the same configuration
211 Delete all files except CMakeCache.txt and call
219 * Warnings: The default warning level of the msvc cmake builds
220 is /W3. To enable /W4 use
224 switches back to to /W3.
225 To disable a specific warning add it to MSVC_W_DISABLE in
226 cmake/CMakeLists.txt. To make the warning an error add it
229 * Memory leak detection
230 For MSVC the usage of 'Visual Leak Detection' could be enabled
231 (http://dmoulding.googlepages.com/vld): -DLYX_VLD=1
233 Building vld requires the 'Debugging Tools For Windows' (~16MB)
234 http://www.microsoft.com/whdc/devtools/debugging/default.mspx
235 Eventually you have to copy dbghelp.dll from your Visual Studio
236 Common7\IDE folder into the binary directory.
237 'vld.ini' is part of lyx.proj where you can configure vld.
239 The documentation for vld can be found in development/Win32/vld, or
240 http://www.codeproject.com/tools/visualleakdetector.asp
245 * the Release build links much faster
246 * for the 'Debug' and 'Release' build all precompiled headers are enabled
247 to compile without pch (non file merge mode) This could be used to check
248 if all necessary headers are included.
249 * use 'MinSizeRel' which only precompiles the STL and Boost headers
250 * use 'RelWithDebInfo' which does not use any precompiled headers
254 GCC/Windows (Win2k only works with MSYS, XP?)
255 ----------------------------------------------
257 export QMAKESPEC=win32-g++ (MSYS) or set QMAKESPEC=win32-g++ (CMD)
264 You need additionally these packages:
267 * qttools5-dev-tools + qt5-qmake or qt6-base-dev-tools + qt6-tools-dev
276 * Xcode prefers UTF8 when opening source files, though LyX usually uses
277 Latin1. To fix that select all source files in Xcode and click "Get Info"
278 in the context menu. Change the encoding to Latin1.
280 * You can run and debug LyX from Xcode. For LyX to find its resources, there
281 are two possibilities:
282 a) Put a resource directory, e.g. a link to the lib directory of the
283 source tree, at .../trunk/../build/bin/Resources
284 b) Select the lyx-qt4 executable in Xcode, click on "Get Info" in the
285 context menu and add "-sysdir a_valid_LyX_resource_directory"
286 pointing e.g. to a valid Contents/Resources of a LyX.app directory.
288 * LyX on Mac doesn't look for fonts in the resource directory if the
289 executable is not in an .app bundle. Instead you have to create a
290 symbolic link to the fonts directory in the place where the executable
291 is: ln -s .../trunk/lib/fonts .../trunk/../build/bin/Debug/
292 If you don't do that math characters will not show up correctly.
294 * CMake properly finds the Qt4 library bundles from Trolltech's binary
295 Qt4 package for Mac. So no need to compile Qt on your own.
299 Updating the translations
300 --------------------------
302 Read README.localization for information on the translation process.
303 Here we list only the CMake specific part. As with the autotools build
304 system the translations are only updated on demand.
306 - Update .po files and create .gmo files (does not touch the source tree):
309 - Copy the updated .po files into the source tree for committing:
312 - Update the layouttranslations file in the source tree:
313 make layouttranslations1
320 - Source .tar.gz, .tar.bz2, .zip:
323 - Binary .tar.gz and install .sh:
327 Configure with "cmake -DCPACK_BINARY_DEB:BOOL=ON"
330 create : cpack -G DEB --config CPackConfig.cmake
331 list : dpkg-deb -c lyx-*.deb
332 install: dpkg -i lyx-*.deb
335 Configure with "cmake -DCPACK_BINARY_RPM:BOOL=ON"
338 create : cpack -G RPM --config CPackConfig.cmake
339 list : rpm -qlp lyx-*.rpm
340 install: rpm -U lyx-*.rpm