# CMake Error: check_cxx_source_compiles failed with: <compiler error output>

- **ID:** `cmake/check-cxx-source-compiles-failed`
- **Domain:** cmake
- **Category:** build_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

A C++ source snippet provided to check_cxx_source_compiles() fails to compile, often due to missing headers, incorrect syntax, or incompatible compiler flags.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| CMake 3.10 | active | — | — |
| CMake 3.16 | active | — | — |
| CMake 3.22 | active | — | — |
| CMake 3.27 | active | — | — |

## Workarounds

1. **Inspect the compiler error output to identify missing headers or syntax issues, then fix the source snippet or add required include directories.** (85% success)
   ```
   Inspect the compiler error output to identify missing headers or syntax issues, then fix the source snippet or add required include directories.
   ```
2. **Set CMAKE_REQUIRED_FLAGS or CMAKE_REQUIRED_LIBRARIES to match the project's compile environment.** (80% success)
   ```
   Set CMAKE_REQUIRED_FLAGS or CMAKE_REQUIRED_LIBRARIES to match the project's compile environment.
   ```

## Dead Ends

- **Adding -Werror or other flags globally to suppress warnings, hoping the snippet compiles** — The error is usually a hard compile failure, not a warning. Adding flags may introduce more issues. (90% fail)
- **Removing the check entirely, assuming the feature is available** — The check is there for a reason; removing it may lead to runtime errors or build failures later. (85% fail)
- **Copying the exact snippet into a standalone file and compiling it manually, then ignoring the CMake error** — Even if it compiles manually, the CMake check may have different include paths or flags; manual success does not guarantee CMake success. (70% fail)