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