Also enable extra_libs for CheckLib

Manpage entries and docstrings updated with version-added specifiers.

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

5 files changed, 70 insertions, 32 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 7903724..fb35ffb 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -12,9 +12,9 @@ NOTE: Python 3.6 support is deprecated and will be dropped in a future release.
 
 RELEASE  VERSION/DATE TO BE FILLED IN LATER
 
-  From Ruben Di Battista: 
-    - Expose `extra_libs` kwarg in the `CheckLibWithHeader` and forward it downstream
-      to `CheckLib`
+  From Ruben Di Battista:
+    - Expose `extra_libs` kwarg in Configure checks `CheckLibWithHeader`
+      and 'CheckLib' and forward it downstream to `CheckLib`
 
   From Joseph Brill:
     - Added error handling when creating MSVC detection debug log file specified by
diff --git a/RELEASE.txt b/RELEASE.txt
index c4f9fe5..38e4a1f 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -25,7 +25,7 @@ DEPRECATED FUNCTIONALITY
 
 CHANGED/ENHANCED EXISTING FUNCTIONALITY
 ---------------------------------------
-- Expose the `extra_libs` keyword argument in `CheckLibWithHeader`
+- Expose the `extra_libs` keyword argument in `CheckLibWithHeader` and 'CheckLib'
 
 - List modifications to existing features, where the previous behavior
   wouldn't actually be considered a bug
diff --git a/SCons/SConf.py b/SCons/SConf.py
index 7d3d484..36bb914 100644
--- a/SCons/SConf.py
+++ b/SCons/SConf.py
@@ -1101,12 +1101,17 @@ def CheckCXXHeader(context, header, include_quotes: str = '""'):
 
 
 def CheckLib(context, library = None, symbol: str = "main",
-             header = None, language = None, autoadd: bool=True,
-             append: bool=True, unique: bool=False) -> bool:
+             header = None, language = None, extra_libs = None,
+             autoadd: bool=True, append: bool=True, unique: bool=False) -> bool:
     """
-    A test for a library. See also CheckLibWithHeader.
+    A test for a library. See also :func:`CheckLibWithHeader`.
     Note that library may also be None to test whether the given symbol
     compiles without flags.
+
+    .. versionchanged:: NEXT_RELEASE
+       Added the *extra_libs* keyword parameter. The actual implementation
+       is in :func:`SCons.Conftest.CheckLib` which already accepted this
+       parameter, so this is only exposing existing functionality.
     """
 
     if not library:
@@ -1116,9 +1121,9 @@ def CheckLib(context, library = None, symbol: str = "main",
         library = [library]
 
     # ToDo: accept path for the library
-    res = SCons.Conftest.CheckLib(context, library, symbol, header = header,
-                                        language = language, autoadd = autoadd,
-                                        append=append, unique=unique)
+    res = SCons.Conftest.CheckLib(context, library, symbol, header=header,
+                                  language=language, extra_libs=extra_libs,
+                                  autoadd=autoadd, append=append, unique=unique)
     context.did_show_result = True
     return not res
 
@@ -1126,15 +1131,21 @@ def CheckLib(context, library = None, symbol: str = "main",
 # Bram: Can only include one header and can't use #ifdef HAVE_HEADER_H.
 
 def CheckLibWithHeader(context, libs, header, language,
-                       extra_libs = None,  call = None, autoadd: bool=True, append: bool=True, unique: bool=False) -> bool:
-    # ToDo: accept path for library. Support system header files.
+                       extra_libs = None,  call = None, autoadd: bool=True,
+                       append: bool=True, unique: bool=False) -> bool:
     """
     Another (more sophisticated) test for a library.
     Checks, if library and header is available for language (may be 'C'
     or 'CXX'). Call maybe be a valid expression _with_ a trailing ';'.
-    As in CheckLib, we support library=None, to test if the call compiles
+    As in :func:`CheckLib`, we support library=None, to test if the call compiles
     without extra link flags.
+
+    .. versionchanged:: NEXT_RELEASE
+       Added the *extra_libs* keyword parameter. The actual implementation
+       is in :func:`SCons.Conftest.CheckLib` which already accepted this
+       parameter, so this is only exposing existing functionality.
     """
+    # ToDo: accept path for library. Support system header files.
     prog_prefix, dummy = createIncludesFromHeaders(header, 0)
     if not libs:
         libs = [None]
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 4119a45..5a05466 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -4163,7 +4163,7 @@ function calls whose arguments are not type compatible with the prototype.
   </varlistentry>
 
   <varlistentry>
-  <term><replaceable>context</replaceable>.<methodname>CheckLib</methodname>(<parameter>[library, symbol, header, language, autoadd=True, append=True, unique=False]</parameter>) </term>
+  <term><replaceable>context</replaceable>.<methodname>CheckLib</methodname>(<parameter>[library, symbol, header, language, extra_libs=None, autoadd=True, append=True, unique=False]</parameter>) </term>
   <listitem>
 <para>Checks if
 <parameter>library</parameter>
@@ -4173,12 +4173,19 @@ 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.
+</para>
+<para>
+The remaining arguments should be specified in keyword style.
+If <parameter>extra_libs</parameter> is specified,
+it is a list off additional libraries to include when
+linking the stub program (usually, dependencies of
+the library being checked).
 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),
+<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),
+If <parameter>append</parameter> is true (the default),
 the library is appended, otherwise it is prepended.
 If <parameter>unique</parameter> is true,
 and the library would otherwise be added but is
@@ -4213,23 +4220,29 @@ at least one should be supplied.
 <parameter>append</parameter> and <parameter>unique</parameter>
 parameters.</emphasis>
 </para>
+<para>
+<emphasis>Changed in version NEXT_RELEASE: added the
+<parameter>extra_libs</parameter> parameter.</emphasis>
+</para>
   </listitem>
   </varlistentry>
 
   <varlistentry>
-  <term><replaceable>context</replaceable>.<methodname>CheckLibWithHeader</methodname>(<parameter>library, header, [language, call, autoadd=True, append=True, unique=False]</parameter>)</term>
+  <term><replaceable>context</replaceable>.<methodname>CheckLibWithHeader</methodname>(<parameter>[library, header, language, extra_libs=None, call=None, autoadd=True, append=True, unique=False]</parameter>)</term>
   <listitem>
 
 <para>Provides an alternative to the
 <methodname>CheckLib</methodname> method
-for checking for libraries usable in a build.
+for checking whether libraries are usable in a build.
+The first three arguments can be given as
+positional or keyword style arguments.
 <parameter>library</parameter>
-specifies a library or list of libraries to check.
+specifies a library or list of libraries to check
+(the default is <literal>None</literal>),
 <parameter>header</parameter>
-specifies a header to include in the test program,
-and <parameter>language</parameter> indicates the compiler to use.
+specifies header text to include in the test program.
 <parameter>header</parameter>
-may be a list,
+may also be a list,
 in which case the last item in the list
 is the header file to be checked,
 and the previous list items are
@@ -4237,14 +4250,22 @@ header files whose
 <literal>#include</literal>
 lines should precede the
 header line being checked for.
-A code fragment
-(must be a valid expression, including a trailing semicolon)
-to serve as the test can be supplied in
-<parameter>call</parameter>;
-if not supplied,
+The default is to include no header text.
+<parameter>language</parameter> indicates the compiler to use
+(default "C").
+</para>
+
+<para>
+The remaining parameters should be specified in keyword style.
+If provided, <parameter>call</parameter>
+is a code fragment to compile as the stub test,
+replacing the auto-generated stub.
+The fragment must be a valid expression in <parameter>language</parameter>.
+If not supplied,
 the default checks the ability to link against the specified
 <parameter>library</parameter>.
-<parameter>extra_libs</parameter> can be used to add additional libraries to link against.
+<parameter>extra_libs</parameter> can be used to add additional libraries
+to link against (usually, dependencies of the library under test).
 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
@@ -4256,12 +4277,18 @@ and the library would otherwise be added but is
 already present in &cv-link-LIBS; in the configure context,
 it will not be added again. The default is <literal>False</literal>.
 </para>
+
 <para>Returns a boolean indicating success or failure.</para>
+
 <para>
 <emphasis>Changed in version 4.5.0: added the
 <parameter>append</parameter> and <parameter>unique</parameter>
 parameters.</emphasis>
 </para>
+<para>
+<emphasis>Changed in version NEXT_RELEASE: added the
+<parameter>extra_libs</parameter> parameter.</emphasis>
+</para>
   </listitem>
   </varlistentry>
 
diff --git a/test/Configure/CheckLibWithHeader_extra_libs.py b/test/Configure/CheckLibWithHeader_extra_libs.py
index 9d5f300..0be8999 100644
--- a/test/Configure/CheckLibWithHeader_extra_libs.py
+++ b/test/Configure/CheckLibWithHeader_extra_libs.py
@@ -62,9 +62,9 @@ test.write(
     str(libB_dir / "SConstruct"),
     """\
 SharedLibrary(
-    'libB', 
-    source=['libB.c'], 
-    LIBS=['A'], 
+    'libB',
+    source=['libB.c'],
+    LIBS=['A'],
     LIBPATH='../libA',
     CPPPATH='../libA',
 )