diff --git a/AGENTS.md b/AGENTS.md index ed46bc289..5be9a6a1a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,13 @@ 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. +The generated files can be built on demand +(`python bin/docs-update-generated.py`), +and should never be directly edited. +It is project convention *not* to commit the changes to generated +files as they happen, but rather to commit the accumulated changes +during the release process. + ## Lint & Type ```bash diff --git a/CHANGES.txt b/CHANGES.txt index ab5e5dddc..ff5a68373 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -47,6 +47,11 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Fix the ninja ctrl-c test, which was failing on some platforms. - Reference manual improvements: * Additional clarification for SideEffect() + * Split out a new section on Emitters with additional prose and + examples, since the information does not exclusively apply to + the emitter argument to Builder(). The Builder Objects "emitter" + argument section still has some wording, plus a link to the + new section. - User Guide improvements: * Removed the out-of-date table of option names for SetOption and GetOption and instead point to the maintained tables in Appendix D. diff --git a/RELEASE.txt b/RELEASE.txt index ec2bad6a0..482585ad1 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -87,6 +87,11 @@ DOCUMENTATION generated from the checked-in documentation sources by bin/scons-man-to-ai.py, and can be built with the "ai-manpage" target. +* Split out a new section on Emitters with additional prose and examples, + since the information does not exclusively apply to the emitter argument + to Builder(). The Builder Objects "emitter" argument section still + has some wording, plus a link to the new section. + DEVELOPMENT ----------- diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 5cac483ba..4b9055a5c 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -888,19 +888,17 @@ for a complete explanation of the arguments and behavior. Note that the -env.Builder() +&f-env-Builder; form of the invocation will expand -&consvars; in any arguments strings, +&consvars; in any argument strings, including the action argument, -at the time it is called -using the &consvars; in the -env -&consenv; through which -&f-env-Builder; was called. +at the time it is called, +using the values from +env. The -&f-Builder; +&f-Builder; (global fuction) form delays all variable expansion until after the Builder object is actually called. diff --git a/SCons/Tool/Tool.xml b/SCons/Tool/Tool.xml index 85311db59..b072f2010 100644 --- a/SCons/Tool/Tool.xml +++ b/SCons/Tool/Tool.xml @@ -511,10 +511,10 @@ determine the version of versioned import library. -Contains the emitter specification for the +A callable or list of callables used as the emitter for the &b-link-StaticLibrary; builder. -The manpage section "Builder Objects" contains -general information on specifying emitters. +See the manpage section "Emitter Functions" +for general emitter behavior. @@ -535,10 +535,10 @@ specified in the same format as &cv-link-SHLIBVERSION;. -Contains the emitter specification for the +A callable or list of callables used as the emitter for the &b-link-LoadableModule; builder. -The manpage section "Builder Objects" contains -general information on specifying emitters. +See the manpage section "Emitter Functions" +for general emitter behavior. @@ -546,10 +546,10 @@ general information on specifying emitters. -Contains the emitter specification for the +A callable or list of callables used as the emitter for the &b-link-SharedLibrary; builder. -The manpage section "Builder Objects" contains -general information on specifying emitters. +See the manpage section "Emitter Functions" +for general emitter behavior. @@ -557,10 +557,10 @@ general information on specifying emitters. -Contains the emitter specification for the +A callable or list of callables used as the emitter for the &b-link-Program; builder. -The manpage section "Builder Objects" contains -general information on specifying emitters. +See the manpage section "Emitter Functions" +for general emitter behavior. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 83327162f..33ec5ddaf 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -6004,6 +6004,9 @@ Adding new Tool modules is described in can be extended to build additional types of targets by adding new Builder objects to a &consenv;. +A Builder combines actions, optional emitters, +optional scanners, and naming rules to create +target nodes from source nodes. In general, you should only need to add a new Builder object when you want to build a new type of file or other external target. @@ -6174,7 +6177,7 @@ may be a string or a list of strings. A Scanner object that will be invoked to find -implicit dependencies for this target file. +implicit dependencies for the Builder's target. Use only to specify Scanner objects that find implicit dependencies based on the target file @@ -6182,8 +6185,9 @@ and &consenv;, not for implicit dependencies based on source files (use for those). -See -for information about creating your own Scanner objects. +See Scanner Objects +for information about creating your own Scanner objects. + @@ -6194,7 +6198,7 @@ for information about creating your own Scanner objects. will be invoked to find implicit dependencies in any source files -used to build this target file. +used to build the Builder's target. Use to specify a scanner to find things like #include @@ -6208,7 +6212,7 @@ for on-disk changes to files that &scons; does not know about from other Builder or function calls. -See +See Scanner Objects for information about creating your own Scanner objects. @@ -6217,10 +6221,10 @@ for information about creating your own Scanner objects. target_factory A factory function that the Builder will use -to turn any targets specified as strings into SCons Nodes. +to turn any targets specified as strings into Nodes. By default, -SCons assumes that all targets are files -(that is, the default factory is &File;). +&SCons; assumes that all targets are files +(that is, the default target factory is &File;). Other useful target_factory values include &Dir; for when a Builder creates a directory target, @@ -6255,10 +6259,10 @@ and a circular dependency. source_factory A factory function that the Builder will use -to turn any sources specified as strings into SCons Nodes. +to turn any sources specified as strings into Nodes. By default, -SCons assumes that all source are files -(that is, the default factory is &File;). +&SCons; assumes that all source are files +(that is, the default source factory is &File;). Other useful source_factory values include &Dir; for when a Builder uses a directory as a source, @@ -6284,33 +6288,27 @@ env.Collect('archive', 'directory_name') emitter -A function or list of functions to manipulate the target and source -lists before dependencies are established -and the target(s) are actually built. -emitter -can also be a string containing a &consvar; to expand -to an emitter function or list of functions, -or a dictionary mapping source file suffixes -to emitter functions. -(Only the suffix of the first source file -is used to select the actual emitter function -from an emitter dictionary.) - -A function passed as emitter -must accept three arguments: -source, -target and -env. -source is a list of source nodes, -target is a list of target nodes, -env is the &consenv; to use for context. + +The optional emitter argument +specifies an emitter function, +list of emitter functions, +&consvar; reference, +or suffix-dispatch mapping used to +adjust the target and source lists +before the build nodes are finalized. +If emitter is a list, +the emitters are called in order. +Each emitter receives the target and source lists +returned by the previous emitter. +If emitter is a mapping, +only the suffix of the first source file +will be used to look up the emitter function. +See the +Emitter Functions +section for full details. -An emitter must return a tuple containing two lists, -the list of targets to be built by this builder, -and the list of sources for this builder. - -Example: +Examples: def e(target, source, env): @@ -7770,6 +7768,156 @@ you should be aware of this issue when using the + +Emitter Functions + +An emitter is a Python callable used by a Builder +to adjust the list of target and source nodes +or make other adjustments +after the builder has interpreted the call arguments, +but before &SCons; finalizes +the dependency graph for those nodes. +Emitters are commonly used to add additional targets, +declare side effects, +add dependencies, +or account for files that a tool creates +in addition to its primary output. + + + +An emitter function will have a signature like: + +def emitter(target, source, env): + return target, source + +where +target is a list of target Nodes, +source is a list of source Nodes, +and env is the construction environment. +The implementation requires specifically that naming and order. + + + +The return value must be a two element sequence composed +of updated target and source lists. +The function must return both lists even if unchanged. +This is because Emitters are composable. +If an emitter is specified as a list of emitter functions, +or as a construction variable that resolves into +a list of emitter functions, +the list is iterated, +with each function being applied to the result of the previous one. +Elements added to target or +source +can be either strings or File nodes. +&SCons; will convert strings to File nodes. + + + +The emitter is called while &SCons; is reading SConscript files +and creating build nodes, +not when the external build command is executed. +It should not attempt build-time operations, +and not make assumptions like reading generated files, +which may not exist at SConscript processing time. + + + +Emitters are usually associated with a Builder by providing +them as an argument to the &f-link-Builder; factory: + + +def my_emitter(target, source, env): + target.append(env.File(str(target[0]) + '.size')) + return target, source + +bld = Builder( + action='mytool -o $TARGET $SOURCE', + emitter=my_emitter, +) +env.Append(BUILDERS={'MyTool': bld}) + + +There are multiple options when specifying emitters this way. +See the &f-Builder; +emitter +section for further examples. + + + +For certain common Builders, +it is possible to modify their Emitter list through a &consvar;, +rather than writing an entire new Builder. +For example, the &b-link-SharedLibrary; builder +used by several linker tools exposes its +emitter list through &cv-link-SHLIBEMITTER;, +which can be appended or prepended to +(it is usually best not to completely replace +the existing value). + + +def exports_emitter(target, source, env): + # Record a generated exports file as an additional build source. + return target, source + [env.File('exports.txt')] + +env.Append(SHLIBEMITTER=[exports_emitter]) +env.SharedLibrary('mylib', ['mylib.c']) + + + +Using the &consvar; is the preferred way to extend these builders: + + + + + + + Consvar + Builder + Purpose + + + + + &cv-link-PROGEMITTER; + &b-link-Program; + customize program link target graph + + + &cv-link-LIBEMITTER; + &b-link-Library; + customize static library targets + + + &cv-link-SHLIBEMITTER; + &b-link-SharedLibrary; + customize shared library targets, versioned/symlinked outputs + + + &cv-link-LDMODULEEMITTER; + &b-link-LoadableModule; + customize program loadable module targets + + + + + + +When the &consvar; mechanism is used, +it can be given as an override on a per-call basis, +so the changes apply only to the sources and targets +of that specific builder call. +Remember that an override assignment replaces the value +from the environment, +so use this carefully — existing emitters may be necessary +for your build to function. + +env.Program('app', ['main.c'], PROGEMITTER=[link_emitter]) + + + + + Scanner Objects