Add CMake install commands for Au (#265)

We may have gotten the project to _build_ under CMake, but _other_
projects can't actually _use_ it unless we provide `install` commands.

First, we add an `install(TARGETS...)` command (based on the
`GNUInstallDirs` module) to the `header_only_library()` function.  We
install it as part of an export set, whose name we set with a global
variable (which must be defined before we load this file).

The tricky bit is that this can't work unless the actual code itself is
in a subdirectory of the repo, _not_ the root folder, for reasons I only
dimly understand.  To make this work, we now provide the Au code via a
symlink, which we create inside of a new `cmake/project_symlinks`
folder.  This lets us refer to this folder in the `BASE_DIRS` variable.

In the main CMake file, we add the installation command for the export
set we've been building up.  We also write and install the package
config and version files.

The above changes would break bazel support, because there would be
BUILD files reachable underneath `cmake`, both via the `au` symlink, and
via `cmake/build`.  To fix this, we make `cmake/` a fake local
repository, causing bazel to skip it.

To test, create a new project with two files:

`main.cc`:

```cpp
#include "au/au.hh"

int main(int argc, char **argv) { return 0; }
```

`CMakeLists.txt`:

```cmake
cmake_minimum_required(VERSION 3.29)

project(CppUnitsCompare)

include(FetchContent)
FetchContent_Declare(
  Au
  GIT_REPOSITORY https://github.com/aurora-opensource/au
  GIT_TAG "chiphogg/cmake-install#215"
)
FetchContent_MakeAvailable(Au)

add_executable(CppUnitsCompare main.cpp)
target_link_libraries(CppUnitsCompare PUBLIC Au::au)
```

And execute:

```sh
cmake -S . -B build
cmake --build build
```

Helps #215.

.github/license-check/license-config.json

@@ -18,7 +18,8 @@
       ".github/**/*.yml",
       "requirements.in",
       "cmake/*.cmake",
-      "WORKSPACE"
+      "cmake/*.cmake.in",
+      "**/WORKSPACE"
     ],
     "exclude": [
       "third_party/**/*"

CMakeLists.txt

@@ -32,6 +32,9 @@ project(
    LANGUAGES CXX
 )
 
+# The export set for all of our headers.
+set(AU_EXPORT_SET_NAME AuHeaders)
+
 enable_testing()
 
 # Bring in GoogleTest so we can build and run the tests.
@@ -52,4 +55,36 @@ set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
 FetchContent_MakeAvailable(googletest)
 include(GoogleTest)
 
-add_subdirectory(au)
+add_subdirectory(cmake/project_symlinks)
+
+# Configure how Au will be installed.
+#
+# (This is necessary for it to be usable in other CMake projects.)
+
+set(AU_CMAKE_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/Au)
+
+install(
+   EXPORT ${AU_EXPORT_SET_NAME}
+   DESTINATION ${AU_CMAKE_DIR}
+   NAMESPACE Au::
+   FILE AuHeaders.cmake
+)
+
+include(CMakePackageConfigHelpers)
+configure_package_config_file(
+   ${CMAKE_CURRENT_SOURCE_DIR}/cmake/AuConfig.cmake.in
+   AuConfig.cmake
+   INSTALL_DESTINATION ${AU_CMAKE_DIR}
+)
+
+write_basic_package_version_file(
+   AuConfigVersion.cmake
+   COMPATIBILITY SameMinorVersion
+)
+
+install(
+   FILES
+      ${CMAKE_CURRENT_BINARY_DIR}/AuConfig.cmake
+      ${CMAKE_CURRENT_BINARY_DIR}/AuConfigVersion.cmake
+   DESTINATION ${AU_CMAKE_DIR}
+)

WORKSPACE

@@ -216,3 +216,11 @@ http_archive(
 
 # END SECTION: Install buildifier.
 ################################################################################
+
+# This is not a "real" local bazel repository.  We define this in this WORKSPACE
+# file because it will prevent bazel from looking for packages in this folder
+# and its children.
+local_repository(
+    name = "ignore_cmake",
+    path = "./cmake",
+)

au/CMakeLists.txt

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-include(../cmake/HeaderOnlyLibrary.cmake)
+include("${PROJECT_SOURCE_DIR}/cmake/HeaderOnlyLibrary.cmake")
 
 #
 # Publicly exported targets

cmake/AuConfig.cmake.in

@@ -0,0 +1,19 @@
+# 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.
+
+@PACKAGE_INIT@
+
+include(${CMAKE_CURRENT_LIST_DIR}/AuHeaders.cmake)
+
+check_required_components(Au)

cmake/HeaderOnlyLibrary.cmake

@@ -45,7 +45,7 @@ function(header_only_library)
     ${ARG_NAME}
     INTERFACE
     FILE_SET HEADERS
-    BASE_DIRS ${CMAKE_SOURCE_DIR}
+    BASE_DIRS "${PROJECT_SOURCE_DIR}/cmake/project_symlinks"
     FILES ${ARG_HEADERS}
   )
   if (DEFINED ARG_DEPS)
@@ -61,8 +61,19 @@ function(header_only_library)
   # See: https://stackoverflow.com/a/68321274
   if (ARG_INTERNAL_ONLY)
     set_target_properties(${ARG_NAME} PROPERTIES EXPORT_NAME "_Au_private_${ARG_NAME}")
+  else()
+    add_library(Au::${ARG_NAME} ALIAS ${ARG_NAME})
   endif()
 
+  # Install the library.  (This is required for other projects to use Au via CMake.)
+  include(GNUInstallDirs)
+  install(
+    TARGETS ${ARG_NAME}
+    EXPORT ${AU_EXPORT_SET_NAME}
+    FILE_SET HEADERS
+    INCLUDES DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+  )
+
   # Add the test, if requested.
   if (DEFINED ARG_GTEST_SRCS)
     add_executable("${ARG_NAME}_test")

cmake/WORKSPACE

@@ -0,0 +1,15 @@
+# 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.
+
+# This file exists so that bazel will ignore this folder.

cmake/project_symlinks/CMakeLists.txt

@@ -0,0 +1,15 @@
+# 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.
+
+add_subdirectory(au)

cmake/project_symlinks/au

@@ -0,0 +1 @@
+../../au