= !MapGuide RFC 164 - CMake build system = This page contains a change request (RFC) for the !MapGuide Open Source project. More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page. == Status == ||RFC Template Version||(1.0)|| ||Submission Date||11 Jan 2018|| ||Last Modified||24 Jan 2018|| ||Author||Jackie Ng|| ||RFC Status||adopted|| ||Implementation Status||implemented|| ||Proposed Milestone||4.0|| ||Assigned PSC guide(s)|||| ||'''Voting History'''|||| ||+1||Jackie,Gordon|| ||+0||Haris|| ||-0|||| ||-1|||| ||Abstained||Crispin,Trevor|| == Overview == This RFC proposes using CMake for building MapGuide on Linux. == Motivation == MapGuide currently uses autotools to build MapGuide on Linux. Autotools suffers from: * Slow build times * Builds are in the source tree, which complicates development as it will taint a subversion working copy with lots of autotools-generated junk files * Ability to use system-installed libraries is difficult as library detection logic is baked into various difficult to maintain configure scripts CMake is an alternative build system to autotools. It has the following advantages: * It is faster (see: Footnotes) * CMake builds are *out of the source tree*. This makes for a very clean development experience. * CMake makes it very easy for us to selectively use system-installed libraries over our internal counterparts. * There is healthy ecosystem of CMake modules available to easily detect certain libraries and for enabling compiler features (eg. AddressSanitizer) * (In the future): CMake can be our one-true-build-system-to-rule-them-all. It supports Visual Studio project generators, avoiding the need for us to maintain vcxproj/sln files by hand. But the main motivator for windows support is we can then leverage the use of [https://github.com/Microsoft/vcpkg vcpkg] to acquire/build/manage thirdparty C++ libraries on Windows. However, this particular item is not in the scope of this RFC and is merely an indicator of the possibilities a CMake build system will give us. == Proposed Solution == This RFC is basically a mirror of the equivalent [https://trac.osgeo.org/fdo/wiki/FDORfc21 RFC for FDO] The repository will be overlaid with various `CMakeLists.txt` files that describe how to build the various projects. A minor problem with implementing this solution is that we have certain thirdparty components that do not exist as system-installed libraries or they are available through the package manager but it is difficult to take advantage of them: * AGG * CS-Map * DBXML * DWF Toolkit * PHP * Apache HTTPD * Tomcat Connector To enable building these thirdparty components and to allow CMake to find them and to maintain the out-of-source-tree quality a CMake build gives us we'll add some helper build scripts to streamline the whole CMake build === cmake_bootstrap.sh === This is effectively a CMake-optimized version of the existing `build_oem.sh` that selectively builds the following thirdparty components in a build area separate from the source checkout: * DBXML * PHP * Apache HTTPD * Tomcat Connector This will install Apache/PHP into the designated install prefix so superuser elevation is generally required when running this script === cmake_build.sh === This is the main CMake wrapper build script that uses the build area prepared by `cmake_bootstrap.sh` to easily detect DBXML, Apache HTTPD and PHP to easily set up include directories and link libraries for the various projects that need them === CMake-ification === But what about the other thirdparty libraries? This RFC will also CMake-ify the following thirdparty libraries: * DWF Toolkit * CS-Map This will cause the above libraries to be built as part of the main `cmake_build.sh` run. Due to CS-Map being an svn external link, we can't modify its contents directly, so the CMake-ification of CS-Map will occur in a sibling `CsMapLibrary` directory in `Oem`. TODO: We should be upstanding OSS citizens and actually get the CS-Map project to adopt building with CMake, but that is not the scope of this RFC. With AGG, we will do what we do currently on Windows: Directly reference the various AGG source files of interest directly into the CMake-ified `Renderers` project. Other thirdparty libraries are available for us via the package manager for the distro versions we intend to target and thus are not built in this build system: * xerces-c (Our internal DBXML has been modified to work with a system-installed xerces-c) * geos * gd/libjpeg/libpng/zlib * jsoncpp * cppunit * ACE === Building with CMake === With these changes and build scripts, and assuming FDO and any available system-libraries are installed. The CMake build is simply: {{{ svn [co/export] https://svn.osgeo.org/mapguide/trunk/MgDev ~/mapguide_source cd ~/mapguide_source sudo ./cmake_bootstrap.sh --oem_working_dir ~/mapguide_oem_build ./cmake_build.sh --oem_working_dir ~/mapguide_oem_build --cmake_build_dir ~/mapguide_build_area cd ~/mapguide_build_area make sudo make install }}} In this example, the `~/mapguide_oem_build` and `~/mapguide_build_area` directories are automatically created by the build scripts and `~/mapguide_source` will remain un-tainted as the build will be taking place in `~/mapguide_oem_build` and `~/mapguide_build_area`. With this solution, the development experience is much cleaner as one can then proceed to edit sources under `~/mapguide_source` and be able to rebuild by re-running `make` and `make install` in `~/mapguide_build_area`. When it comes time to commit, there is no concerns about what junk files have been left by the build system as they are all in the un-tracked `~/mapguide_oem_build` and `~/mapguide_build_area` directories. This RFC has been implemented in the [https://trac.osgeo.org/mapguide/browser/sandbox/jng/cmake_v2 cmake_v2 sandbox]. Upon adoption of this RFC, the changes will be merged into trunk. == Implications == This is an alternative build system for Linux. Existing build systems are not affected. == Test Plan == Build on Ubuntu 14.04 with selective use of system-installed libraries. Build with existing Autotools to verify those builds still function. == Funding/Resources == Community == Footnotes == During the initial sandbox implementation of this RFC, CMake with the Ninja build generator and usage of GNU gold linker (over ld) yielded some very impressive build performance times vs the same build via autotools. However with the advent of the [https://meltdownattack.com/ Meltdown and Spectre vulnerabilities] and the ensuing OS/kernel updates to patch these vulnerabilities, the build performance gains through CMake have been wiped out and is now on par with autotools (pre-meltdown). Autotools (post-meltdown) has worse build performance, so overall a CMake build still performs better against Autotools, but it is a somewhat moot point in a post-meltdown world.