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