Modify the Builder Methods manpage section [skip appveyor]

In clarifying the detail on when a builder's target can be deduced,
it seemed like the concept of a single-source builder ought to be
introduced in this context. So now those builders we know are
single-source have that notation in their entry in this section.

Also mentions that pseudo-Builders may have a diffeent calling sequence.

A chunk of text about dependencies previously appeared after the
listing of builder methods, where it would be hard to spot. Moved up
into the text before the listing, and integrate in a bit more smoothly.

A couple of very minor typing things adjusted along the way - mainly
using single_source consistently as a bool.

Signed-off-by: Mats Wichmann <[email protected]>

Author: mwichmann

CHANGES.txt

@@ -27,6 +27,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - runtest.py once again finds "external" tests, such as the tests for
       tools in scons-contrib. An earlier rework had broken this.  Fixes #4699.
     - Clarify how pre/post actions on an alias work.
+    - Improve the Builder Methods intro section in manpage, making sure
+      all prose appears before the listing of methods.
 
 
 RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700
@@ -42,7 +44,6 @@ RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700
   From Mats Wichmann:
     - Fix typos in CCFLAGS test. Didn't affect the test itself, but
       didn't correctly apply the DefaultEnvironment speedup.
-
     - New CacheDir initialization code failed on Python 3.7 for unknown
       reason (worked on 3.8+). Adjusted the approach a bit.  Fixes #4694.
     - Try to fix Windows fails on Docbook tests in case xsltproc is found.

RELEASE.txt

@@ -61,12 +61,16 @@ DOCUMENTATION
 DEVELOPMENT
 -----------
 
+- List visible changes in the way SCons is developed
+
 - runtest.py once again finds "external" tests, such as the tests for
   tools in scons-contrib. An earlier rework had broken this.  Fixes #4699.
 
+- Improve the descriptive portion of the Builder Methods section in
+  the manpage: reword, reorganize.
+
 Thanks to the following contributors listed below for their contributions to this release.
 ==========================================================================================
 .. code-block:: text
 
-
     git shortlog --no-merges -ns 4.9.1..HEAD

SCons/BuilderTests.py

@@ -714,8 +714,8 @@ def func(target, source, env) -> None:
             infiles.append(test.workpath('%d.in' % i))
             outfiles.append(test.workpath('%d.out' % i))
             test.write(infiles[-1], "\n")
-        builder = SCons.Builder.Builder(action=SCons.Action.Action(func,None),
-                                        single_source = 1, suffix='.out')
+        builder = SCons.Builder.Builder(action=SCons.Action.Action(func, None),
+                                        single_source=True, suffix='.out')
         env['CNT'] = [0]
         tgt = builder(env, target=outfiles[0], source=infiles[0])[0]
         s = str(tgt)

SCons/Node/__init__.py

@@ -215,7 +215,7 @@ def get_contents_dir(node):
         contents.append('%s %s\n' % (n.get_csig(), n.name))
     return ''.join(contents)
 
-def get_contents_file(node):
+def get_contents_file(node) -> bytes:
     if not node.rexists():
         return b''
     fname = node.rfile().get_abspath()

SCons/Tool/Tool.xml

@@ -36,13 +36,13 @@ if it is not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds foo.c
 env.CFile(target='foo.c', source='foo.l')
 
 # builds bar.c
 env.CFile(target='bar', source='bar.y')
-</example_commands>
+</programlisting>
 
 <!--para>  ** Left here for reference, does not need to be user-visible. **
 Note that for yacc files,
@@ -67,13 +67,13 @@ if it is not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 # builds foo.cc
 env.CXXFile(target='foo.cc', source='foo.ll')
 
 # builds bar.cc
 env.CXXFile(target='bar', source='bar.yy')
-</example_commands>
+</programlisting>
 
 <!--para>  ** Left here for reference, does not need to be user-visible. **
 Note that for yacc files,
@@ -141,9 +141,9 @@ are automatically added to the target if not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
-</example_commands>
+</programlisting>
 </summary>
 </builder>
 
@@ -187,9 +187,9 @@ it is appended (following a period) to the resulting library name.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
-</example_commands>
+</programlisting>
 
 <para>
 On Windows systems, the
@@ -228,9 +228,9 @@ adds the version number to the library name, and creates any
 symbolic links that are needed.
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
-</example_commands>
+</programlisting>
 
 <para>
 On a POSIX system, supplying a simple version string (no dots)
@@ -264,9 +264,9 @@ up and requiring user attention when it is run.  If you change
 For example,
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
-</example_commands>
+</programlisting>
 
 <para>
 will register <filename>bar.dll</filename> as a COM object
@@ -281,38 +281,41 @@ when it is done linking it.
 Builds an object file intended for
 inclusion in a shared library.
 Source files must have one of the same set of extensions
-specified above for the
-&b-StaticObject;
+specified for the
+&b-link-StaticObject;
 builder method.
-On some platforms building a shared object requires additional
-compiler option
-(e.g. <option>-fPIC</option> for <command>gcc</command>)
-in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
 The target object file prefix,
 specified by the &cv-link-SHOBJPREFIX; &consvar;
 (by default, the same as &cv-link-OBJPREFIX;),
 and suffix,
 specified by the &cv-link-SHOBJSUFFIX; &consvar;,
 are automatically added to the target if not already present.
+&b-SharedObject; is a single-source builder.
 Examples:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.SharedObject(target='ddd', source='ddd.c')
 env.SharedObject(target='eee.o', source='eee.cpp')
 env.SharedObject(target='fff.obj', source='fff.for')
-</example_commands>
+env.SharedObject(source=Glob('*.c'))
+</programlisting>
 
 <para>
-Note that the source files will be scanned
+On some platforms building a shared object requires additional
+compiler option(s)
+(e.g. <option>-fPIC</option> for <command>gcc</command>)
+in addition to those needed to build a
+normal (static) object.
+If shared and static objects differ,
+&SCons; will allow only shared objects
+to be linked into a shared library,
+and will use a different suffix for shared objects
+to help indicate and track the difference.
+</para>
+
+<para>
+Source files will be scanned
 according to the suffix mappings in the
 <classname>SourceFileScanner</classname>
 object.
@@ -342,9 +345,9 @@ are automatically added to the target if not already present.
 Example:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
-</example_commands>
+</programlisting>
 
 <para>
 Any object files listed in the
@@ -364,10 +367,10 @@ will raise an error if there is any mismatch.
 <para>
 Builds a static object file
 from one or more C, C++, D, or Fortran source files.
-Source files must have one of the following extensions:
+The file extension mapping is shown in the table:
 </para>
 
-<example_commands>
+<literallayout><literal>
   .asm    assembly language file
   .ASM    assembly language file
   .c      C file
@@ -396,28 +399,30 @@ Source files must have one of the following extensions:
           POSIX:  assembly language file + C pre-processor
   .spp    assembly language file + C pre-processor
   .SPP    assembly language file + C pre-processor
-</example_commands>
+</literal></literallayout>
 
 <para>
 The target object file prefix,
 specified by the &cv-link-OBJPREFIX; &consvar;
-(nothing by default),
+(empty string by default),
 and suffix,
 specified by the &cv-link-OBJSUFFIX; &consvar;
 (<filename>.obj</filename> on Windows systems,
 <filename>.o</filename> on POSIX systems),
 are automatically added to the target if not already present.
+&b-StaticObject; is a single-source builder.
 Examples:
 </para>
 
-<example_commands>
+<programlisting language="python">
 env.StaticObject(target='aaa', source='aaa.c')
 env.StaticObject(target='bbb.o', source='bbb.c++')
 env.StaticObject(target='ccc.obj', source='ccc.f')
-</example_commands>
+env.StaticObject(source=Glob('*.c'))
+</programlisting>
 
 <para>
-Note that the source files will be scanned
+Source files will be scanned
 according to the suffix mappings in the
 <classname>SourceFileScanner</classname>
 object.

SCons/Tool/__init__.py

@@ -408,7 +408,7 @@ def createObjBuilders(env):
                                            suffix='$OBJSUFFIX',
                                            src_builder=['CFile', 'CXXFile'],
                                            source_scanner=SourceFileScanner,
-                                           single_source=1)
+                                           single_source=True)
         env['BUILDERS']['StaticObject'] = static_obj
         env['BUILDERS']['Object'] = static_obj
 
@@ -421,7 +421,7 @@ def createObjBuilders(env):
                                            suffix='$SHOBJSUFFIX',
                                            src_builder=['CFile', 'CXXFile'],
                                            source_scanner=SourceFileScanner,
-                                           single_source=1)
+                                           single_source=True)
         env['BUILDERS']['SharedObject'] = shared_obj
 
     return (static_obj, shared_obj)