INSTALL.cmake

   1 =========================
   2 Building LyX with CMake
   3 =========================
   4
   5     Install CMake from www.cmake.org or your distribution (version >= 2.6.4).
   6
   7
   8
   9 3rd party libraries
  10 --------------------
  11
  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%
  18
  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
  24
  25     Windows specific
  26
  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
  36
  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.
  40
  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
  44         will be disabled.
  45
  46
  47
  48 Generating build system files
  49 ------------------------------
  50
  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.
  54
  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.
  58
  59
  60
  61 Building out-of-source
  62 -----------------------
  63
  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
  67     again.
  68
  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.
  71
  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.
  75
  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.
  79
  80
  81
  82 Using cmake
  83 ------------
  84
  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.
  88
  89     Here some examples, assuming the build folder is in the same folder as the source tree:
  90
  91     * Makefiles on Linux
  92         cmake ../trunk
  93
  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"
  98
  99     * Project files for Xcode
 100         cmake ../trunk -GXcode
 101
 102     * Project files for Visual Studio 10
 103         cmake ..\trunk -G"Visual Studio 10"
 104
 105     * NMake files for Visual Studio
 106         cmake ..\trunk -G"NMake Makefiles"
 107
 108     * Makefiles for MinGW
 109         cmake ..\trunk -G"MinGW Makefiles"
 110
 111
 112     Daily work:
 113
 114     * Re-running cmake is simple
 115         cmake .
 116
 117     * Adding new files
 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.
 120
 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.
 125
 126
 127
 128
 129 Build options
 130 --------------
 131
 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:
 135
 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
 151     -- LYX_EXTERNAL_LIBINTL     = ON     : Use external libintl
 152
 153     # GCC specific
 154     -- LYX_PROFILE              = OFF    : Build profile version
 155     -- LYX_EXTERNAL_BOOST       = OFF    : Use external boost
 156     -- LYX_PROGRAM_SUFFIX       = ON     : Append version suffix to binaries
 157     -- LYX_DEBUG_GLIBC          = OFF    : Enable libstdc++ debug mode
 158     -- LYX_DEBUG_GLIBC_PEDANTIC = OFF    : Enable libstdc++ pedantic debug mode
 159     -- LYX_STDLIB_DEBUG         = OFF    : Use debug stdlib
 160     -- LYX_CONCEPT_CHECKS       = OFF    : Enable concept-checks
 161
 162     # MSVC specific
 163     -- LYX_CONSOLE              = ON     : Show console on Windows
 164     -- LYX_VLD                  = OFF    : Use VLD with MSVC
 165     -- LYX_WALL                 = OFF    : Enable all warnings
 166     -- LYX_CONFIGURE_CHECKS     = OFF    : Also run configure checks for MSVC
 167     -- LYX_DEPENDENCIES_DOWNLOAD= OFF    : Download precompiled 3rd party libraries for MSVC 10
 168
 169
 170
 171 Using the merged files build
 172 -----------------------------
 173
 174     When the option 'LYX_MERGE_FILES' is used then for each library a file
 175     is generated that includes all source files of this library, this speeds
 176     up compilation by a factor of about 5.
 177
 178     When you heavily work on one file you could comment out the relevant
 179     define in the '_allinone_const.C' file, so only the file _allinone_touched.C'
 180     will be re-compiled again and again.
 181
 182
 183     - Adding new files
 184       When you add new files the merging files have to be rebuilt:
 185         cmake -DLYX_MERGE_REBUILD=1 .
 186       Or start over by completely cleaning the build folder.
 187
 188     - Starting over with the same configuration
 189       Delete all files except CMakeCache.txt and call
 190         cmake .
 191
 192
 193
 194 Visual Studio C++
 195 ------------------
 196
 197     * Warnings: The default warning level of the msvc cmake builds
 198       is /W3. To enable /W4 use
 199         '-DLYX_WALL=1 '
 200       and
 201         '-DLYX_WALL=0'
 202       switches back to to /W3.
 203       To disable a specific warning add it to MSVC_W_DISABLE in
 204       cmake/CMakeLists.txt. To make the warning an error add it
 205       to MSVC_W_ERROR.
 206
 207     * Memory leak detection
 208       For MSVC the usage of 'Visual Leak Detection' could be enabled
 209       (http://dmoulding.googlepages.com/vld): -DLYX_VLD=1
 210
 211       Building vld requires the 'Debugging Tools For Windows' (~16MB)
 212       http://www.microsoft.com/whdc/devtools/debugging/default.mspx
 213       Eventually you have to copy dbghelp.dll from your Visual Studio
 214       Common7\IDE folder into the binary directory.
 215       'vld.ini' is part of lyx.proj where you can configure vld.
 216
 217       The documentation for vld can be found in development/Win32/vld, or
 218       http://www.codeproject.com/tools/visualleakdetector.asp
 219
 220
 221     Some tips:
 222
 223     * the Release build links much faster
 224     * for the 'Debug' and 'Release' build all precompiled headers are enabled
 225       to compile without pch (non file merge mode) This could be used to check
 226       if all necessary headers are included.
 227         * use 'MinSizeRel' which only precompiles the STL and Boost headers
 228         * use 'RelWithDebInfo' which does not use any precompiled headers
 229
 230
 231
 232 GCC/Windows (Win2k only works with MSYS, XP?)
 233 ----------------------------------------------
 234     QMAKESPEC is needed:
 235       export QMAKESPEC=win32-g++ (MSYS) or set QMAKESPEC=win32-g++ (CMD)
 236
 237
 238
 239 Ubuntu/Kubuntu
 240 ---------------
 241
 242     You need additionally these packages:
 243       * g++
 244       * cmake
 245       * qt4-dev-tools
 246
 247
 248
 249 Xcode/Mac
 250 ----------
 251
 252     Some tips:
 253
 254     * Xcode prefers UTF8 when opening source files, though LyX usually uses
 255       Latin1. To fix that select all source files in Xcode and click "Get Info"
 256       in the context menu. Change the encoding to Latin1.
 257
 258     * You can run and debug LyX from Xcode. For LyX to find its resources, there
 259       are two possibilities:
 260         a) Put a resource directory, e.g. a link to the lib directory of the
 261            source tree, at .../trunk/../build/bin/Resources
 262         b) Select the lyx-qt4 executable in Xcode, click on "Get Info" in the
 263            context menu and add "-sysdir a_valid_LyX_resource_directory"
 264            pointing e.g. to a valid Contents/Resources of a LyX.app directory.
 265
 266     * LyX on Mac doesn't look for fonts in the resource directory if the
 267       executable is not in an .app bundle. Instead you have to create a
 268       symbolic link to the fonts directory in the place where the executable
 269       is: ln -s .../trunk/lib/fonts .../trunk/../build/bin/Debug/
 270       If you don't do that math characters will not show up correctly.
 271
 272     * CMake properly finds the Qt4 library bundles from Trolltech's binary
 273       Qt4 package for Mac. So no need to compile Qt on your own.
 274
 275
 276
 277 Updating the translations
 278 --------------------------
 279
 280     Read README.localization for information on the translation process.
 281     Here we list only the CMake specific part. As with the autotools build
 282     system the translations are only updated on demand.
 283
 284     - Update .po files and create .gmo files (does not touch the source tree):
 285         make translations
 286
 287     - Copy the updated .po files into the source tree for committing:
 288         make update-po
 289
 290     - Update the layouttranslations file in the source tree:
 291         make layouttranslations1
 292
 293
 294
 295 Packaging
 296 ----------
 297
 298     - Source .tar.gz, .tar.bz2, .zip:
 299         make package_source
 300
 301     - Binary .tar.gz and install .sh:
 302         make package
 303
 304     - Binary .deb:
 305         create : cpack -G DEB --config CPackConfig.cmake
 306         list   : dpkg-deb -c lyx-*.deb
 307         install: dpkg -i lyx-*.deb
 308
 309     - Binary .rpm:
 310         create : cpack -G RPM --config CPackConfig.cmake
 311         list   : rpm -qlp lyx-*.rpm
 312         install: rpm -U lyx-*.rpm
 313