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 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 ​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 ​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 ​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 ​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.