scylladb/docs/dev/compare-build-systems.md

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

# 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

# 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:

# 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:

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.