Add GEO_UTILS_BUILD_TESTS and GEO_UTILS_BUILD_EXAMPLES options

.github/workflows/ci.yml

@@ -61,7 +61,7 @@ jobs:
           key: ${{ runner.os }}-${{ matrix.name }}-googletest-1.14.0
 
       - name: Configure
-        run: cmake -S . -B build -DBUILD_TESTING=ON
+        run: cmake -S . -B build -DGEO_UTILS_BUILD_TESTS=ON -DGEO_UTILS_BUILD_EXAMPLES=ON
 
       - name: Build
         run: cmake --build build --config Release

.github/workflows/coverage.yml

@@ -4,7 +4,7 @@
 # then generates a Cobertura-XML report scoped to include/ (the public headers).
 # The report is uploaded to Codecov for tracking over time.
 #
-# Linux-only: relies on gcc + gcov; the ENABLE_COVERAGE option in CMakeLists.txt
+# Linux-only: relies on gcc + gcov; the GEO_UTILS_ENABLE_COVERAGE option in CMakeLists.txt
 # is GCC/Clang-specific.
 #
 # Triggered automatically on push/PR to master/main; can also be run manually
@@ -42,7 +42,7 @@ jobs:
         run: pip install gcovr
 
       - name: Configure
-        run: cmake -S . -B build -DBUILD_TESTING=ON -DENABLE_COVERAGE=ON
+        run: cmake -S . -B build -DGEO_UTILS_BUILD_TESTS=ON -DGEO_UTILS_ENABLE_COVERAGE=ON
 
       - name: Build
         run: cmake --build build

CHANGELOG.md

@@ -33,7 +33,10 @@ geometry, no runtime dependencies.
 - `find_package(GeoUtils 1.0 REQUIRED)` after `cmake --install`.
 - `FetchContent_Declare(GeoUtils ...)` for in-tree consumption.
 - `SameMajorVersion` package compatibility.
-- `ENABLE_COVERAGE` option for gcov instrumentation (GCC/Clang).
+- Build options `GEO_UTILS_BUILD_TESTS` and `GEO_UTILS_BUILD_EXAMPLES` —
+  default ON when geo-utils is the top-level project, OFF when consumed via
+  `add_subdirectory` or `FetchContent`.
+- `GEO_UTILS_ENABLE_COVERAGE` option for gcov instrumentation (GCC/Clang only).
 
 ### Tests & examples
 

CMakeLists.txt

@@ -1,7 +1,18 @@
 cmake_minimum_required(VERSION 3.14)
 project(GeoUtils VERSION 1.0.0 LANGUAGES CXX)
 
-option(ENABLE_COVERAGE "Enable gcov coverage instrumentation (GCC/Clang only). Requires BUILD_TESTING=ON." OFF)
+if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+    set(_geo_utils_is_top_level ON)
+else()
+    set(_geo_utils_is_top_level OFF)
+endif()
+
+include(CMakeDependentOption)
+option(GEO_UTILS_BUILD_TESTS    "Build geo-utils tests"    ${_geo_utils_is_top_level})
+option(GEO_UTILS_BUILD_EXAMPLES "Build geo-utils examples" ${_geo_utils_is_top_level})
+cmake_dependent_option(GEO_UTILS_ENABLE_COVERAGE
+    "Enable gcov coverage instrumentation (GCC/Clang only)" OFF
+    "GEO_UTILS_BUILD_TESTS" OFF)
 
 # Header-only interface target
 add_library(geo_utils INTERFACE)
@@ -16,10 +27,22 @@ target_include_directories(geo_utils INTERFACE
 )
 target_compile_features(geo_utils INTERFACE cxx_std_17)
 
-# Tests (optional, enabled when this is the top-level project)
-if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+# Tests
+if(GEO_UTILS_BUILD_TESTS)
     include(CTest)
-    if(BUILD_TESTING)
+    include(GoogleTest)
+
+    if(TARGET gtest)
+        # Someone upstream (the consuming project, or an earlier add_subdirectory)
+        # already set up googletest. Reuse those targets — don't try to find or
+        # fetch our own. Add the legacy GTest:: aliases only if they're missing.
+        if(NOT TARGET GTest::GTest)
+            add_library(GTest::GTest ALIAS gtest)
+        endif()
+        if(NOT TARGET GTest::Main)
+            add_library(GTest::Main ALIAS gtest_main)
+        endif()
+    else()
         find_package(GTest QUIET)
         if(NOT GTest_FOUND)
             include(FetchContent)
@@ -28,28 +51,50 @@ if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
                 URL https://github.com/google/googletest/archive/v1.14.0.tar.gz
                 DOWNLOAD_EXTRACT_TIMESTAMP ON
             )
-            # Prevent overriding the parent project's compiler/linker settings on Windows
-            set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
-            # Don't leak GTest into our install prefix
-            set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
+            # Prevent overriding the parent project's compiler/linker settings on Windows.
+            # Local (non-cache) variables — relies on CMP0077 (NEW since CMake 3.13,
+            # default at our cmake_minimum_required of 3.14) so the option() calls
+            # inside googletest don't overwrite these.
+            set(gtest_force_shared_crt ON)
+            # Don't leak GTest into our install prefix.
+            set(INSTALL_GTEST OFF)
             FetchContent_MakeAvailable(googletest)
             # FetchContent creates 'gtest'/'gtest_main'; alias to match find_package names
             add_library(GTest::GTest ALIAS gtest)
             add_library(GTest::Main  ALIAS gtest_main)
         endif()
+    endif()
 
-        add_executable(geo_utils_tests tests/tests.cpp)
-        target_link_libraries(geo_utils_tests
-            PRIVATE geo::utils GTest::GTest GTest::Main
-        )
-        add_test(NAME geo_utils_tests COMMAND geo_utils_tests)
+    add_executable(geo_utils_tests tests/tests.cpp)
+    target_link_libraries(geo_utils_tests
+        PRIVATE geo::utils GTest::GTest GTest::Main
+    )
+    gtest_discover_tests(geo_utils_tests)
 
-        if(ENABLE_COVERAGE)
-            target_compile_options(geo_utils_tests PRIVATE --coverage)
-            target_link_options(geo_utils_tests PRIVATE --coverage)
+    if(GEO_UTILS_ENABLE_COVERAGE)
+        # `--coverage` is split: compile inserts gcov hooks, link pulls in the
+        # gcov runtime. The compiler-flag check must include both stages — see
+        # CMAKE_REQUIRED_LINK_OPTIONS (CMake 3.14+). Otherwise the test object
+        # compiles fine but link fails on missing gcov symbols, giving a false
+        # negative on toolchains that actually support the flag (e.g. AppleClang).
+        include(CheckCXXCompilerFlag)
+        set(CMAKE_REQUIRED_LINK_OPTIONS --coverage)
+        check_cxx_compiler_flag(--coverage GEO_UTILS_HAS_COVERAGE_FLAG)
+        unset(CMAKE_REQUIRED_LINK_OPTIONS)
+
+        if(NOT GEO_UTILS_HAS_COVERAGE_FLAG)
+            message(FATAL_ERROR
+                "GEO_UTILS_ENABLE_COVERAGE=ON requested, but the C++ compiler "
+                "(${CMAKE_CXX_COMPILER_ID}) does not support --coverage. "
+                "Coverage instrumentation requires GCC or Clang.")
         endif()
+        target_compile_options(geo_utils_tests PRIVATE --coverage)
+        target_link_options(geo_utils_tests PRIVATE --coverage)
     endif()
+endif()
 
+# Examples
+if(GEO_UTILS_BUILD_EXAMPLES)
     add_subdirectory(examples)
 endif()
 

docs/getting-started.md

@@ -112,10 +112,16 @@ int main() {
 }
 ```
 
+## Build options
+
+- `GEO_UTILS_BUILD_TESTS`    — build unit tests (default: ON if top-level, OFF otherwise)
+- `GEO_UTILS_BUILD_EXAMPLES` — build examples   (default: ON if top-level, OFF otherwise)
+- `GEO_UTILS_ENABLE_COVERAGE` — gcov instrumentation, GCC/Clang only (default: OFF)
+
 ## Building and testing
 
 ```sh
-cmake -S . -B build -DBUILD_TESTING=ON
+cmake -S . -B build
 cmake --build build
 ctest --test-dir build --output-on-failure
 ```

examples/CMakeLists.txt

@@ -1,7 +1,7 @@
 foreach(example spherical poly)
     add_executable(example_${example} ${example}.cpp)
     target_link_libraries(example_${example} PRIVATE geo::utils)
-    if(BUILD_TESTING)
+    if(GEO_UTILS_BUILD_TESTS)
         add_test(NAME example_${example} COMMAND example_${example})
     endif()
 endforeach()