1. Transforming a Project#

clang-ssaf-driver runs a source transformation over a whole project as it builds, and presents what it found: the source edits as a patch, the transformation report as diagnostics and as SARIF, and, if asked, the edits applied to the sources. It drives projects built with make through clang-ssaf-orchestrator-make, whose requirements it shares; see Make-Based Projects.

1.1. Usage#

Run it from the project root, with its options before the build command:

$ clang-ssaf-driver --transformation=cpp-bounded-buffers -- make -j8

The driver knows which summaries and which whole-program analysis each transformation needs:

Transformation	What it does
`cpp-bounded-buffers`	Rewrites the raw pointers and arrays that need bounds into `bounded_ptr` and `bounded_array`.

1.2. Results#

A run writes two files into the output directory:

<transformation>.patch, the source edits as one unified diff whose paths are relative to the project root, for patch -p1 from there;
<transformation>.sarif, the transformation report: the findings of every translation unit, and every conflict between source edits.

Both are named on stdout, after the orchestrator’s own results:

patch: /work/proj/ssaf-output/cpp-bounded-buffers.patch
report: /work/proj/ssaf-output/cpp-bounded-buffers.sarif

The report is also printed on stderr, one line per finding the way a compiler prints a diagnostic, and closes with a count for each rule:

src/shared.h:1:8: note: declarator of a multi-declarator group is not yet rewritten [cpp-bounded-buffers-skipped]
src/shared.h:3:1: error: 2 overlapping replacement(s) at file:///work/proj/src/shared.h byte 20 were dropped; resolve manually. [clang-reforge-replacement-conflict]
src/shared.h:5:1: note: candidate edit: "bounded_ptr<int> "
src/shared.h:3:1: note: candidate edit: "bounded_ptr<long> "
1 clang-reforge-replacement-conflict, 1 cpp-bounded-buffers-skipped reported

A finding is a place the transformation did not rewrite. A conflict is a place where translation units asked for different edits; none of them is made, and an edit that overlaps a conflict is left out of the patch too, with a warning. Both are left to be done by hand, and neither changes the exit status.

1.3. Applying the edits#

--apply also rewrites the sources, using clang-apply-replacements from clang-tools-extra. It is looked for on PATH, or named with --clang-apply-replacements=<path>, before anything is built. The patch is written either way, and the run fails if the sources do not end up the way the patch shows them.

1.4. Options#

Option	Purpose
`--transformation=<name>`	The transformation to run. Required.
`-o`, `--output-dir=<dir>`	Where the results and the SSAF artifacts go. Defaults to `ssaf-output`, and is the orchestrator’s output directory.
`--apply`	Also apply the source edits.
`--clang-apply-replacements=<path>`	Path to `clang-apply-replacements`. Defaults to the name on `PATH`.
`--ssaf-clang=<path>`, `--ssaf-linker=<path>`, `--ssaf-analyzer=<path>`, `--ssaf-src-edit-merge=<path>`, `--ssaf-merge-transformation-report=<path>`, `--ssaf-merge-conflict-report=<path>`, `--ssaf-extra-clang-arg=<arg>`, `-k`, `-v`	Passed to the orchestrator; see {doc}`MakeProjects`.
`--version`	The clang version this was built from.

1.5. What is not supported#

Edits outside the project root. A file the project does not contain is left out of the patch and is not applied to; the driver names it in a warning.

Compilations that run in another directory, as in recursive make or make -C. A source edit names its file relative to where its compilation ran, and is merged where the link runs, so such an edit can be lost or land on the wrong file. Run the build from the project root.