mirror of
https://github.com/scylladb/scylladb.git
synced 2026-04-20 08:30:35 +00:00
33bca2428a
Document the purpose, usage, and examples for scripts/compare_build_systems.py which compares the configure.py and CMake build systems by parsing their ninja build files.
156 lines
5.4 KiB
Markdown
156 lines
5.4 KiB
Markdown
# 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.
|
|
|