spec: S1 0.3.0, generated files and the path the build writes them to

[speak-agent]

Summary

S1 0.3.0 adds the generated field to a set's ide object (section 7.2). Each entry describes one file or directory that the build generates and that the set's units compile or include:

• path: the path the document names;
• build-path: the path the build of the same configuration writes;
• kind: source, header or directory;
• generator, for a file only: id, inputs, arguments and work-directory of the step that writes it.

A consumer does not report a reference to a missing generated file as an error in the referring source (S1-7.2-10). It may read the build's copy read-only, treating it as possibly stale (S1-7.2-12), and it runs a step only with its user's consent (S1-7.2-13).

Motivation

mcpp-community/mcpp#724. mcpp emit build-database plans in a private directory, and it writes nothing into the project and runs no build step. A header that a rule generates is therefore absent there, and every source that includes it loses its semantics. The plan already knows each generating step, its inputs and its outputs. This addition lets the producer state these facts, and it leaves the decision to run a generator with the consumer and its user.

Compatibility

The change is additive. A 0.2.0 consumer ignores the field (S1-11.2-1), and the schema accepts every 0.2.0 document.

Contents

• Specification. docs/specs/s1-build-database.md gains section 7.2, with rules S1-7.2-1 to S1-7.2-13, and the profile version becomes 0.3.0. The schema, the README, the two S1 examples (their profile-version) and the CHANGELOG are updated to match.
• Traceability. conformance/traceability.json records the producer rules as manual evidence; the producer is mcpp, whose e2e 815 checks the fields. The four consumer rules are listed as $pending until the server reads the field.

Test plan

• python3 docs/specs/tools/validate.py: 0 failures. It reports 258 rules and 4 pending.