.. _rfc-84:

===========================================================
RFC 84: Migrating build systems to CMake
===========================================================

======== ==================================================
Authors: Even Rouault, Nyall Dawson, Howard Butler
======== ==================================================
Contact: even.rouault at spatialys.com,
         nyall.dawson at gmail.com,
         howard at hobu.co
Started: 2021-09-22
Updated: 2022-01-17
Status:  Adopted (implementation in progress)
======== ==================================================

Summary
-------

The document proposes :

- to develop a CMake build system, officially integrated in the source tree.

- and remove the current GNU makefiles and nmake build systems, when the CMake
  build system has matured enough and reached feature parity.
  We don't want to end up with a https://xkcd.com/927/ situation.

Motivation
----------

- A dual build system means editing twice, which increases the amount of work and
  the chance for bugs.

- For Unix, we have a rather custom and non-idiomatic build system using autoconf,
  but not automake.

- The makefiles in both build systems are hand-written. One of their main deficiency
  from the point of view of a GDAL developer is the lack of tracking of header
  dependencies. It is this very easy to produce a corrupted GDAL build, if forgetting to
  manually clean a previous build. This is a serious obstacle to embed regular or
  occasional GDAL developers that hit that issue, generally not found in other
  projects.

- Neither Unix or Windows builds support out-of-tree builds.

- Windows builds have poor support for parallel build: it is limited to the files
  in one directory.

- There is generally no consistency in the naming of build options in our
  Unix and Windows build systems, which makes life harder for users having to
  build GDAL on multiple platforms.

- The two existing build systems do not have the same features. For example,
  configure now offers the option to selectively disable drivers, including ones
  that do not depend on external dependencies, using a opt-out or opt-in
  strategies, whereas the NMake build does not.

- CMake has become the defacto solution with the widest adoption for C/C++ software that
  want to address multiple platforms. Most of GDAL dependencies have at least a
  CMake build system, and some have now CMake as the only option (GEOS 3.10 will
  only have a CMake build system, and the same is proposed for PROJ 9 in
  https://github.com/OSGeo/PROJ/pull/2880), making soon CMake a de-facto requirement
  for a GDAL build.
  Looking a bit in the FOSS4G field for C/C++ project, CMake is ubiquitous, so
  there is a widespread knowledge of it among existing or potential contributors
  to GDAL.

- A CMake build system has been asked repeatedly by many developers or users of
  GDAL over the past years. We are aware of a least two public out-of-tree CMake
  efforts: https://github.com/miurahr/cmake4gdal and https://github.com/nextgis-borsch/lib_gdal

- CMake has the widest industry tooling support. A number of Modern C++ IDEs offer good support for CMake:
  Visual Studio, qtcreator, etc.
  This should help reduce the barrier for contribution.

- CMake development is active with regular feature releases, whereas the technologies
  behind our existing build systems are more in a maintenance mode.

Why not CMake?
--------------

Other modern cross-platform build systems exist, including Meson and Bazel,
which have many advantages over CMake. However, they are currently not widely
familiar or used by active GDAL contributors. CMake represent the current
"least worse" solution for multiple platform builds when comparing its capabilities
and its maturity.

CMake does not address simultaneously building shared and static libraries. This
can however be worked around by doing 2 builds and merging build artifacts.

Phases / Schedule
-----------------

The following is the planned schedule:

- Add CMake as a new build system, and formally deprecate GNUmakefile and NMake
  base file systems.
  Users and packagers are encouraged to switch to CMake and actively report
  (and help fixing) issues the find in the process.
  GDAL 3.5.x point releases will be used to address reported issues.

  ==> Target: GDAL 3.5 / May 2022

- Completely remove GNUmakefile and NMake base file systems, and make CMake the
  only build system in GDAL source tree.

  ==> Target: GDAL 3.6 / November 2022

Details
-------

The above mentioned cmake4gdal repository seems to us the best starting point.
It respects the current tree organization of the GDAL repository and targets a
not too old CMake version (3.10).

We will start by running the scripts that deploy the CMakeLists.txt and other
cmake support files, and commit them into the GDAL repository.

A checklist of all features of our current build systems that will need to be
ported and checked has been initiated in:
https://docs.google.com/spreadsheets/d/1SsUXiZxKim6jhLjlJFCRs1zwMvNpbJbBMB6yl0ms01c/edit

SWIG bindings
-------------

The Python, Java and CSharp bindings will be available as options of the CMake
build options.

The Perl bindings will not be available, as being planned for removal in GDAL 3.5

Compatibility
-------------

The addition of the CMake build system, being mostly an addition during the transient
phase where it will be available alongside the existing build systems, should
moderately impact existent files. However, it is likely that there will be some
improvements that affect C++ files (for example, to use consistently ``#include <project/header.h>``
style of inclusion instead of the``#include <header.h>`` with ``-I${include_prefix}/project``
pattern sometimes used) and the GNUmakefile/makefile.vc files.

We may use of PRIVATE linking of vendored and intermediate libraries to hide
non-public symbols. This might change a bit from existing builds that can leak them.

Minimum CMake version
---------------------

cmake4gdal uses CMake 3.10 as the minimum version. This is a reasonable choice,
as it would be compatible with the cmake version provided by Ubuntu 18.04 for example,
the current old-stable Ubuntu LTS.

Given the mentioned schedule, CMake will become a requirement in May 2023,
at a time where the new old-stable LTS will be Ubuntu 20.04. So we can't exclude
we will bump this minimum version if it is found to be more practical.
For example, CMake 3.12 adds an easier way for handling "object libraries", that
can help solving issues regarding static builds and vendored dependencies
(cf https://github.com/libgeos/geos/issues/463)

Supported platforms
-------------------

Our continuous integration "only" tests Linux (Intel/AMD, ARM64 and s390x architectures),
Android (build only), MacOSX and Windows. We will welcome involvement at some point
from users/developers of other environments to test and help address any outstanding issues.

General requirements
--------------------

The following lists a few requirements to consider the new build system be ready,
and the existing ones can be removed:

- The build system works on most environments where the build systems are known to work.
  For CI-tested environments, this will involve porting to them and checking that
  the builds are functional. For other build systems, we will depend on manual testing
  from users.

- objdir / out-of-source builds are supported.

- cross builds are supported.

- Explicit testing of OSes through ``if(THIS_OS)`` should be limited, and replaced
  by testing of feature wherever doable.

- There has been a formal release (presumably 3.6) with existing build systems
  and cmake where cmake meets the above requirements, as verified by packager feedback.

Funding
-------

Even Rouault and Nyall Dawson will use project sponsorship funding to complete
that work. An estimate of 2 man-months of effort has been made recently to
provide an initial build out of CMake support for GDAL.

Voting history
--------------

+1 from PSC members: HowardB, MateuszL, KurtS, DanielM and JukkaR
