INSTALL.cmake

   1 =========================
   2 Building LyX with CMake
   3 =========================
   4
   5     Install CMake from www.cmake.org or your distribution (version >= 3.1.0).
   6
   7
   8
   9 3rd party libraries
  10 --------------------
  11
  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.
  21
  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
  27
  28     Windows specific
  29
  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
  39
  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.
  43
  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
  47         will be disabled.
  48
  49
  50
  51 Generating build system files
  52 ------------------------------
  53
  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.
  57
  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.
  61
  62
  63
  64 Building out-of-source
  65 -----------------------
  66
  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
  70     again.
  71
  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.
  74
  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.
  78
  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.
  82
  83
  84
  85 Using cmake
  86 ------------
  87
  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.
  91
  92     Here some examples, assuming the build folder is in the same folder as the source tree:
  93
  94     * Makefiles on Linux
  95         cmake ../trunk
  96
  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"
 101
 102     * Project files for Xcode
 103         cmake ../trunk -GXcode
 104
 105     * Project files for Visual Studio 10
 106         cmake ..\trunk -G"Visual Studio 10"
 107
 108     * NMake files for Visual Studio
 109         cmake ..\trunk -G"NMake Makefiles"
 110
 111     * Makefiles for MinGW
 112         cmake ..\trunk -G"MinGW Makefiles"
 113
 114
 115     Daily work:
 116
 117     * Re-running cmake is simple
 118         cmake .
 119
 120     * Adding new files
 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.
 123
 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.
 128
 129
 130
 131
 132 Build options
 133 --------------
 134
 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)
 141
 142
 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)
 173
 174     # GCC specific
 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
 181
 182     # MSVC specific
 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
 187
 188     # APPLE specific
 189     -- LYX_DMG                  = OFF    : Build as Mac bundle, needed for .dmg  (experimental)
 190     -- LYX_COCOA                = OFF    : Use Cocoa on Mac
 191
 192
 193 Using the merged files build (Deprecated)
 194 -----------------------------
 195
 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.
 199
 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.
 203
 204
 205     - Adding new files
 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.
 209
 210     - Starting over with the same configuration
 211       Delete all files except CMakeCache.txt and call
 212         cmake .
 213
 214
 215
 216 Visual Studio C++
 217 ------------------
 218
 219     * Warnings: The default warning level of the msvc cmake builds
 220       is /W3. To enable /W4 use
 221         '-DLYX_WALL=1 '
 222       and
 223         '-DLYX_WALL=0'
 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
 227       to MSVC_W_ERROR.
 228
 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
 232
 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.
 238
 239       The documentation for vld can be found in development/Win32/vld, or
 240       http://www.codeproject.com/tools/visualleakdetector.asp
 241
 242
 243     Some tips:
 244
 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
 251
 252
 253
 254 GCC/Windows (Win2k only works with MSYS, XP?)
 255 ----------------------------------------------
 256     QMAKESPEC is needed:
 257       export QMAKESPEC=win32-g++ (MSYS) or set QMAKESPEC=win32-g++ (CMD)
 258
 259
 260
 261 Ubuntu/Kubuntu
 262 ---------------
 263
 264     You need additionally these packages:
 265       * g++
 266       * cmake
 267       * qttools5-dev-tools + qt5-qmake or qt6-base-dev-tools + qt6-tools-dev
 268
 269
 270
 271 Xcode/Mac
 272 ----------
 273
 274     Some tips:
 275
 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.
 279
 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.
 287
 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.
 293
 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.
 296
 297
 298
 299 Updating the translations
 300 --------------------------
 301
 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.
 305
 306     - Update .po files and create .gmo files (does not touch the source tree):
 307         make translations
 308
 309     - Copy the updated .po files into the source tree for committing:
 310         make update-po
 311
 312     - Update the layouttranslations file in the source tree:
 313         make layouttranslations1
 314
 315
 316
 317 Packaging
 318 ----------
 319
 320     - Source .tar.gz, .tar.bz2, .zip:
 321         make package_source
 322
 323     - Binary .tar.gz and install .sh:
 324         make package
 325
 326     - Binary .deb:
 327         Configure with "cmake -DCPACK_BINARY_DEB:BOOL=ON"
 328           make package
 329         -- or --
 330           create : cpack -G DEB --config CPackConfig.cmake
 331         list   : dpkg-deb -c lyx-*.deb
 332         install: dpkg -i lyx-*.deb
 333
 334     - Binary .rpm:
 335         Configure with "cmake -DCPACK_BINARY_RPM:BOOL=ON"
 336           make package
 337         -- or --
 338           create : cpack -G RPM --config CPackConfig.cmake
 339         list   : rpm -qlp lyx-*.rpm
 340         install: rpm -U lyx-*.rpm
 341