From ebf44c53014b03a9dc9c7754efa7bf90f1ea3b28 Mon Sep 17 00:00:00 2001
From: Chip Hogg <chogg@aurora.tech>
Date: Tue, 2 Jul 2024 14:12:58 -0400
Subject: [PATCH] Add foundations for CMake support (#254)

We start by creating the top-level `CMakeLists.txt` file, following the
modern CMake guide (https://cliutils.gitlab.io/modern-cmake/).

We already have a `build/` directory, so we'll use `cmake/build` for our
build folder.  We add this to `.gitignore` (using a `*` so as to support
multiple build folders).

We update the release instructions so as to keep the version number in
sync, and the installation instructions so as to explain how to use
CMake.

Helps #215.
---
 .gitignore      |  1 +
 CMakeLists.txt  | 30 ++++++++++++++++++++++++++++++
 RELEASE.md      | 15 ++++++++++++++-
 docs/install.md | 16 ++++++++++++++++
 4 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 CMakeLists.txt

diff --git a/.gitignore b/.gitignore
index a6ef824c..1b3df357 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 /bazel-*
+cmake/build*
diff --git a/CMakeLists.txt b/CMakeLists.txt
new file mode 100644
index 00000000..6daac76d
--- /dev/null
+++ b/CMakeLists.txt
@@ -0,0 +1,30 @@
+# Copyright 2024 Aurora Operations, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# CMake should always be at least as new as your compiler[1].  Clang 14 was released on March 25,
+# 2022, and is our newest officially supported compiler.  The next CMake release was v3.23.0, on
+# March 29, 2022.  Therefore, our minimum version must be at least CMake 3.23.
+#
+# The maximum version should be the latest version we've tested the project with.
+#
+# [1]: https://cliutils.gitlab.io/modern-cmake/chapters/intro/dodonot.html
+cmake_minimum_required(VERSION 3.23...3.29)
+
+project(
+   Au
+   VERSION 0.3.4
+   DESCRIPTION "A C++ quantities and units library, by Aurora Innovation"
+   HOMEPAGE_URL "https://aurora-opensource.github.io/au/0.3.4/"
+   LANGUAGES CXX
+)
diff --git a/RELEASE.md b/RELEASE.md
index 40c03cd8..0d6ffc05 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -52,6 +52,17 @@ Any empty section can be omitted.
 We try to follow [semantic versioning](https://semver.org/).  Since we are currently in major
 version zero (0.y.z), incompatible changes don't force a major version upgrade.
 
+### Update the CMake version number
+
+Edit the `CMakeLists.txt` file in the root folder, updating the version number in the `project`
+command to the number chosen above.
+
+Also update the version number in the `HOMEPAGE_URL` parameter, because we link to the docs for the
+latest release in our CMake project definition.  (True, this URL won't exist until you complete the
+remaining steps in this guide, but the danger of getting it wrong is pretty small.)
+
+Make a PR with these changes and land it before creating the tag.
+
 ### Fill out release notes template
 
 The first line should be the tag name.
@@ -102,7 +113,9 @@ Issues!  Alphabetically:
 
 ### Create the tag
 
-Use the command below, replacing `0.3.1` with the version to create.
+First, make sure the "final commit" (which updates the CMake variables) has already landed.
+
+Then, use the command below, replacing `0.3.1` with the version to create.
 
 ```sh
 # Remember to update the tag number!
diff --git a/docs/install.md b/docs/install.md
index 840e4821..7986c062 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -247,6 +247,22 @@ attribute, and include the appropriate files.
 | `@au//au:io` | `"au/io.hh"` | `operator<<` support |
 | `@au//au:testing` | `"au/testing.hh"` | Utilities for testing<br>_Note:_ `testonly = True` |
 
+#### CMake
+
+CMake support is still experimental and in-progress.  We are building it up starting from "root"
+targets (that is, targets without dependencies), and expanding support to the rest of the library.
+
+To build the library using this experimental CMake support, follow these steps:
+
+```sh
+# CMake is a "meta build system", not a build system.
+# This first command generates the actual build files.
+cmake -B cmake/build -S .
+
+# This command builds the library.
+cmake --build cmake/build
+```
+
 #### Other build systems (CMake / conan / vcpkg / ...)
 
 We would like to support all these build and packaging systems, and perhaps others!  But the initial