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
  20     Windows specific
  21
  22         On Windows install the supplementary modules:
  23         * Visual Studio 2008: ftp://ftp.lyx.org/pub/lyx/contrib/lyx-windows-deps-msvc2008.zip
  24         * Visual Studio 2010: ftp://ftp.devel.lyx.org/pub/contrib/windows/bin
  25                               or use the option LYX_3RDPARTY_DOWNLOAD
  26
  27         If cmake couldn't find these modules set GNUWIN32_DIR, eg.
  28         -DGNUWIN32_DIR=c:\gnuwin32. By default cmake searches in your
  29         program folder. Or use the cmake GUI to set the GNUWIN32_DIR path.
  30
  31         The build process tries to find aspell on Windows
  32         in %ProgramFiles%/GnuWin32/ and in /usr/ or in /usr/local
  33         under Linux. If it could not find aspell, spell checking
  34         will be disabled.
  35
  36
  37
  38 Generating build system files
  39 ------------------------------
  40
  41     CMake is a build system file generator. On all systems it could
  42     generate files for several build systems, for instance Makefiles
  43     for make, project files for Visual Studio, Xcode, Eclipse.
  44
  45     Running cmake without any argument lists all supported build
  46     systems on your system. Passing one of them as -G"<build system name>"
  47     argument when running cmake selects this.
  48
  49
  50
  51 Building out-of-source
  52 -----------------------
  53
  54     The standard way of using CMake is to build in a folder which doesn't resides
  55     in the source tree. This has the advantage, that a complete fresh build could
  56     be done by simply deleting all files in the build folder and to re-run cmake
  57     again.
  58
  59     Another benefit of out-of-source builds is that several builds (debug, release,
  60     command-line builds, IDE project files) could all use the same source tree.
  61
  62     Therefore when using cmake create a folder outside of the source tree and
  63     select this folder when using CMake's GUI, cmake-gui, or go into this folder
  64     when you call cmake from the shell.
  65
  66
  67
  68 Using cmake
  69 ------------
  70
  71     When calling cmake you must pass the path to the source tree (absolute are relative)
  72     and optionally the generator (each system has its own default). Additional arguments
  73     could be passed with the -D prefix.
  74
  75     Here some examples, assuming the build folder is in the same folder as the source tree:
  76
  77     * Makefiles on Linux
  78         cmake ../trunk/development/cmake
  79
  80     * Project files for QtCreator:
  81         Open the trunk/development/cmake/CMakeLists.txt file and select the build folder
  82         or create the files in the command line using the -G"CodeBlocks *" option, eg
  83             cmake ../trunk/development/cmake -G"CodeBlocks - Unix Makefiles"
  84
  85     * Project files for Xcode
  86         cmake ../trunk/development/cmake -GXcode
  87
  88     * Project files for Visual Studio 10
  89         cmake ..\trunk\development\cmake -G"Visual Studio 10"
  90
  91     * NMake files for Visual Studio
  92         cmake ..\trunk\development\cmake -G"NMake Makefiles"
  93
  94     * Makefiles for MinGW
  95         cmake ..\trunk\development\cmake -G"MinGW Makefiles"
  96
  97
  98     Daily work:
  99
 100     * Re-running cmake is simple
 101         cmake .
 102
 103     * Adding new files
 104         The cmake build system scans the directories, so no need to update any file,
 105         just re-run cmake. Also the mocing rules are generated.
 106
 107     * Unused source code file
 108         Because cmake scans the directories for *.cpp and *.h files it will also
 109         add files to the build system which are not mentioned to build. To exclude
 110         them change their ending and re-run cmake.
 111
 112
 113
 114
 115 Build options
 116 --------------
 117
 118     Options could be passed by the -D prefix when running cmake.
 119     Available options will be listed on each cmake run.
 120     Here the options with their default value:
 121
 122     # Available on all systems/compilers
 123     -- LYX_CPACK                = OFF    : Use the CPack management (Implies LYX_INSTALL option)
 124     -- LYX_INSTALL              = OFF    : Build install projects/rules (implies a bunch of other options)
 125     -- LYX_NLS                  = OFF    : Use nls
 126     -- LYX_ASPELL               = OFF    : Require aspell
 127     -- LYX_ENCHANT              = OFF    : Require Enchant
 128     -- LYX_HUNSPELL             = OFF    : Require Hunspell
 129     -- LYX_DEVEL_VERSION        = OFF    : Build developer version
 130     -- LYX_RELEASE              = ON     : Build release version, build debug when disabled
 131     -- LYX_PACKAGE_SUFFIX       = ON     : Use version suffix for packaging
 132     -- LYX_PCH                  = OFF    : Use precompiled headers
 133     -- LYX_MERGE_FILES          = OFF    : Merge source files into one compilation unit
 134     -- LYX_MERGE_REBUILD        = OFF    : Rebuild generated files from merged files build
 135     -- LYX_QUIET                = OFF    : Don't generate verbose makefiles
 136     -- LYX_INSTALL_PREFIX       = OFF    : Install path for LyX
 137     -- LYX_EXTERNAL_LIBINTL     = ON     : Use external libintl
 138
 139     # GCC specific
 140     -- LYX_PROFILE              = OFF    : Build profile version
 141     -- LYX_EXTERNAL_BOOST       = OFF    : Use external boost
 142     -- LYX_PROGRAM_SUFFIX       = ON     : Append version suffix to binaries
 143     -- LYX_DEBUG_GLIBC          = OFF    : Enable libstdc++ debug mode
 144     -- LYX_DEBUG_GLIBC_PEDANTIC = OFF    : Enable libstdc++pedantic debug mode
 145     -- LYX_STDLIB_DEBUG         = OFF    : Use debug stdlib
 146     -- LYX_CONCEPT_CHECKS       = OFF    : Enable concept-checks
 147
 148     # MSVC specific
 149     -- LYX_CONSOLE              = ON     : Show console on Windows
 150     -- LYX_VLD                  = OFF    : Use VLD with MSVC
 151     -- LYX_WALL                 = OFF    : Enable all warnings
 152     -- LYX_CONFIGURE_CHECKS     = OFF    : Also run configure checks for MSVC
 153     -- LYX_3RDPARTY_DOWNLOAD    = OFF    : Download precompiled 3rd party libraries for MSVC 10
 154
 155
 156
 157 Using the merged files build
 158 -----------------------------
 159
 160     When the option 'LYX_MERGE_FILES' is used then for each library a files
 161     is generated which includes all source files of this library, this speeds
 162     up compilation about factor 5.
 163
 164     When you heavily work on one file you could comment out the relevant
 165     define in the '_allinone_const.C' file, so only the file _allinone_touched.C'
 166     file will be re-compiled again an again.
 167
 168
 169     - Adding new files
 170       When you add new files the merging files have to be rebuild:
 171         cmake -DLYX_MERGE_REBUILD=1 .
 172       Or start over by completely  cleaning the build folder.
 173
 174     - Starting over with same configuration
 175       Delete all files but CMakeCache.txt and call
 176         cmake .
 177
 178
 179
 180 Visual Studio C++
 181 ------------------
 182
 183     * Warnings: The default warning level of the msvc cmake builds
 184       is /W3. To enable /W4 use
 185         '-DLYX_WALL=1 '
 186       and
 187         '-DLYX_WALL=0'
 188       switches back to to /W3,
 189       To disable a specific warning add it to MSVC_W_DISABLE in
 190       cmake/CMakeLists.txt. To make the warning an error add it
 191       to MSVC_W_ERROR.
 192
 193     * Memory leak detection
 194       For MSVC the usage of 'Visual Leak Detection' could be enabled
 195       (http://dmoulding.googlepages.com/vld): -DLYX_VLD=1
 196
 197       Building vld requires the 'Debugging Tools For Windows' (~16MB)
 198       http://www.microsoft.com/whdc/devtools/debugging/default.mspx
 199       Eventually you have to copy dbghelp.dll from your Visual Studio
 200       Common7\IDE folder into the binary directory.
 201       'vld.ini' is part of lyx.proj where you can configure vld.
 202
 203       The docu for vld could be found in development/Win32/vld, or
 204       http://www.codeproject.com/tools/visualleakdetector.asp
 205
 206
 207     Some tips:
 208
 209     * the Release build links much faster
 210     * for the 'Debug' and 'Release' build all precompiled headers are enabled
 211       to compile without pch (non file merge mode) This could be used to check
 212       if all necessary headers are included.
 213         * use 'MinSizeRel' which only precompiles the STL and Boost headers
 214         * use 'RelWithDebInfo' which does not use any precompiled headers
 215
 216
 217
 218 GCC/Windows (Win2k only works with MSYS, XP?)
 219 ----------------------------------------------
 220     QMAKESPEC is needed:
 221       export QMAKESPEC=win32-g++ (MSYS) or set QMAKESPEC=win32-g++ (CMD)
 222
 223
 224
 225 Ubuntu/Kubuntu
 226 --------------_
 227
 228     You need additionally these packages:
 229       * g++
 230       * cmake
 231       * qt4-dev-tools
 232
 233
 234
 235 Xcode/Mac
 236 ----------
 237
 238     Some tips:
 239
 240     * Xcode prefers UTF8 when opening source files, though LyX usually uses
 241       Latin1. To fix that select all source files in Xcode and click "Get Info"
 242       in the context menu. Change the encoding to Latin1.
 243
 244     * You can run and debug LyX from Xcode. For LyX to find its resources, there
 245       are two possibilities:
 246         a) Put a resource directory, e.g. a link to the lib directory of the
 247            source tree, at .../trunk/../build/bin/Resources
 248         b) Select the lyx-qt4 executable in Xcode, click on "Get Info" in the
 249            context menu and add "-sysdir a_valid_LyX_resource_directory"
 250            pointing e.g. to a valid Contents/Resources of a LyX.app directory.
 251
 252     * LyX on Mac doesn't look for fonts in the resource directory if the
 253       executable is not in an .app bundle. Instead you have to create a
 254       symbolic link to the fonts directory in the place where the executable
 255       is: ln -s .../trunk/lib/fonts .../trunk/../build/bin/Debug/
 256       If you don't do that math character will not show up correctly.
 257
 258     * CMake properly finds the Qt4 library bundles from Trolltech's binary
 259       Qt4 package for Mac. So no need to compile Qt on your own.
 260
 261
 262
 263 Packaging
 264 ----------
 265
 266     - Source .tar.gz, .tar.bz2, .zip:
 267         make package_source
 268
 269     - Binary .tar.gz and install .sh:
 270         make package
 271
 272     - Binary .deb:
 273         create : cpack -G DEB --config CPackConfig.cmake
 274         list   : dpkg-deb -c lyx-*.deb
 275         install: dpkg -i lyx-*.deb
 276
 277     - Binary .rpm:
 278         create : cpack -G RPM --config CPackConfig.cmake
 279         list   : rpm -qlp lyx-*.rpm
 280         install: rpm -U lyx-*.rpm
 281