summaryrefslogtreecommitdiffstats
path: root/src/engine/SCons
diff options
context:
space:
mode:
authorMats Wichmann <mats@linux.com>2020-01-07 16:36:47 (GMT)
committerMats Wichmann <mats@linux.com>2020-01-14 13:51:15 (GMT)
commit44e28045d9a4a0ee64b40ce4b469fd461df885bb (patch)
tree57e95238a859ac6acf07bbf6506d74bda40c817b /src/engine/SCons
parent0ab03698067fe6e6fc0a3e245a0a5d42f20960c6 (diff)
downloadSCons-44e28045d9a4a0ee64b40ce4b469fd461df885bb.zip
SCons-44e28045d9a4a0ee64b40ce4b469fd461df885bb.tar.gz
SCons-44e28045d9a4a0ee64b40ce4b469fd461df885bb.tar.bz2
docs: refer *COM* and SH*COM* to each other [ci skip]
[fixes #2565] Object code intended for use in a shared library may need different compilation options than object code not intended for such use. When SCons tools recognize this need they define parallel sets of variables, such that for FOO there is both FOOCOM and SHFOOCOM, FOOCOMSTR and SHFOOCOMSTR, etc. Refer such pairs to each other. Issue 2565 described a case where a user did not realize they needed to use SHCXXCOMSTR to affect the output for certain C++-compiled objects. The discussion concluded this was just a doc fix. Some examination turned up cases of this in docs for the C compiler, C++ compiler, D compiler, Fortran compiler and linker modules, seemed better to just hit all of those. I would have preferred to move the pairs together into a single entry but it seems the scons doc markup doesn't support this kind of usage - a <cvar> can take only a single name attribute, and uses it to generate tags, etc. so there would have been a ton of surgery needed to implement that way. Signed-off-by: Mats Wichmann <mats@linux.com>
Diffstat (limited to 'src/engine/SCons')
-rw-r--r--src/engine/SCons/Tool/DCommon.xml24
-rw-r--r--src/engine/SCons/Tool/c++.xml17
-rw-r--r--src/engine/SCons/Tool/cc.xml22
-rw-r--r--src/engine/SCons/Tool/link.xml12
4 files changed, 60 insertions, 15 deletions
diff --git a/src/engine/SCons/Tool/DCommon.xml b/src/engine/SCons/Tool/DCommon.xml
index 7cc47da..6ff08da 100644
--- a/src/engine/SCons/Tool/DCommon.xml
+++ b/src/engine/SCons/Tool/DCommon.xml
@@ -27,6 +27,7 @@ See its __doc__ string for a discussion of the format.
<summary>
<para>
The D compiler to use.
+See also &cv-link-SHDC;.
</para>
</summary>
</cvar>
@@ -37,6 +38,18 @@ The D compiler to use.
The command line used to compile a D file to an object file.
Any options specified in the &cv-link-DFLAGS; construction variable
is included on this command line.
+See also &cv-link-SHDCOM;.
+</para>
+</summary>
+</cvar>
+
+<cvar name="DCOMSTR">
+<summary>
+<para>
+If set, the string displayed when a D source file
+is compiled to a (static) object file.
+If not set, then &cv-link-DCOM; (the command line) is displayed.
+See also &cv-link-SHDCOMSTR;.
</para>
</summary>
</cvar>
@@ -290,6 +303,17 @@ The command line to use when compiling code to be part of shared objects.
</summary>
</cvar>
+<cvar name="SHDCOMSTR">
+<summary>
+<para>
+If set, the string displayed when a D source file
+is compiled to a (shared) object file.
+If not set, then &cv-link-SHDCOM; (the command line) is displayed.
+See also &cv-link-DCOMSTR;.
+</para>
+</summary>
+</cvar>
+
<cvar name="SHDLIBVERSION">
<summary>
<para>
diff --git a/src/engine/SCons/Tool/c++.xml b/src/engine/SCons/Tool/c++.xml
index b59816b..0918b5f 100644
--- a/src/engine/SCons/Tool/c++.xml
+++ b/src/engine/SCons/Tool/c++.xml
@@ -47,6 +47,7 @@ Sets construction variables for generic POSIX C++ compilers.
</sets>
<uses>
<item>CXXCOMSTR</item>
+<item>SHCXXCOMSTR</item>
</uses>
</tool>
@@ -54,6 +55,7 @@ Sets construction variables for generic POSIX C++ compilers.
<summary>
<para>
The C++ compiler.
+See also &cv-link-SHCXX;.
</para>
</summary>
</cvar>
@@ -65,6 +67,7 @@ The command line used to compile a C++ source file to an object file.
Any options specified in the &cv-link-CXXFLAGS; and
&cv-link-CPPFLAGS; construction variables
are included on this command line.
+See also &cv-link-SHCXXCOM;.
</para>
</summary>
</cvar>
@@ -72,9 +75,10 @@ are included on this command line.
<cvar name="CXXCOMSTR">
<summary>
<para>
-The string displayed when a C++ source file
+If set, the string displayed when a C++ source file
is compiled to a (static) object file.
-If this is not set, then &cv-link-CXXCOM; (the command line) is displayed.
+If not set, then &cv-link-CXXCOM; (the command line) is displayed.
+See also &cv-link-SHCXXCOMSTR;.
</para>
<example_commands>
@@ -91,6 +95,7 @@ By default, this includes the value of &cv-link-CCFLAGS;,
so that setting &cv-CCFLAGS; affects both C and C++ compilation.
If you want to add C++-specific flags,
you must set or override the value of &cv-link-CXXFLAGS;.
+See also &cv-link-SHCXXFLAGS;.
</para>
</summary>
</cvar>
@@ -99,6 +104,7 @@ you must set or override the value of &cv-link-CXXFLAGS;.
<summary>
<para>
The C++ compiler used for generating shared-library objects.
+See also &cv-link-CXX;.
</para>
</summary>
</cvar>
@@ -111,6 +117,7 @@ to a shared-library object file.
Any options specified in the &cv-link-SHCXXFLAGS; and
&cv-link-CPPFLAGS; construction variables
are included on this command line.
+See also &cv-link-CXXCOM;.
</para>
</summary>
</cvar>
@@ -118,9 +125,10 @@ are included on this command line.
<cvar name="SHCXXCOMSTR">
<summary>
<para>
-The string displayed when a C++ source file
+If set, the string displayed when a C++ source file
is compiled to a shared object file.
-If this is not set, then &cv-link-SHCXXCOM; (the command line) is displayed.
+If not set, then &cv-link-SHCXXCOM; (the command line) is displayed.
+See also &cv-link-CXXCOMSTR;.
</para>
<example_commands>
@@ -134,6 +142,7 @@ env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
<para>
Options that are passed to the C++ compiler
to generate shared-library objects.
+See also &cv-link-CXXFLAGS;.
</para>
</summary>
</cvar>
diff --git a/src/engine/SCons/Tool/cc.xml b/src/engine/SCons/Tool/cc.xml
index 06e73ff..4150e23 100644
--- a/src/engine/SCons/Tool/cc.xml
+++ b/src/engine/SCons/Tool/cc.xml
@@ -51,6 +51,8 @@ Sets construction variables for generic POSIX C compilers.
</sets>
<uses>
<item>PLATFORM</item>
+<item>CCCOMSTR</item>
+<item>SHCCCOMSTR</item>
</uses>
</tool>
@@ -67,8 +69,8 @@ The C compiler.
<para>
The command line used to compile a C source file to a (static) object
file. Any options specified in the &cv-link-CFLAGS;, &cv-link-CCFLAGS; and
-&cv-link-CPPFLAGS; construction variables are included on this command
-line.
+&cv-link-CPPFLAGS; construction variables are included on this command line.
+See also &cv-link-SHCCCOM;.
</para>
</summary>
</cvar>
@@ -76,9 +78,10 @@ line.
<cvar name="CCCOMSTR">
<summary>
<para>
-The string displayed when a C source file
+If set, the string displayed when a C source file
is compiled to a (static) object file.
-If this is not set, then &cv-link-CCCOM; (the command line) is displayed.
+If not set, then &cv-link-CCCOM; (the command line) is displayed.
+See also &cv-link-SHCCCOMSTR;.
</para>
<example_commands>
@@ -91,6 +94,7 @@ env = Environment(CCCOMSTR = "Compiling static object $TARGET")
<summary>
<para>
General options that are passed to the C and C++ compilers.
+See also &cv-link-SHCCFLAGS;.
</para>
</summary>
</cvar>
@@ -99,6 +103,7 @@ General options that are passed to the C and C++ compilers.
<summary>
<para>
General options that are passed to the C compiler (C only; not C++).
+See also &cv-link-SHCFLAGS;.
</para>
</summary>
</cvar>
@@ -156,6 +161,7 @@ The default list is:
<summary>
<para>
The C compiler used for generating shared-library objects.
+See also &cv-link-CC;.
</para>
</summary>
</cvar>
@@ -169,6 +175,7 @@ Any options specified in the &cv-link-SHCFLAGS;,
&cv-link-SHCCFLAGS; and
&cv-link-CPPFLAGS; construction variables
are included on this command line.
+See also &cv-link-CCCOM;.
</para>
</summary>
</cvar>
@@ -176,9 +183,10 @@ are included on this command line.
<cvar name="SHCCCOMSTR">
<summary>
<para>
-The string displayed when a C source file
+If set, the string displayed when a C source file
is compiled to a shared object file.
-If this is not set, then &cv-link-SHCCCOM; (the command line) is displayed.
+If not set, then &cv-link-SHCCCOM; (the command line) is displayed.
+See also &cv-link-CCCOMSTR;.
</para>
<example_commands>
@@ -192,6 +200,7 @@ env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
<para>
Options that are passed to the C and C++ compilers
to generate shared-library objects.
+See also &cv-link-CCFLAGS;.
</para>
</summary>
</cvar>
@@ -201,6 +210,7 @@ to generate shared-library objects.
<para>
Options that are passed to the C compiler (only; not C++)
to generate shared-library objects.
+See also &cv-link-CFLAGS;.
</para>
</summary>
</cvar>
diff --git a/src/engine/SCons/Tool/link.xml b/src/engine/SCons/Tool/link.xml
index 654dafc..7a84e1a 100644
--- a/src/engine/SCons/Tool/link.xml
+++ b/src/engine/SCons/Tool/link.xml
@@ -55,8 +55,8 @@ based on the types of source files.
<item>__LDMODULEVERSIONFLAGS</item>
</sets>
<uses>
-<item>SHLINKCOMSTR</item>
<item>LINKCOMSTR</item>
+<item>SHLINKCOMSTR</item>
<item>LDMODULECOMSTR</item>
</uses>
</tool>
@@ -184,8 +184,8 @@ On other systems, this is the same as &cv-link-SHLINK;.
<cvar name="LDMODULECOMSTR">
<summary>
<para>
-The string displayed when building loadable modules.
-If this is not set, then &cv-link-LDMODULECOM; (the command line) is displayed.
+If set, the string displayed when building loadable modules.
+If not set, then &cv-link-LDMODULECOM; (the command line) is displayed.
</para>
</summary>
</cvar>
@@ -258,9 +258,10 @@ The command line used to link object files into an executable.
<cvar name="LINKCOMSTR">
<summary>
<para>
-The string displayed when object files
+If set, the string displayed when object files
are linked into an executable.
-If this is not set, then &cv-link-LINKCOM; (the command line) is displayed.
+If not set, then &cv-link-LINKCOM; (the command line) is displayed.
+See also &cv-link-SHLINKCOMSTR;.
</para>
<example_commands>
@@ -334,6 +335,7 @@ The command line used to link programs using shared libraries.
<para>
The string displayed when programs using shared libraries are linked.
If this is not set, then &cv-link-SHLINKCOM; (the command line) is displayed.
+See also &cv-link-LINKCOMSTR;.
</para>
<example_commands>
generated by cgit v0.12 at 2025-03-10 01:03:46 (GMT)