X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=INSTALL.cmake;h=540b68e698c067aa598bff2d4b1821c044740839;hb=71b8019d56142397994e0ef2d4244ada51f199d5;hp=284758b0be6b000f5acc44217e73b8876af07434;hpb=0ffdae7651cf562ed6ee19aec1c5c470ed331990;p=lyx.git diff --git a/INSTALL.cmake b/INSTALL.cmake index 284758b0be..540b68e698 100644 --- a/INSTALL.cmake +++ b/INSTALL.cmake @@ -1,82 +1,310 @@ +========================= Building LyX with CMake +========================= + + Install CMake from www.cmake.org or your distribution (version >= 3.1.0). + + + +3rd party libraries +-------------------- + + Install Qt 4 or Qt 5 and make sure qmake is found. + Add the folder with qmake to the environment variable PATH. + If you've compiled Qt by yourself or qmake is not found after + installing Qt fix PATH, + Linux/Unix: export PATH=/bin:$PATH + Windows : set PATH=\bin;%PATH% + If you use Qt 5, use -DLYX_USE_QT=QT5, otherwise Qt 4 will be searched. + + When you want to run LyX without installing from an out-of-source + build directory you have to set the environment variable LYX_DIR_22x + and it must point to the lib dir in the source tree. + Linux/Unix: export LYX_DIR_22x=/lib + Windows : set LYX_DIR_22x=\lib + + Windows specific + + On Windows install the supplementary modules: + * Visual Studio 2010: ftp://ftp.lyx.org/pub/lyx/devel/win_deps/lyx20-deps-msvc2010.zip + or use the option LYX_DEPENDENCIES_DOWNLOAD, then you have to add + these paths to your PATH variable: + \msvc2010-deps\deps20\bin + \msvc2010-deps\deps20\python + \msvc2010-deps\deps20\imagemagick + \msvc2010-deps\deps20\ghostscript + \msvc2010-deps\deps20\gettext-tools + + If cmake couldn't find these modules set GNUWIN32_DIR, e.g. + -DGNUWIN32_DIR=c:\gnuwin32. By default cmake searches in your + program folder. Or use the cmake GUI to set the GNUWIN32_DIR path. + + The build process tries to find aspell on Windows + in %ProgramFiles%/GnuWin32/ and in /usr/ or in /usr/local + under Linux. If it could not find aspell, spell checking + will be disabled. + + + +Generating build system files +------------------------------ + + CMake is a build system file generator. On all systems it could + generate files for several build systems, for instance Makefiles + for make, project files for Visual Studio, Xcode, Eclipse. + + Running cmake without any argument lists all supported build + systems on your system. Passing one of them as -G"" + argument when running cmake selects this. + + + +Building out-of-source +----------------------- + + The standard way of using CMake is to build in a folder that doesn't reside + in the source tree. This has the advantage that a complete fresh build could + be done by simply deleting all files in the build folder and re-running cmake + again. + + Another benefit of out-of-source builds is that several builds (debug, release, + command-line builds, IDE project files) could all use the same source tree. + + Therefore when using CMake create a folder outside of the source tree and + select this folder when using CMake's GUI, cmake-gui, or go into this folder + when you call cmake from the shell. + + Before performing an out-of-source build, ensure that all CMake generated + in-source build information is removed from the source directory, + e.g., CMakeFiles directory, CMakeCache.txt. + + + +Using cmake +------------ + + When calling cmake you must pass the path to the source tree (absolute or relative) + and optionally the generator (each system has its own default). Additional arguments + could be passed with the -D prefix. + + Here some examples, assuming the build folder is in the same folder as the source tree: + + * Makefiles on Linux + cmake ../trunk + + * Project files for QtCreator: + Open the trunk/CMakeLists.txt file and select the build folder + or create the files in the command line using the -G"CodeBlocks *" option, eg + cmake ../trunk -G"CodeBlocks - Unix Makefiles" + + * Project files for Xcode + cmake ../trunk -GXcode + + * Project files for Visual Studio 10 + cmake ..\trunk -G"Visual Studio 10" + + * NMake files for Visual Studio + cmake ..\trunk -G"NMake Makefiles" + + * Makefiles for MinGW + cmake ..\trunk -G"MinGW Makefiles" + + + Daily work: + + * Re-running cmake is simple + cmake . + + * Adding new files + The cmake build system scans the directories, so no need to update any file, + just re-run cmake. Also the mocing rules are generated. + + * Unused source code file + Because cmake scans the directories for *.cpp and *.h files it will also + add files to the build system that are not mentioned to build. To exclude + them change their ending and re-run cmake. + + + + +Build options +-------------- + + Options could be passed by the -D prefix when running cmake. + Available options will be listed on each cmake run. + -Dhelp=1 lists all available options: + + # Available on all systems/compilers + -- LYX_CPACK = OFF : Use the CPack management (Implies LYX_INSTALL option) + -- LYX_INSTALL = OFF : Build install projects/rules (implies a bunch of other options) + -- LYX_NLS = ON : Use nls + -- LYX_ASPELL = OFF : Require aspell + -- LYX_ENCHANT = OFF : Require Enchant + -- LYX_HUNSPELL = OFF : Require Hunspell + -- LYX_RELEASE = OFF : Build release version, build debug when disabled + -- LYX_PACKAGE_SUFFIX = ON : Use version suffix for packaging + -- LYX_PCH = OFF : Use precompiled headers + -- LYX_MERGE_FILES = OFF : Merge source files into one compilation unit + -- LYX_MERGE_REBUILD = OFF : Rebuild generated files from merged files build + -- LYX_QUIET = OFF : Don't generate verbose makefiles + -- LYX_INSTALL_PREFIX = OFF : Install path for LyX + + # GCC specific + -- LYX_PROFILE = OFF : Build profile version + -- LYX_EXTERNAL_BOOST = OFF : Use external boost + -- LYX_PROGRAM_SUFFIX = ON : Append version suffix to binaries + -- LYX_DEBUG_GLIBC = OFF : Enable libstdc++ debug mode + -- LYX_DEBUG_GLIBC_PEDANTIC = OFF : Enable libstdc++ pedantic debug mode + -- LYX_STDLIB_DEBUG = OFF : Use debug stdlib + + # MSVC specific + -- LYX_CONSOLE = ON : Show console on Windows + -- LYX_VLD = OFF : Use VLD with MSVC + -- LYX_WALL = OFF : Enable all warnings + -- LYX_DEPENDENCIES_DOWNLOAD= OFF : Download precompiled 3rd party libraries for MSVC 10 + + + +Using the merged files build +----------------------------- + + When the option 'LYX_MERGE_FILES' is used then for each library a file + is generated that includes all source files of this library, this speeds + up compilation by a factor of about 5. + + When you heavily work on one file you could comment out the relevant + define in the '_allinone_const.C' file, so only the file _allinone_touched.C' + will be re-compiled again and again. + + + - Adding new files + When you add new files the merging files have to be rebuilt: + cmake -DLYX_MERGE_REBUILD=1 . + Or start over by completely cleaning the build folder. + + - Starting over with the same configuration + Delete all files except CMakeCache.txt and call + cmake . + + + +Visual Studio C++ +------------------ + + * Warnings: The default warning level of the msvc cmake builds + is /W3. To enable /W4 use + '-DLYX_WALL=1 ' + and + '-DLYX_WALL=0' + switches back to to /W3. + To disable a specific warning add it to MSVC_W_DISABLE in + cmake/CMakeLists.txt. To make the warning an error add it + to MSVC_W_ERROR. + + * Memory leak detection + For MSVC the usage of 'Visual Leak Detection' could be enabled + (http://dmoulding.googlepages.com/vld): -DLYX_VLD=1 + + Building vld requires the 'Debugging Tools For Windows' (~16MB) + http://www.microsoft.com/whdc/devtools/debugging/default.mspx + Eventually you have to copy dbghelp.dll from your Visual Studio + Common7\IDE folder into the binary directory. + 'vld.ini' is part of lyx.proj where you can configure vld. + + The documentation for vld can be found in development/Win32/vld, or + http://www.codeproject.com/tools/visualleakdetector.asp + + + Some tips: + + * the Release build links much faster + * for the 'Debug' and 'Release' build all precompiled headers are enabled + to compile without pch (non file merge mode) This could be used to check + if all necessary headers are included. + * use 'MinSizeRel' which only precompiles the STL and Boost headers + * use 'RelWithDebInfo' which does not use any precompiled headers + + + +GCC/Windows (Win2k only works with MSYS, XP?) +---------------------------------------------- + QMAKESPEC is needed: + export QMAKESPEC=win32-g++ (MSYS) or set QMAKESPEC=win32-g++ (CMD) + + + +Ubuntu/Kubuntu +--------------- + + You need additionally these packages: + * g++ + * cmake + * qt4-dev-tools + + + +Xcode/Mac +---------- + + Some tips: + + * Xcode prefers UTF8 when opening source files, though LyX usually uses + Latin1. To fix that select all source files in Xcode and click "Get Info" + in the context menu. Change the encoding to Latin1. + + * You can run and debug LyX from Xcode. For LyX to find its resources, there + are two possibilities: + a) Put a resource directory, e.g. a link to the lib directory of the + source tree, at .../trunk/../build/bin/Resources + b) Select the lyx-qt4 executable in Xcode, click on "Get Info" in the + context menu and add "-sysdir a_valid_LyX_resource_directory" + pointing e.g. to a valid Contents/Resources of a LyX.app directory. + + * LyX on Mac doesn't look for fonts in the resource directory if the + executable is not in an .app bundle. Instead you have to create a + symbolic link to the fonts directory in the place where the executable + is: ln -s .../trunk/lib/fonts .../trunk/../build/bin/Debug/ + If you don't do that math characters will not show up correctly. + + * CMake properly finds the Qt4 library bundles from Trolltech's binary + Qt4 package for Mac. So no need to compile Qt on your own. + + + +Updating the translations +-------------------------- + + Read README.localization for information on the translation process. + Here we list only the CMake specific part. As with the autotools build + system the translations are only updated on demand. + + - Update .po files and create .gmo files (does not touch the source tree): + make translations + + - Copy the updated .po files into the source tree for committing: + make update-po + + - Update the layouttranslations file in the source tree: + make layouttranslations1 + + + +Packaging +---------- + + - Source .tar.gz, .tar.bz2, .zip: + make package_source + + - Binary .tar.gz and install .sh: + make package + + - Binary .deb: + create : cpack -G DEB --config CPackConfig.cmake + list : dpkg-deb -c lyx-*.deb + install: dpkg -i lyx-*.deb + + - Binary .rpm: + create : cpack -G RPM --config CPackConfig.cmake + list : rpm -qlp lyx-*.rpm + install: rpm -U lyx-*.rpm -For all builds: -- CMake 2.4 or CVS version from www.cmake.org -- install Qt 4 and make sure qmake 4 is found - (add the folder with qmake to the environment variable PATH) -- by default it builds the Qt4 frontend -- with GNUWIN32_DIR you could point to your gnuwin32 packages - (eg. -DGNUWIN32_DIR=c:\gnuwin32) by default it searches in your - program folder - -Building Visual C++ 2005 project files: -- install Visual C++ 2005 -- install Platform SDK 2005, "Core" and "Web Workshop" -- add include and library paths of the SDK to the IDE search paths, - menu: Tools->Options->VC++ directories->Library files + Include files -- install zlib (www.zlib.net) into %ProgramFiles%/GnuWin32/include+lib - or %ProgramFiles%/zlib/include+lib -- create a build directory, e.g. .../trunk/../build -- call in the build directory 'cmake ..\trunk\development\cmake' -- start lyx.sln -- Warnings: - The default warning level of the msvc cmake builds is now /W4. - The cmake option - -DDISABLEWALL=1 - switches to /W3, - -DWALL=1 - re enables /W4. - To disable a specific warning add it to MSVC_W_DISABLE of - cmake/CMakeLists.txt. To make the warning an error add it - to MSVC_W_ERROR of the same file. - -TIPS: - rename Microsoft Visual Studio 8\VC\vcpackages\feacp.dll - to disable Intellisense - - the Release build links much faster - - for the 'Debug' and 'Release' build all precompiled headers are enabled - to compile without pch (to check if all necessary headers are included) - * use 'MinSizeRel' which only precompiles the STL and Boost headers - * use 'RelWithDebInfo' which does not use any precompiled headers - - -Building with GCC/Linux: -- create a build directory, e.g. .../trunk/../build -- call in the build directory 'cmake ..\trunk\development\cmake' - -Building with GCC/Windows (Win2k only works with MSYS, XP?): -- install zlib (www.zlib.net) into %ProgramFiles%/GnuWin32/include+lib -- create a build directory, e.g. .../trunk/../build -- call: export QMAKESPEC=win32-g++ (MSYS) or set QMAKESPEC=win32-g++ (CMD) -- call in the build directory 'cmake ..\trunk\development\cmake' - -Building with Xcode/Mac: -- create a build directory, e.g. .../trunk/../build -- call in the build directory 'cmake .../trunk/development/cmake -G Xcode' -- open .../trunk/../build/lyx-qt4.xcodeproj - -TIPS: - Xcode prefers UTF8 when opening source files, though LyX usually uses - Latin1. To fix that select all source files in Xcode and click "Get Info" - in the context menu. Change the encoding to Latin1. - - You can run and debug LyX from Xcode. For LyX to find its resources, there - are two possibilities: - a) Put a resource directory, e.g. a link to the lib directory of the - source tree, at .../trunk/../build/bin/Resources - b) Select the lyx-qt4 executable in Xcode, click on "Get Info" in the - context menu and add "-sysdir a_valid_LyX_resource_directory" - pointing e.g. to a valid Contents/Resources of a LyX.app directory. - - LyX on Mac doesn't look for fonts in the resource directory if the - executable is not in an .app bundle. Instead you have to create a - symbolic link to the fonts directory in the place where the executable - is: ln -s .../trunk/lib/fonts .../trunk/../build/bin/Debug/ - If you don't do that math character will not show up correctly. - - CMake properly finds the Qt4 library bundles from Trolltech's binary - Qt4 package for Mac. So no need to compile Qt on your own. - - -To generate other build files call 'cmake' -which shows a list of possibilities. - - -The build process tries to find aspell on Windows -in %ProgramFiles%/GnuWin32/ and in /usr/ or in /usr/local -under Linux. If it is not found the support is disabled.