Merge pull request #4898 from mwichmann/doc/sideeffect

Manpage improvement: SideEffect

Author: bdbaddog

CHANGES.txt

@@ -16,6 +16,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - ty: Initial support setup within `pyproject.toml`.
     - Removed Python 3.7 & 3.8 support.
 
+  From Mats Wichmann:
+    - Reference manual improvements:
+      * Additional clarification for SideEffect()
+
 
 RELEASE 4.11.1 - Mon, 26 Aug 2026 21:16:00 -0700
 

RELEASE.txt

@@ -60,6 +60,8 @@ DOCUMENTATION
   typo fixes, even if they're mentioned in src/CHANGES.txt to give
   the contributor credit)
 
+* Additional clarification for SideEffect() in manpage.
+
 DEVELOPMENT
 -----------
 

SCons/Environment.xml

@@ -3274,63 +3274,65 @@ if 'FOO' not in env:
 <para>
 Declares
 <parameter>side_effect</parameter>
-as a side effect of building
+as a file that may be created or updated while building
+<parameter>target</parameter>,
+but is not the primary output of the builder that builds
 <parameter>target</parameter>.
 Both
 <parameter>side_effect</parameter>
 and
 <parameter>target</parameter>
-can be a list, a file name, or a node.
-A side effect is a target file that is created or updated
-as a side effect of building other targets.
-For example, a Windows PDB
-file is created as a side effect of building the .obj
-files for a static library,
-and various log files are created updated
-as side effects of various TeX commands.
-If a target is a side effect of multiple build commands,
-&scons;
-will ensure that only one set of commands
-is executed at a time.
-Consequently, you only need to use this method
-for side-effect targets that are built as a result of
-multiple build commands.
+may be a filename, a Node object, or a list of filenames or Nodes.
 </para>
 
 <para>
-Because multiple build commands may update
-the same side effect file,
-by default the
+Use &f-SideEffect; for shared auxiliary output files,
+especially when the same file may be written by more than one
+otherwise-independent build command.
+Declaring the file as a side effect tells &SCons; that commands which
+write the same
 <parameter>side_effect</parameter>
-target is
-<emphasis>not</emphasis>
-automatically removed
-when the
+must not run at the same time.
+This is primarily important for parallel builds.
+</para>
+
+<para>
+Typical examples include compiler-generated database files,
+such as Windows PDB files, and log or auxiliary files generated by
+document-processing tools.
+For example, several object-file compilations may update the same PDB file.
+Declaring the PDB file as a side effect of those object-file targets
+prevents &SCons; from running those compilations concurrently when doing so
+could corrupt the PDB file.
+</para>
+
+<para>
+Do not use &f-SideEffect; for an ordinary additional output that should be
+treated as a normal build target.
+If a command deliberately produces multiple primary output files,
+list those files as targets of the builder or &Command; call instead.
+Use &f-SideEffect; only for auxiliary files whose contents are a consequence
+of building other targets and whose exact update relationship is not suitable
+as a normal target dependency.
+</para>
+
+<para>
+A side-effect file is not automatically removed when
 <parameter>target</parameter>
-is removed by the
-<option>-c</option>
+is cleaned with the
+<link linkend="opt-clean"><option>-c</option></link>
 option.
-(Note, however, that the
-<parameter>side_effect</parameter>
-might be removed as part of
-cleaning the directory in which it lives.)
-If you want to make sure the
-<parameter>side_effect</parameter>
-is cleaned whenever a specific
-<parameter>target</parameter>
-is cleaned,
-you must specify this explicitly
-with the
-&f-link-Clean;
-or
-&f-env-Clean;
-function.
+This is because the same side-effect file may be shared by several targets.
+If the side-effect file should be removed when cleaning a particular target,
+declare that explicitly with
+&f-link-Clean;.
 </para>
 
 <para>
-This function returns the list of side effect Node objects that were successfully added.
-If the list of side effects contained any side effects that had already been added,
-they are not added and included in the returned list.
+Returns the list of side-effect Node objects that were
+successfully added by this call.
+If any specified side effect had already been declared,
+it is not added again and is not included in the returned list.
 </para>
 </summary>
 </scons_function>