feat: major build system improvements with multi-compiler support and sanitizers

Completely overhaul the build system with production-quality features:

Build System:
  - Add comprehensive warning flags (-Wall, -Wextra, -Wpedantic, etc.)
  - Enable -Werror for Debug builds, warnings-only for Release
  - Add ASAN, UBSAN, and TSAN support with proper CMake options
  - Make benchmarks opt-in (BUILD_BENCHMARKS) to save ~30-40% compile time
  - Disable sanitizers for GCC on macOS (not supported)

Build Scripts:
  - Rewrite build.sh with automatic compiler detection
  - Support multiple compilers: gcc-15/14/13, clang-19/18/17, llvm, appleclang
  - Add --list-compilers flag to show available compilers
  - Generic compiler selection (gcc → latest available)
  - Show full version numbers (e.g., "GCC 15.2.0")
  - Save compiler preferences to .build_config
  - Auto-clean when switching compilers to avoid CMake cache issues
  - Improved error messages with suggestions ("Did you mean 'appleclang'?")

Build Modes:
  - debug: ASAN + UBSAN, warnings as errors
  - debug-tsan: TSAN, warnings as errors
  - release: Optimized, no sanitizers, warnings enabled

Scripts:
  - Update test.sh to default to debug mode (ASAN + UBSAN)
  - Update benchmark.sh to auto-enable BUILD_BENCHMARKS
  - Update run.sh to support all build modes

CI:
  - Update to Debug builds with ASAN + UBSAN on all platforms
  - Test with GCC 14 and Clang on Linux
  - Test with AppleClang on macOS
  - Skip benchmarks in CI (unreliable on shared runners)

Documentation:
  - Comprehensive README.md update with build modes, compiler selection
  - Update CONTRIBUTING.md with sanitizer info, build instructions
  - Add sanitizer support matrix

This follows industry best practices from projects like Abseil, LLVM, and Google Benchmark.

Author: jasonjdominguez99

.github/workflows/ci.yml

@@ -28,23 +28,25 @@ jobs:
         sudo apt-get update
         sudo apt-get install -y gcc-14 g++-14
 
-    - name: Configure CMake
+    - name: Configure CMake (Debug with ASAN + UBSAN)
       run: |
         if [ "${{ matrix.compiler }}" = "gcc" ]; then
           export CC=gcc-14 CXX=g++-14
         else
           export CC=clang CXX=clang++
         fi
-        cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -G Ninja
+        cmake -B build -S . \
+          -DCMAKE_BUILD_TYPE=Debug \
+          -DENABLE_ASAN=ON \
+          -DENABLE_UBSAN=ON \
+          -DENABLE_TSAN=OFF \
+          -G Ninja
 
     - name: Build
-      run: cmake --build build --config Release
-
-    - name: Run tests
-      run: cd build && ctest --output-on-failure -C Release
+      run: cmake --build build --config Debug
 
-    - name: Run benchmarks (quick)
-      run: ./build/benchmarks/hello_world_benchmark --benchmark_min_time=0.1s
+    - name: Run tests with sanitizers
+      run: cd build && ctest --output-on-failure -C Debug
 
   build-macos:
     runs-on: macos-latest
@@ -53,26 +55,22 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Install dependencies
-      run: |
-        brew install cmake ninja llvm
+      run: brew install cmake ninja
 
-    - name: Configure CMake with Homebrew LLVM
+    - name: Configure CMake (Debug with ASAN + UBSAN)
       run: |
-        export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
         cmake -B build -S . \
-          -DCMAKE_BUILD_TYPE=Release \
-          -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang \
-          -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ \
+          -DCMAKE_BUILD_TYPE=Debug \
+          -DENABLE_ASAN=ON \
+          -DENABLE_UBSAN=ON \
+          -DENABLE_TSAN=OFF \
           -G Ninja
 
     - name: Build
-      run: cmake --build build --config Release
-
-    - name: Run tests
-      run: cd build && ctest --output-on-failure -C Release
+      run: cmake --build build --config Debug
 
-    - name: Run benchmarks (quick)
-      run: ./build/benchmarks/hello_world_benchmark --benchmark_min_time=0.1s
+    - name: Run tests with sanitizers
+      run: cd build && ctest --output-on-failure -C Debug
 
   coverage:
     runs-on: ubuntu-latest

.gitignore

@@ -43,6 +43,7 @@
 # Build files
 build/
 cmake-build-*/
+.build_config
 
 # CMake
 CMakeCache.txt

CMakeLists.txt

@@ -9,20 +9,28 @@ set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
+# Define warning flags for project targets only (not third-party dependencies)
+set(PROJECT_WARNING_FLAGS -Wall -Wextra -Wpedantic -Wshadow -Wuninitialized
+                          -Wconversion)
+
+# Add compiler-specific warnings
+if(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  list(APPEND PROJECT_WARNING_FLAGS -Wmost -Wthread-safety)
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "GNU")
+  list(APPEND PROJECT_WARNING_FLAGS -Wduplicated-cond -Wlogical-op)
+endif()
+
+# Add -Werror for Debug builds only
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+  list(APPEND PROJECT_WARNING_FLAGS -Werror)
+endif()
+
 # Only disable Apple-specific flags if using GCC on macOS
 if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
   message(STATUS "Using GCC on macOS - disabling Apple-specific flags")
   set(CMAKE_OSX_ARCHITECTURES "")
   set(CMAKE_OSX_SYSROOT "")
   set(CMAKE_OSX_DEPLOYMENT_TARGET "")
-  # GCC on macOS doesn't support TSAN well, disable it
-  set(ENABLE_TSAN
-      OFF
-      CACHE BOOL "TSAN not supported with GCC on macOS" FORCE)
-  message(
-    WARNING
-      "Thread Sanitizer (TSAN) is not supported with GCC on macOS ARM64 - disabling"
-  )
 endif()
 
 # Configure Homebrew LLVM/Clang to use the correct libc++
@@ -49,7 +57,50 @@ endif()
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 # Add sanitizer options
-option(ENABLE_TSAN "Enable Thread Sanitizer" ON)
+option(ENABLE_ASAN "Enable Address Sanitizer" OFF)
+option(ENABLE_UBSAN "Enable Undefined Behavior Sanitizer" OFF)
+option(ENABLE_TSAN "Enable Thread Sanitizer" OFF)
+
+# GCC on macOS doesn't include sanitizer runtime libraries - disable them
+if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+  if(ENABLE_ASAN)
+    message(
+      WARNING
+        "Address Sanitizer (ASAN) is not supported with GCC on macOS - disabling"
+    )
+    set(ENABLE_ASAN
+        OFF
+        CACHE BOOL "ASAN not supported with GCC on macOS" FORCE)
+  endif()
+  if(ENABLE_UBSAN)
+    message(
+      WARNING
+        "Undefined Behavior Sanitizer (UBSAN) is not supported with GCC on macOS - disabling"
+    )
+    set(ENABLE_UBSAN
+        OFF
+        CACHE BOOL "UBSAN not supported with GCC on macOS" FORCE)
+  endif()
+  if(ENABLE_TSAN)
+    message(
+      WARNING
+        "Thread Sanitizer (TSAN) is not supported with GCC on macOS - disabling"
+    )
+    set(ENABLE_TSAN
+        OFF
+        CACHE BOOL "TSAN not supported with GCC on macOS" FORCE)
+  endif()
+endif()
+
+if(ENABLE_ASAN)
+  add_compile_options(-fsanitize=address)
+  add_link_options(-fsanitize=address)
+endif()
+
+if(ENABLE_UBSAN)
+  add_compile_options(-fsanitize=undefined)
+  add_link_options(-fsanitize=undefined)
+endif()
 
 if(ENABLE_TSAN)
   add_compile_options(-fsanitize=thread)
@@ -78,38 +129,51 @@ set(gtest_force_shared_crt
     CACHE BOOL "" FORCE)
 FetchContent_MakeAvailable(googletest)
 
-# Fetch Google Benchmark
-FetchContent_Declare(
-  googlebenchmark
-  GIT_REPOSITORY https://github.com/google/benchmark.git
-  GIT_TAG v1.9.1)
-set(BENCHMARK_ENABLE_TESTING
-    OFF
-    CACHE BOOL "" FORCE)
-set(BENCHMARK_ENABLE_GTEST_TESTS
-    OFF
-    CACHE BOOL "" FORCE)
-set(HAVE_STD_REGEX
-    ON
-    CACHE BOOL "" FORCE)
-set(RUN_HAVE_STD_REGEX
-    1
-    CACHE STRING "" FORCE)
-FetchContent_MakeAvailable(googlebenchmark)
+# Benchmark support (opt-in, use ./scripts/benchmark.sh to enable)
+option(BUILD_BENCHMARKS "Build benchmark executables" OFF)
+
+if(BUILD_BENCHMARKS)
+  FetchContent_Declare(
+    googlebenchmark
+    GIT_REPOSITORY https://github.com/google/benchmark.git
+    GIT_TAG v1.9.1)
+  set(BENCHMARK_ENABLE_TESTING
+      OFF
+      CACHE BOOL "" FORCE)
+  set(BENCHMARK_ENABLE_GTEST_TESTS
+      OFF
+      CACHE BOOL "" FORCE)
+  set(HAVE_STD_REGEX
+      ON
+      CACHE BOOL "" FORCE)
+  set(RUN_HAVE_STD_REGEX
+      1
+      CACHE STRING "" FORCE)
+  FetchContent_MakeAvailable(googlebenchmark)
+endif()
 
 # Main library
 add_library(hello_world STATIC src/hello_world.cpp)
 target_include_directories(
   hello_world PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
                      $<INSTALL_INTERFACE:include>)
+target_compile_options(hello_world PRIVATE ${PROJECT_WARNING_FLAGS})
 
 # Main executable
 add_executable(hello_world_demo src/main.cpp)
 target_link_libraries(hello_world_demo PRIVATE hello_world)
+target_compile_options(hello_world_demo PRIVATE ${PROJECT_WARNING_FLAGS})
 
 # Enable testing
 enable_testing()
 
 # Add subdirectories
 add_subdirectory(tests)
-add_subdirectory(benchmarks)
+
+if(BUILD_BENCHMARKS)
+  add_subdirectory(benchmarks)
+  message(STATUS "Benchmarks enabled")
+else()
+  message(
+    STATUS "Benchmarks disabled (run ./scripts/benchmark.sh to build and run)")
+endif()