From 65a1581014a78a8714afa6c57079f1f8faffa146 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 22 Apr 2026 09:39:14 -0600 Subject: [PATCH 1/2] Minor doc fixes for linking Some of the linker-related entities needed some rewording; others needed a cleanup where emphasized references were turned into live links to entities elsewhere. Most of the remaining references to command-line options were turned into live links (the addition of anchors for those is relatively recent, they didn't originally use live-linking). Signed-off-by: Mats Wichmann --- CHANGES.txt | 2 + RELEASE.txt | 3 ++ SCons/Environment.xml | 2 +- SCons/Script/Main.xml | 20 ++++----- SCons/Script/SConscript.xml | 2 +- SCons/Tool/Tool.xml | 15 ++++--- SCons/Tool/install.xml | 3 +- SCons/Tool/lex.xml | 4 +- SCons/Tool/link.xml | 65 ++++++++++++++++++------------ SCons/Tool/packaging/packaging.xml | 9 +++-- 10 files changed, 78 insertions(+), 47 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index f8825923c9..c855911be2 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -83,6 +83,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER and tweak wording a bit. - zip tool now uses zipfile module's "from_file" method to populate ZipInfo records, rather than doing manually. + - Update documentation for linking-related construction variables. + Add a few more live links. RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index 6460b882e5..53b5e11705 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -121,6 +121,9 @@ DOCUMENTATION - Clarify VariantDir behavior when switching to not duplicate sources and tweak wording a bit. +- Update documentation for linking-related construction variables. + Add a few more live links. + DEVELOPMENT ----------- diff --git a/SCons/Environment.xml b/SCons/Environment.xml index fb70671fe3..1cf91ae5f0 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -2783,7 +2783,7 @@ and added to the following &consvars;: Any other strings not associated with options are assumed to be the names of libraries and added to the -&cv-LIBS; &consvar;. +&cv-link-LIBS; &consvar;. diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index 747b81c603..21f121d408 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -82,7 +82,7 @@ as long as they can be unambiguously resolved. For example, if add_option is called to define a option, -it will recognize , +it will also recognize , and so forth as long as there is no other option which could also match to the same abbreviation. @@ -200,9 +200,11 @@ Future versions of &SCons; will likely forbid such usage. -Allows setting options for SCons debug options. Currently, the only supported value is - json which sets the path to the JSON file created when - --debug=json is set. +Allows setting values for SCons debug options. +Currently, the only supported value is +json which sets the path to the JSON file created when the + +argument is given. DebugOptions(json='#/build/output/scons_stats.json') @@ -436,7 +438,7 @@ processed prior to the &f-GetOption; call in the &SConscript; files. config - + debug @@ -1171,13 +1173,13 @@ SetOption('max_drift', 0) -$ scons --compilers=mingw # the correct flag is --compiler +$ scons --complier=mingw # the correct flag is --compiler - Here &SCons; could go off and run a bunch of configure steps with - the default value of --compiler, since the - incorrect command line did not actually supply a value to it, + Here &SCons; could go off and run a bunch of configure steps using + the default value of , since the + misspelled option causes it not to be supplied the intended value, costing developer time to track down why the configure logic made the "wrong" choices. This example shows catching this: diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml index 7ae0159dee..a4ff9f96cb 100644 --- a/SCons/Script/SConscript.xml +++ b/SCons/Script/SConscript.xml @@ -278,7 +278,7 @@ file is found. Adds text to the help message shown when &scons; is called with the - or + or argument. diff --git a/SCons/Tool/Tool.xml b/SCons/Tool/Tool.xml index 592357d8e3..85311db59e 100644 --- a/SCons/Tool/Tool.xml +++ b/SCons/Tool/Tool.xml @@ -523,11 +523,11 @@ general information on specifying emitters. When this &consvar; is defined, a versioned loadable module -is created by &b-link-LoadableModule; builder. This activates the +is created by the &b-link-LoadableModule; builder. This activates the &cv-link-_LDMODULEVERSIONFLAGS; and thus modifies the &cv-link-LDMODULECOM; as required, adds the version number to the library name, and creates the symlinks -that are needed. &cv-link-LDMODULEVERSION; versions should exist in the same -format as &cv-link-SHLIBVERSION;. +that are needed. &cv-link-LDMODULEVERSION; versions should be +specified in the same format as &cv-link-SHLIBVERSION;. @@ -572,9 +572,12 @@ When this &consvar; is defined, a versioned shared library is created by the &b-link-SharedLibrary; builder. This activates the &cv-link-_SHLIBVERSIONFLAGS; and thus modifies the &cv-link-SHLINKCOM; as required, adds the version number to the library name, and creates the symlinks -that are needed. &cv-link-SHLIBVERSION; versions should exist as alphanumeric, -decimal-delimited values as defined by the regular expression "\w+[\.\w+]*". -Example &cv-link-SHLIBVERSION; values include '1', '1.2.3', and '1.2.gitaa412c8b'. +that are needed. &cv-link-SHLIBVERSION; versions are specified +as alphanumeric, decimal-delimited values which can be +recognized by the regular expression +"\w+[\.\w+]*" +Example valid &cv-SHLIBVERSION; values include +'1', '1.2.3', and '1.2.gitaa412c8b'. diff --git a/SCons/Tool/install.xml b/SCons/Tool/install.xml index 3cbb0f4f6a..096eb459d9 100644 --- a/SCons/Tool/install.xml +++ b/SCons/Tool/install.xml @@ -69,7 +69,8 @@ in this case. -If the command line +If the + option is given, the target directory will be prefixed by the directory path specified. This is useful to test installation behavior without installing to diff --git a/SCons/Tool/lex.xml b/SCons/Tool/lex.xml index 028072b6e5..f5244f543d 100644 --- a/SCons/Tool/lex.xml +++ b/SCons/Tool/lex.xml @@ -123,7 +123,9 @@ command-line option. Use this in preference to including -Used only in Windows environments to set a lex flag to prevent 'unistd.h' from being included. The default value is '--nounistd'. +Used only in Windows environments to set a lex flag to prevent +unistd.h from being included. +The default value is . diff --git a/SCons/Tool/link.xml b/SCons/Tool/link.xml index 63d499c011..0ab8b50682 100644 --- a/SCons/Tool/link.xml +++ b/SCons/Tool/link.xml @@ -83,8 +83,10 @@ if &cv-link-SHLIBVERSION; is set. Otherwise, it evaluates to an empty string. -A macro that automatically generates loadable module's SONAME based on $TARGET, -$LDMODULEVERSION and $LDMODULESUFFIX. Used by &b-link-LoadableModule; builder +A macro that automatically generates a loadable module's &cv-link-SONAME; +based on $TARGET, +&cv-link-LDMODULEVERSION; and &cv-link-LDMODULESUFFIX;. +Used by the &b-link-LoadableModule; builder when the linker tool supports SONAME (e.g. &t-link-gnulink;). @@ -94,11 +96,12 @@ when the linker tool supports SONAME (e.g. &t-link-gnulink;). This macro automatically introduces extra flags to &cv-link-LDMODULECOM; when -building versioned &b-link-LoadableModule; (that is when -&cv-link-LDMODULEVERSION; is set). _LDMODULEVERSIONFLAGS +building a versioned &b-link-LoadableModule; +(that is, when &cv-link-LDMODULEVERSION; is set). +&cv-_LDMODULEVERSIONFLAGS; usually adds &cv-link-SHLIBVERSIONFLAGS; and some extra dynamically generated -options (such as -Wl,-soname=$_LDMODULESONAME). It is unused -by plain (unversioned) loadable modules. +options (such as -Wl,-soname=$_LDMODULESONAME). +It is unused by plain (unversioned) loadable modules. @@ -107,11 +110,12 @@ by plain (unversioned) loadable modules. This macro automatically introduces extra flags to &cv-link-SHLINKCOM; when -building versioned &b-link-SharedLibrary; (that is when &cv-link-SHLIBVERSION; -is set). _SHLIBVERSIONFLAGS usually adds &cv-link-SHLIBVERSIONFLAGS; -and some extra dynamically generated options (such as --Wl,-soname=$_SHLIBSONAME. It is unused by "plain" -(unversioned) shared libraries. +building a versioned &b-link-SharedLibrary; +(that is, when &cv-link-SHLIBVERSION; is set). +&cv-_SHLIBVERSIONFLAGS; usually adds &cv-link-SHLIBVERSIONFLAGS; +and some extra dynamically generated options +(such as -Wl,-soname=$_SHLIBSONAME). +It is unused by "plain" (unversioned) shared libraries. @@ -119,8 +123,10 @@ and some extra dynamically generated options (such as -A macro that automatically generates shared library's SONAME based on $TARGET, -$SHLIBVERSION and $SHLIBSUFFIX. Used by &b-link-SharedLibrary; builder when +A macro that automatically generates a shared library's &cv-link-SONAME; +based on $TARGET, +&cv-link-SHLIBVERSION; and &cv-link-SHLIBSUFFIX;. +Used by the &b-link-SharedLibrary; builder when the linker tool supports SONAME (e.g. &t-link-gnulink;). @@ -202,8 +208,9 @@ General user options passed to the linker for building loadable modules. -Instructs the &b-link-LoadableModule; builder to not automatically create symlinks -for versioned modules. Defaults to $SHLIBNOVERSIONSYMLINKS +Instructs the &b-link-LoadableModule; builder +not to automatically create symlinks for versioned modules. +Defaults to &cv-link-SHLIBNOVERSIONSYMLINKS;. @@ -234,8 +241,8 @@ the same as $SHLIBSUFFIX. Extra flags added to &cv-link-LDMODULECOM; when building versioned -&b-link-LoadableModule;. These flags are only used when &cv-link-LDMODULEVERSION; is -set. +&b-link-LoadableModule;. +These flags are only used when &cv-link-LDMODULEVERSION; is set. @@ -399,11 +406,18 @@ See also &cv-link-LINKFLAGS; for linking static objects. -Variable used to hard-code SONAME for versioned shared library/loadable module. +The name of a versioned shared library/loadable module. +If specified, it is an explicit statement of the name; +if unspecified, the value is generated. +&cv-SONAME; and &cv-link-SOVERSION; may not both be specified +in the same &consenv; or override. +# Will cause libtest.so.2 to exist and be a symlink to libtest.so.0.1.2 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2') -The variable is used, for example, by &t-link-gnulink; linker tool. + + +This variable is used by toolchains that support versioned shared objects. @@ -411,17 +425,18 @@ The variable is used, for example, by &t-link-gnulink; linker tool. -This will construct the SONAME using on the base library name -(test in the example below) and use specified SOVERSION -to create SONAME. +Version string used in construction of &cv-link-SONAME;. +The version is added to the base library name +(test in the example below). +&cv-SONAME; and &cv-SOVERSION; may not both be specified +in the same &consenv; or override. +# SONAME will be libtest.so.2, and will be a symlink to libtest.so.0.1.2 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2') -The variable is used, for example, by &t-link-gnulink; linker tool. -In the example above SONAME would be libtest.so.2 -which would be a symlink and point to libtest.so.0.1.2 +This variable is used by toolchains that support versioned shared objects. diff --git a/SCons/Tool/packaging/packaging.xml b/SCons/Tool/packaging/packaging.xml index 6f1a8d8b5c..08163dc1c4 100644 --- a/SCons/Tool/packaging/packaging.xml +++ b/SCons/Tool/packaging/packaging.xml @@ -28,8 +28,9 @@ This file is processed by the bin/SConsDoc.py module Sets construction variables for the &b-link-Package; Builder. -If this tool is enabled, the -command-line option is also enabled. +If this tool is enabled, the + +command-line option is made available. @@ -56,7 +57,9 @@ env = Environment(tools=['default', 'packaging']) &SCons; can build packages in a number of well known packaging formats. The target package type may be selected with the &cv-link-PACKAGETYPE; construction variable -or the command line option. +or the + +command line option. The package type may be a list, in which case &SCons; will attempt to build packages for each type in the list. Example: From 0e1c820d7165a46115869801ebe5aeb6b0e28fc5 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 5 May 2026 07:14:28 -0600 Subject: [PATCH 2/2] Fix typo in doc hyperlink [skip appveyor] A reference to opt-help was missing the "help" part. Signed-off-by: Mats Wichmann --- SCons/Script/SConscript.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml index a4ff9f96cb..2af6d1ef59 100644 --- a/SCons/Script/SConscript.xml +++ b/SCons/Script/SConscript.xml @@ -278,7 +278,7 @@ file is found. Adds text to the help message shown when &scons; is called with the - or + or argument.