Add "append" kwarg to two configure checks

Add append=True/False to CheckLib, CheckLibWithHeader in SConf.  The
"implementation", Conftest.CheckLib, already accepted this kwarg,
but it could not be passed from an SConscript using the offical API.
Updated manpage to describe and expanded a unit test to check.

Fixes #2767

Additionally, clarified some things in manpage, including a recent user
confusion about how to call CheckFunc.

Signed-off-by: Mats Wichmann <mats@linux.com>

5 files changed, 128 insertions, 88 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 2475bddb8..93be68dfd 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -122,6 +122,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       3.12 is in alpha for this SCons release, the bytecode sequences 
       embedded in SCons/ActionTests.py may need to change later, but
       based on what is known now, 3.12 itself should work with this release.
+    - Add "append" keyword argument to Configure context's CheckLib and
+      CheckLibWithHeader to control whether to append or prepend (issue #2767)
 
 
 RELEASE 4.4.0 -  Sat, 30 Jul 2022 14:08:29 -0700
diff --git a/RELEASE.txt b/RELEASE.txt
index f74a2b099..01bf63b12 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -45,6 +45,10 @@ CHANGED/ENHANCED EXISTING FUNCTIONALITY
   to NewParallel Job class (Andrew Morrow's new parallel job implementation)
 - Preliminary support for Python 3.12.
 - Run LaTeX after biber/bibtex only if necessary
+- Configure context methods CheckLib and CheckLibWithHeader now expose
+  an additional keyword argument 'append' which controls whether to append
+  (the default) or prepend discovered libraries to $LIBS.  The functionality
+  was always present but prepending could not be requested via the offical API.
 
 
 FIXES
diff --git a/SCons/SConf.py b/SCons/SConf.py
index fe14a0ccc..051c14ce6 100644
--- a/SCons/SConf.py
+++ b/SCons/SConf.py
@@ -1067,7 +1067,7 @@ def CheckCXXHeader(context, header, include_quotes = '""'):
 
 
 def CheckLib(context, library = None, symbol = "main",
-             header = None, language = None, autoadd = 1):
+             header = None, language = None, autoadd=True, append=True,) -> bool:
     """
     A test for a library. See also CheckLibWithHeader.
     Note that library may also be None to test whether the given symbol
@@ -1082,15 +1082,16 @@ def CheckLib(context, library = None, symbol = "main",
 
     # ToDo: accept path for the library
     res = SCons.Conftest.CheckLib(context, library, symbol, header = header,
-                                        language = language, autoadd = autoadd)
-    context.did_show_result = 1
+                                        language = language, autoadd = autoadd,
+                                        append=append)
+    context.did_show_result = True
     return not res
 
 # XXX
 # Bram: Can only include one header and can't use #ifdef HAVE_HEADER_H.
 
 def CheckLibWithHeader(context, libs, header, language,
-                       call = None, autoadd = 1):
+                       call = None, autoadd=True, append=True) -> bool:
     # ToDo: accept path for library. Support system header files.
     """
     Another (more sophisticated) test for a library.
@@ -1099,8 +1100,7 @@ def CheckLibWithHeader(context, libs, header, language,
     As in CheckLib, we support library=None, to test if the call compiles
     without extra link flags.
     """
-    prog_prefix, dummy = \
-                 createIncludesFromHeaders(header, 0)
+    prog_prefix, dummy = createIncludesFromHeaders(header, 0)
     if not libs:
         libs = [None]
 
@@ -1108,7 +1108,7 @@ def CheckLibWithHeader(context, libs, header, language,
         libs = [libs]
 
     res = SCons.Conftest.CheckLib(context, libs, None, prog_prefix,
-            call = call, language = language, autoadd = autoadd)
+            call = call, language = language, autoadd=autoadd, append=append)
     context.did_show_result = 1
     return not res
 
diff --git a/SCons/SConfTests.py b/SCons/SConfTests.py
index a06b22755..172fba75c 100644
--- a/SCons/SConfTests.py
+++ b/SCons/SConfTests.py
@@ -572,14 +572,27 @@ int main(void) {
             env = sconf.env.Clone()
 
             try:
-                r = sconf.CheckLibWithHeader( existing_lib, "math.h", "C", autoadd=1 )
+                r = sconf.CheckLibWithHeader(
+                    existing_lib, "math.h", "C", autoadd=True, append=True
+                )
                 assert r, "did not find math.h with %s" % existing_lib
                 expect = libs(env) + [existing_lib]
                 got = libs(sconf.env)
                 assert got == expect, "LIBS: expected %s, got %s" % (expect, got)
 
                 sconf.env = env.Clone()
-                r = sconf.CheckLibWithHeader( existing_lib, "math.h", "C", autoadd=0 )
+                r = sconf.CheckLibWithHeader(
+                    existing_lib, "math.h", "C", autoadd=True, append=False
+                )
+                assert r, "did not find math.h with %s" % existing_lib
+                expect = [existing_lib] + libs(env)
+                got = libs(sconf.env)
+                assert got == expect, "LIBS: expected %s, got %s" % (expect, got)
+
+                sconf.env = env.Clone()
+                r = sconf.CheckLibWithHeader(
+                    existing_lib, "math.h", "C", autoadd=False
+                )
                 assert r, "did not find math.h with %s" % existing_lib
                 expect = libs(env)
                 got = libs(sconf.env)
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 824cd41c2..15270e2d9 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -174,14 +174,14 @@ looks for a file named
 in the current directory and reads the
 build configuration from that file
 (other names are allowed,
-see <xref linkend="sconscript_files"/> 
+see <xref linkend="sconscript_files"/>
 and the <link linkend="opt-f"><option>-f</option></link> option
 for more information).
 The build may be structured in a hierarchical manner:
 the &SConstruct;
 file may specify subsidiary
 configuration files by calling the
-&f-link-SConscript; function, 
+&f-link-SConscript; function,
 and these may, in turn, do the same.
 By convention,
 these subsidiary files are named
@@ -3665,7 +3665,7 @@ does not maintain an explicit cache of the tested values
 (this is different than &Autoconf;),
 but uses its normal dependency tracking to keep the checked values
 up to date. However, users may override this behaviour with the
-<option>--config</option>
+<link linkend="opt-config"><option>--config</option></link>
 command line option.</para>
 
 <variablelist>
@@ -3795,13 +3795,16 @@ env = conf.Finish()
 <para>A &configure_context;
 has the following predefined methods which
 can be used to perform checks. Where
-<parameter>language</parameter> is a required or
-optional parameter, the choice can currently
-be C or C++. The spellings accepted for
+<parameter>language</parameter> is an optional parameter,
+it specifies the compiler to use for the check,
+currently a choice of C or C++.
+The spellings accepted for
 C are <quote>C</quote> or <quote>c</quote>;
 for C++ the value can be
 <quote>CXX</quote>, <quote>cxx</quote>, <quote>C++</quote>
 or <quote>c++</quote>.
+If <parameter>language</parameter> is omitted,
+<quote>C</quote> is assumed.
 </para>
 
 <variablelist>
@@ -3810,7 +3813,7 @@ or <quote>c++</quote>.
   <listitem>
 <para>Checks if
 <parameter>header</parameter>
-is usable in the specified language.
+is usable in the specified <parameter>language</parameter>.
 <parameter>header</parameter>
 may be a list,
 in which case the last item in the list
@@ -3826,14 +3829,8 @@ must be
 a two character string, where the first character denotes the opening
 quote and the second character denotes the closing quote.
 By default, both characters  are <markup>"</markup> (double quote).
-The optional argument
-<parameter>language</parameter>
-should be either
-<emphasis role="bold">C</emphasis>
-or
-<emphasis role="bold">C++</emphasis>
-and selects the compiler to be used for the check.
-Returns a boolean indicating success or failure.</para>
+</para>
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
@@ -3894,25 +3891,23 @@ Returns a boolean indicating success or failure.</para>
   <varlistentry>
   <term><replaceable>context</replaceable>.<methodname>CheckFunc</methodname>(<parameter>function_name, [header, language]</parameter>)</term>
   <listitem>
-<para>Checks if the specified
-C or C++ library function is available based on the
-context's local environment settings (that is, using
-the values of &cv-link-CFLAGS;, &cv-link-CPPFLAGS;, &cv-link-LIBS;
-or other relevant &consvars;).
+<para>Checks if <parameter>function_name</parameter> is usable
+in the context's local environment using the compiler
+specified by <parameter>language</parameter> - that is,
+can a check referencing it be compiled using the current values
+of &cv-link-CFLAGS;, &cv-link-CPPFLAGS;,
+&cv-link-LIBS; or other relevant &consvars;.
 </para>
 
 <para>
-<parameter>function_name</parameter>
-is the name of the function to check for.
 The optional
 <parameter>header</parameter>
-argument is a string
-that will be
-placed at the top
-of the test file
-that will be compiled
-to check if the function exists;
-the default is:</para>
+argument is a string representing a code fragment
+to place at the top of the test program
+that will be compiled to check if the function exists.
+If omitted, the default stanza will be
+(with <parameter>function_name</parameter> appropriately substituted):
+</para>
 
 <programlisting language="C">
 #ifdef __cplusplus
@@ -3922,61 +3917,79 @@ char function_name();
 </programlisting>
 
 <para>
-Returns an empty string on success, a string containing
-an error message on failure.
+Note: do not use <parameter>header</parameter>
+to include the standard header file that declares
+<parameter>function_name</parameter> - successful
+compilation of the test program depends on using
+a dummy prototype for it,
+to avoid probems with compilers which object to
+function signature mismatches.
 </para>
+
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
   <varlistentry>
-  <term><replaceable>context</replaceable>.<methodname>CheckLib</methodname>(<parameter>[library, symbol, header, language, autoadd=True]</parameter>) </term>
+  <term><replaceable>context</replaceable>.<methodname>CheckLib</methodname>(<parameter>[library, symbol, header, language, autoadd=True, append=True]</parameter>) </term>
   <listitem>
 <para>Checks if
 <parameter>library</parameter>
 provides
-<parameter>symbol</parameter>.
-If
-<parameter>autoadd</parameter>
-is true (the default) and the library provides the specified
-<parameter>symbol</parameter>,
-appends the library to the <varname>LIBS</varname> &consvar;
-<parameter>library</parameter>
-may also be <constant>None</constant> (the default),
-in which case
-<parameter>symbol</parameter>
-is checked with the current <varname>LIBS</varname> variable,
-or a list of library names,
-in which case each library in the list
-will be checked for
-<parameter>symbol</parameter>.
-If
-<parameter>symbol</parameter>
-is not set or is
-<constant>None</constant>,
-then
-<function>CheckLib</function>
+<parameter>symbol</parameter> by compiling a simple stub program
+with the compiler selected by <parameter>language</parameter>,
+and optionally adds that library to the context.
+If supplied, the text of <parameter>header</parameter> is included at the
+top of the stub.
+If <parameter>autoadd</parameter> is true (the default),
+and the library provides the specified
+<parameter>symbol</parameter> (as defined by successfully
+linking the stub program),
+it is added to the &cv-link-LIBS; &consvar; in the context.
+if <parameter>append</parameter> is true (the default),
+the library is appended, otherwise it is prepended.
+</para>
+<para>
+<parameter>library</parameter> can be a list of library names,
+or <constant>None</constant> (the default if the argument is omitted).
+If the former, <parameter>symbol</parameter> is checked against
+each library name in order, returning on the first
+successful test; if the latter,
+it is checked with the current value of &cv-LIBS;
+(in this case no library name would be added).
+If <parameter>symbol</parameter>
+is omitted or <constant>None</constant>,
+then <function>CheckLib</function>
 just checks if
 you can link against the specified
-<parameter>library</parameter>.
+<parameter>library</parameter>,
 Note though it is legal syntax, it would
 not be very useful to call this method
 with <parameter>library</parameter>
 and <parameter>symbol</parameter> both
-omitted or <constant>None</constant>.
-Returns a boolean indicating success or failure.</para>
+omitted or <constant>None</constant> -
+at least one should be supplied.
+</para>
+<para>Returns a boolean indicating success or failure.</para>
+<para>
+<emphasis>Changed in version 4.5.0: added the
+<parameter>append</parameter> parameter.</emphasis>
+</para>
   </listitem>
   </varlistentry>
 
   <varlistentry>
-  <term><replaceable>context</replaceable>.<methodname>CheckLibWithHeader</methodname>(<parameter>library, header, language, [call, autoadd=True]</parameter>)</term>
+  <term><replaceable>context</replaceable>.<methodname>CheckLibWithHeader</methodname>(<parameter>library, header, [language, call, autoadd=True, append=True]</parameter>)</term>
   <listitem>
 
-<para>Provides a more sophisticated way to check against libraries then the
-<function>CheckLib</function> call.
+<para>Provides an alternative to the
+<methodname>CheckLib</methodname> method
+for checking for libraries usable in a build.
 <parameter>library</parameter>
-specifies the library or a list of libraries to check.
+specifies a library or list of libraries to check.
 <parameter>header</parameter>
-specifies a header to check for.
+specifies a header to include in the test program,
+and <parameter>language</parameter> indicates the compiler to use.
 <parameter>header</parameter>
 may be a list,
 in which case the last item in the list
@@ -3986,18 +3999,25 @@ header files whose
 <literal>#include</literal>
 lines should precede the
 header line being checked for.
-<parameter>call</parameter>
-can be any valid expression (with a trailing ';').
-If
-<parameter>call</parameter>
-is not set,
-the default simply checks that you
-can link against the specified
+A code fragment
+(must be a a valid expression, including a trailing semicolon)
+to serve as the test can be supplied in
+<parameter>call</parameter>;
+if not supplied,
+the default checks the ability to link against the specified
 <parameter>library</parameter>.
-<parameter>autoadd</parameter> (default true)
-specifies whether to add the library to the environment if the check
-succeeds.
-Returns a boolean indicating success or failure.</para>
+If <parameter>autoadd</parameter> is true (the default),
+the first library that passes the check
+is added to the &cv-link-LIBS; &consvar; in the context
+and the method returns.
+If <parameter>append</parameter> is true (the default),
+the library is appended, otherwise prepended.
+</para>
+<para>Returns a boolean indicating success or failure.</para>
+<para>
+<emphasis>Changed in version 4.5.0: added the
+<parameter>append</parameter> parameter.</emphasis>
+</para>
   </listitem>
   </varlistentry>
 
@@ -4019,11 +4039,7 @@ Example:</para>
 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
 </programlisting>
 
-<para>
-Returns an empty string on success, a string containing
-an error message on failure.
-</para>
-
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
@@ -4050,7 +4066,7 @@ is supplied, it should be an integer size;
 <parameter>type_name</parameter> is actually
 that size.
 Returns the size in bytes, or zero if the type was not found
-(or if the size did not match <parameter>expect</parameter>).</para>
+(or if the size did not match optional <parameter>expect</parameter>).</para>
 
 <para>
 For example,</para>
@@ -4081,6 +4097,7 @@ for C source files, so by setting relevant &consvars;
 it can be used to detect if particular compiler flags will
 be accepted or rejected by the compiler.
 </para>
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
@@ -4101,6 +4118,7 @@ for C++ source files, so by setting relevant &consvars;
 it can be used to detect if particular compiler flags will
 be accepted or rejected by the compiler.
 </para>
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
@@ -4123,6 +4141,7 @@ be accepted or rejected by the compiler.
 Note this does not check whether a shared library/dll can
 be created.
 </para>
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
@@ -4145,6 +4164,7 @@ be accepted or rejected by the compiler.
 Note this does not check whether a shared library/dll can
 be created.
 </para>
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>
 
@@ -4171,7 +4191,8 @@ is a string containing one or more
 <literal>#include</literal>
 lines that will be inserted into the program
 that will be run to test for the existence of the symbol.
-Returns a boolean indicating success or failure.</para>
+</para>
+<para>Returns a boolean indicating success or failure.</para>
   </listitem>
   </varlistentry>