From 979a7ae9d3910fac17d03f18877076dbece77db8 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 26 Jun 2026 08:30:22 -0600 Subject: [PATCH] Edits to AGENTS.md file [skip CI] These are agent-suggested updates (OpenCode with Qwen 3.6), plus some edits of mine to the result. In general terms, it suggested removing thing which were instructions to human readers, and some other boilerplate already covered in files it was going to read anyway (README). I mainly filled out the instructions on doc building, because a question I asked left an agent now knowing how to validate a manpage change. Signed-off-by: Mats Wichmann --- AGENTS.md | 145 +++++++++++++++++++++++++++++------------------------- 1 file changed, 78 insertions(+), 67 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 24e626ec1e..04fe33eb66 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,88 +1,99 @@ # SCons - Software Construction Tool -## Project Overview -SCons is an open-source software construction tool (build tool) implemented in Python. It is designed to be easier to use and more reliable than the traditional `make` utility. SCons configuration files are Python scripts, allowing users to use the full power of Python to solve build problems. +## Build & Run -**Key Features:** -* Configuration files are Python scripts. -* Built-in support for C, C++, D, Java, Fortran, Yacc, Lex, Qt, SWIG, and TeX/LaTeX. -* Reliable dependency analysis (implicit and explicit). -* Support for parallel builds. -* Cross-platform (Linux, POSIX, Windows, macOS). - -## Building and Running - -### Prerequisites -* Python 3.7 or higher. -* Development dependencies: `python -m pip install -r requirements-dev.txt` - -### Running SCons (Development) -You do not need to install SCons to run it from the source tree. - -**Linux/macOS:** ```bash -python scripts/scons.py [arguments] +python scripts/scons.py # build packages (wheels, tarballs, zips → build/) +python scripts/scons.py doc # docs only +python scripts/scons.py [args] # run SCons from source (no install needed) ``` +SCons builds itself. The repo root `SConstruct` is the build script for packaging. -**Windows:** -```cmd -py -3 scripts\scons.py [arguments] -``` - -### Building SCons -SCons uses itself to build its own packages. +## Testing -**Full Build (Packages & Docs):** ```bash -python scripts/scons.py +python runtest.py -a # all tests +python runtest.py SCons/SConfTests.py # unit test +python runtest.py test/Configure/ConfigureDryRunError.py # e2e test +python runtest.py --retry # re-run last failures (reads failed_tests.log) +python runtest.py -j 0 # parallel (cpu_count) +python runtest.py -t # print timing ``` -This produces artifacts (wheels, tarballs, zips) in the `build/` directory. -**Build Documentation Only:** +For more complete testing, the dependency set `[dev]` from `pyproject.toml` +is useful. + ```bash -python scripts/scons.py doc +python bin/docs-validate.py +python scripts/scons.py doc SKIP_DOC=pdf,api ``` -## Testing -The project uses a custom test runner script, `runtest.py`. +| Type | Location | Pattern | +|------|----------|---------| +| E2E | `test/**/*.py` | Custom `TestSCons` (subclass of `TestCmd`) with `test.run()` / `test.pass_test()` | +| Unit | `SCons/*Tests.py` | Standard `unittest.TestCase`, also use `TestCmd`/`TestSCons` for setup | + +The test runner (`runtest.py`) adds `SCons/` and `testing/` to `PYTHONPATH` automatically. E2E tests create a temp workdir per run. Use `SCons.Debug.Trace()` for print debugging (won't interfere with test output capture). + +## Codebase Architecture + +**Core engine (`SCons/`):** +- `Script/Main.py` - entry point (`main()`). +- `Environment.py` - `Environment` class; construction variable management. +- `Builder.py` + `Action.py` - define how targets are built and what commands execute. +- `Node/` — dependency graph: `FS.py` (File, Dir, Entry), `Alias.py`, `Python.py`. +- `Taskmaster/` - parallel job scheduling and task execution. +- `SConsign.py` - `.sconsign.dblite` persistence (single file at build top, keyed by dir path). +- `Subst.py` - variable substitution (`$CC`, `$CFLAGS`, etc.). +- `Scanner/` - dependency scanners (C/C++ `#include`, etc.). +- `CacheDir.py` - shared build-artifact cache. +- `SConf.py` - `Configure()` logic. +- `Warnings.py` - warning hierarchy (stderr via `warn()`). +- `Tool/` - compiler/linker integrations (CC, CXX, MSVC, Ninja, Docbook, etc.). +- `Script/` - CLI entry points, option parsing (`SConsOptions.py`). +- `Platform/` - OS-specific adaptations. +- `Variables/` - `PathVariable`, `BoolVariable`, etc., for build configuration. + +**Tests:** +- `testing/framework/` — `TestSCons.py`, `TestCmd.py` (e2e test base classes). +- `test/` — ~200+ e2e tests organized by feature. +- `SCons/*Tests.py` — unit tests alongside source, standard `unittest.TestCase`. + +**Documentation:** +- `doc` documentation sources, tools, extended DocBook schema +- `SCons/*.xml` - module-specific documentation sources + +## Documentation + +The doc build requires the dependency set `[doc]` from `pyproject.toml`. +For validating just that the Docbook xml documents build, use -**Run All Tests:** ```bash -python runtest.py -a +python bin/docs-validate.py +python scripts/scons.py doc SKIP_DOC=pdf,api ``` -**Run Specific Tests:** -```bash -python runtest.py SCons/BuilderTests.py # Unit test -python runtest.py test/option/option-j.py # End-to-end test -``` +Individual xml files are not syntactically complete DocBook, +they require the context of xincluded files (`.mod` and `.gen` +from `doc` and `doc/generated`), the SCons schema extension +(`doc/xsd`), and the framework from `bin/SConsDoc.py`, +which also contains information on some of the extensions. + +## Lint & Type -**Run Failed Tests (Retry):** ```bash -python runtest.py --retry +python -m ruff check . # lint (target-version py37, skips test/ bench/ doc/ etc.) +python -m ruff format --check . # formatting check +python -m mypy SCons/ # type check ``` -**Test Types:** -* **Unit Tests:** Located in `SCons/` alongside the source files (e.g., `SCons/Builder.py` -> `SCons/BuilderTests.py`). -* **End-to-End Tests:** Located in the `test/` directory. These run SCons against sample projects. - -## Development Conventions - -* **Code Style:** Follows Python PEP 8 (mostly). The project includes a `.editorconfig` file. -* **Version Control:** Git is used. Commits should be signed off (`git commit -s`). -* **Debugging:** - * Use `--debug=pdb` when running SCons to drop into the Python debugger. - * Use `SCons.Debug.Trace()` for print debugging in a way that doesn't interfere with test output capturing. -* **Directory Structure:** - * `SCons/`: Core engine source code and unit tests. - * `test/`: End-to-end system tests. - * `scripts/`: Wrapper scripts (e.g., `scons.py`). - * `bin/`: Development utilities. - * `doc/`: Documentation source (DocBook/XML). - * `template/`: Templates for file generation. - * `testing/framework`: Test framework used by the end-to-end tests. - -## AI Contribution Policy -If contributing AI-generated code: -1. You take full responsibility for the code quality and license. -2. Disclose AI use in the commit message (e.g., `Assisted-by: ModelName`). +`.editorconfig` enforces: indent 4 spaces, 88-char line limit (Python/SConstruct/SConscript), LF line endings, trailing comma, parentheses for multiline. + +## Conventions + +- Git commits signed off (`git commit -s`). Add `Assisted-by:` to message for AI-generated changes. +- Version in `SCons/__init__.py` (`__version__`) - automatically generated, do not edit. +- CI: GitHub Actions (`runtest.yml` - test suite; `scons-package.yml` — packaging), AppVeyor (Windows, legacy). +- Python >= 3.7 required. +- Config log for `Configure()` lives at `config.log` in the build dir. +- `.sconsign.dblite` persists across builds; deleting build dirs from disk doesn't clear sconsign entries.