Add the first target and test (#258)

`stdx` has no dependencies, so it's a good choice for our first target.
We make an `INTERFACE` target, using `FILE_SET HEADERS` for more modern
handling.  By trial and error, it seems like the right move is to set
the `BASE_DIRS` to the main project folder.  The following other choices
are supported by reading the docs (i.e., Professional CMake, 18th
Edition), specifically, section 16.2.7 on File Sets:

- When we say `FILE_SET HEADERS`, we do not need to provide `TYPE`.
- Providing relative paths is correct, because they will be taken to be
  relative to `CMAKE_CURRENT_SOURCE_DIR`.

We also take advantage of section 32.6, "File Sets Header Verification".
The `CMAKE_VERIFY_INTERFACE_HEADER_SET` variable (which we also reflect
in our docs) will automatically generate synthetic targets that make
sure we got our include paths correct.  We can "run" this "test" by
building the target `all_verify_interface_header_sets`.  This is how I
figured out what to set `BASE_DIRS` to.

On the googletest side, I followed the docs.  We use `FetchContent`, but
fall back to `find_package` in case there's a system-installed version.
This latter behaviour seems highly suspect to me, but the docs were
adamant that this is typically the right move, especially for open
source projects.  See Section 39.8 ("Recommended Practices").  It feels
like it would be nice to _at least_ set a minimum version that we would
accept from the `find_package` fallback, but we can probably defer that
until we get an actual problem report.  (And, honestly, maybe there's
simply no use case for this anyway?  People who want to develop the
tests can use `bazel`, which for Au supports a zero-install setup.  And
people who just want to depend on Au via CMake don't really need to run
the tests.)

Another consideration is _conditionally_ enabling the GoogleTest
dependency, as was done for the branch with the initial CMake support. I
would like to defer adding that complexity until we encounter a concrete
use case that's blocked by it, so I can be sure I understand why we
would want to do that.

It turns out that we can "build-and-run-all-tests, incrementally" with a
single CMake command that builds three named targets: all, "all header
verifications", and test.  I updated the instructions to include this.

Finally, it appears that running the tests can sometimes create a folder
called `Testing`, so I added that to `.gitignore`.

Future PRs will add a bunch more targets.

Helps #215.

.gitignore

@@ -1,2 +1,3 @@
 /bazel-*
 cmake/build*
+Testing

CMakeLists.txt

@@ -16,10 +16,13 @@
 # 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.
 #
+# We also use the `CMAKE_VERIFY_INTERFACE_HEADER_SETS`, which was added in CMake
+# 3.24, which means the minimum must also be at least 3.24.
+#
 # 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)
+cmake_minimum_required(VERSION 3.24...3.29)
 
 project(
    Au
@@ -28,3 +31,25 @@ project(
    HOMEPAGE_URL "https://aurora-opensource.github.io/au/0.3.4/"
    LANGUAGES CXX
 )
+
+enable_testing()
+
+# Bring in GoogleTest so we can build and run the tests.
+include(FetchContent)
+FetchContent_Declare(
+   googletest
+   GIT_REPOSITORY https://github.com/google/googletest.git
+   GIT_TAG 58d77fa8070e8cec2dc1ed015d66b454c8d78850 # Release 1.12.1
+   FIND_PACKAGE_ARGS
+      1.12.1
+      NAMES GTest
+)
+
+# https://google.github.io/googletest/quickstart-cmake.html
+# For Windows: Prevent overriding the parent project's compiler/linker settings
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+
+FetchContent_MakeAvailable(googletest)
+include(GoogleTest)
+
+add_subdirectory(au)

WORKSPACE

@@ -113,6 +113,7 @@ gcc_register_toolchain(
 http_archive(
     name = "com_google_googletest",
     sha256 = "24564e3b712d3eb30ac9a85d92f7d720f60cc0173730ac166f27dda7fed76cb2",
+    # NOTE: if updating this version, also update the version numbers in `CMakelists.txt`.
     strip_prefix = "googletest-release-1.12.1",
     urls = ["https://github.com/google/googletest/archive/refs/tags/release-1.12.1.zip"],
 )

au/CMakeLists.txt

@@ -0,0 +1,43 @@
+# 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_path(GET CMAKE_CURRENT_SOURCE_DIR PARENT_PATH AU_BASE_DIRECTORY)
+
+#
+# Private implementation detail targets
+#
+
+add_library(stdx INTERFACE)
+target_sources(stdx
+   INTERFACE
+   FILE_SET HEADERS
+   BASE_DIRS ${AU_BASE_DIRECTORY}
+   FILES
+      stdx/experimental/is_detected.hh
+      stdx/functional.hh
+      stdx/type_traits.hh
+      stdx/utility.hh
+)
+
+add_executable(stdx_test)
+target_sources(stdx_test
+   PRIVATE
+      stdx/test/utility_test.cc
+)
+target_link_libraries(stdx_test
+   PRIVATE
+      stdx
+      GTest::gtest_main
+)
+gtest_discover_tests(stdx_test)

docs/install.md

@@ -257,10 +257,15 @@ 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
+cmake -S . -B cmake/build -DCMAKE_VERIFY_INTERFACE_HEADER_SETS=TRUE
+
+# This command builds Au, checks include paths, and runs unit tests.
+cmake \
+  --build cmake/build \
+  --target \
+    all \
+    all_verify_interface_header_sets \
+    test
 ```
 
 #### Other build systems (CMake / conan / vcpkg / ...)