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