# Comparing Build Systems: configure.py vs CMake

ScyllaDB has two build systems: the primary `configure.py` + Ninja pipeline
and an alternative CMake build (used mainly for IDE integration — CLion,
clangd, etc.).  Both must produce equivalent compilation and link commands.

`scripts/compare_build_systems.py` verifies this by parsing the `build.ninja`
files generated by each system and comparing:

1. **Per-file compilation flags** — defines, warnings, optimization, language
   flags for every Scylla source file.
2. **Link target sets** — are the same executables produced by both systems?
3. **Per-target linker settings** — link flags and libraries for every common
   executable.

`configure.py` is treated as the baseline.  CMake should match it.

## Quick start

```bash
# Compare a single mode
scripts/compare_build_systems.py -m dev

# Compare all modes
scripts/compare_build_systems.py

# Verbose output — show per-file and per-target differences
scripts/compare_build_systems.py -m debug -v
```

The script automatically configures both build systems into a temporary
directory for every run — the user's existing build tree is never touched.
No manual `configure.py` or `cmake` invocation is required.

## Mode mapping

| configure.py | CMake            |
|--------------|------------------|
| `debug`      | `Debug`          |
| `dev`        | `Dev`            |
| `release`    | `RelWithDebInfo` |
| `sanitize`   | `Sanitize`       |
| `coverage`   | `Coverage`       |

## Examples

```bash
# Check dev mode only (fast, most common during development)
scripts/compare_build_systems.py -m dev

# Check all modes
scripts/compare_build_systems.py

# CI mode: quiet, strict (exit 1 on any diff)
scripts/compare_build_systems.py --ci

# Verbose output for debugging a specific mode
scripts/compare_build_systems.py -m sanitize -v

# Quiet mode — only prints summary and errors
scripts/compare_build_systems.py -m dev -q
```

## Exit codes

| Code | Meaning                                                                  |
|------|--------------------------------------------------------------------------|
| `0`  | All checked modes match                                                  |
| `1`  | Differences found                                                        |
| `2`  | Configuration failure or some modes could not be compared (e.g. skipped) |

## What it ignores

The script intentionally ignores certain structural differences that are
inherent to how the two build systems work:

- **Include paths** (`-I`, `-isystem`) — directory layout differs between
  the two systems.
- **LTO/PGO flags** — these are configuration-dependent options, not
  mode-inherent.
- **Internal library targets** — CMake creates intermediate static/shared
  libraries (e.g., `scylla-main`, `test-lib`, abseil targets) while
  `configure.py` links `.o` files directly.
- **Per-component Boost defines** — CMake adds `BOOST_REGEX_DYN_LINK` etc.
  per component; `configure.py` uses a single `BOOST_ALL_DYN_LINK`.

## Typical workflow

After modifying `CMakeLists.txt` or `cmake/mode.*.cmake`:

```bash
# 1. Run the comparison (auto-configures both systems in a temp dir)
scripts/compare_build_systems.py -m dev -v

# 2. Fix any differences, repeat
```

## AI agent workflow

When the script reports mismatches, you can paste its summary output into
an AI coding agent (GitHub Copilot, etc.) and ask it to fix the
discrepancies.  The agent has access to both `configure.py` and the
CMake files and can resolve most differences automatically.

### Example interaction

**1. Run the script:**

```bash
scripts/compare_build_systems.py
```

**2. Copy the summary and paste it to the agent:**

> I ran `scripts/compare_build_systems.py` and got:
>
> ```
> Summary
> ══════════════════════════════════════════════════════════════════════
>   debug      (CMake: Debug          ):  ✗ MISMATCH
>     Compilation: 3 files with flag diffs, 1 sources only in configure.py
>       only-configure.py  defines: -DSOME_FLAG  (3 files)
>     Link targets: 1 only in configure.py
>     Linker: 2 targets with lib diffs
>       lib only in CMake: boost_filesystem  (2 targets)
>   dev        (CMake: Dev            ):  ✗ MISMATCH
>     Compilation: 1 sources only in configure.py
>     Link targets: 1 only in configure.py
>   release    (CMake: RelWithDebInfo ):  ✓ MATCH
>   sanitize   (CMake: Sanitize       ):  ✓ MATCH
>   coverage   (CMake: Coverage       ):  ✓ MATCH
> ```
>
> Please fix all issues and commit according to project guidelines.

**3. The agent will:**

- Identify each discrepancy (missing sources, missing targets, extra
  libraries, missing defines).
- Trace root causes — e.g., a test added to `configure.py` but not to
  `test/boost/CMakeLists.txt`, or an unnecessary `Boost::filesystem`
  link in a CMake target.
- Apply fixes to the appropriate `CMakeLists.txt` files.
- Re-run cmake and the comparison script to verify the fix.
- Commit each fix to the correct commit in the series (using
  `git commit --fixup` + `git rebase --autosquash`).

### Tips

- **Paste the full summary block** — the inline diff details (compilation,
  link targets, linker) give the agent enough context to act without
  scrolling through verbose output.
- **Use `-v` for stubborn issues** — if the agent needs per-file or
  per-target detail, re-run with `-v` and paste the relevant section.