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