Merge pull request #3425 from mwichmann/tool-docs

manpage: clarify that tools=[list] overrides [ci skip]

7 files changed, 239 insertions, 51 deletions

diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen
index ecd9c98..0d30f6f 100644
--- a/doc/generated/tools.gen
+++ b/doc/generated/tools.gen
@@ -91,7 +91,7 @@ Sets construction variables for the bcc32 compiler.
     <term>cc</term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
-Sets construction variables for generic POSIX C copmilers.
+Sets construction variables for generic POSIX C compilers.
 </para>
 <para>Sets:  &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-FRAMEWORKPATH;, &cv-link-FRAMEWORKS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHOBJSUFFIX;.</para><para>Uses:  &cv-link-PLATFORM;.</para></listitem>
   </varlistentry>
@@ -139,9 +139,91 @@ Set construction variables for cygwin linker/loader.
     <term>default</term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
-Sets variables by calling a default list of Tool modules
-for the platform on which SCons is running.
+Sets <literal xmlns="http://www.scons.org/dbxsd/v1.0">construction variables</literal> for a default list of Tool modules.
+Use <emphasis role="bold">default</emphasis>
+in the tools list to retain the original defaults,
+since the <parameter>tools</parameter> parameter
+is treated as a literal statement of the tools
+to be made available in that <literal xmlns="http://www.scons.org/dbxsd/v1.0">construction environment</literal>, not an addition.
 </para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+The list of tools selected by default is not static,
+but is dependent both on
+the platform and on the software installed on the platform.
+Some tools will not initialize if an underlying command is
+not found, and some tools are selected from a list of choices
+on a first-found basis. The finished tool list can be
+examined by inspecting the <envar>TOOLS</envar> <literal xmlns="http://www.scons.org/dbxsd/v1.0">construction variable</literal>
+in the <literal xmlns="http://www.scons.org/dbxsd/v1.0">construction environment</literal>.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On all platforms, all tools from the following list
+are selected whose respective conditions are met:
+filesystem, wix, lex, yacc, rpcgen, swig,
+jar, javac, javah, rmic, dvipdf, dvips, gs,
+tex, latex, pdflatex, pdftex, tar, zip, textfile.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On Linux systems, the default tools list selects
+(first-found): a C compiler from
+gcc, intelc, icc, cc;
+a C++ compiler from
+g++, intelc, icc, cxx;
+an assembler from
+gas, nasm, masm;
+a linker from
+gnulink, ilink;
+a Fortran compiler from
+gfortran, g77, ifort, ifl, f95, f90, f77;
+and a static archiver 'ar'.
+It also selects all found from the list
+m4, rpm.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On Windows systems, the default tools list selects
+(first-found): a C compiler from
+msvc, mingw, gcc, intelc, icl, icc, cc, bcc32;
+a C++ compiler from
+msvc, intelc, icc, g++, cxx, bcc32;
+an assembler from
+masm, nasm, gas, 386asm;
+a linker from
+mslink, gnulink, ilink, linkloc, ilink32;
+a Fortran compiler from
+gfortran, g77, ifl, cvf, f95, f90, fortran;
+and a static archiver from
+mslib, ar, tlib;
+It also selects all found from the list
+msvs, midl.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+On MacOS systems, the default tools list selects
+(first-found): a C compiler from
+gcc, cc;
+a C++ compiler from
+g++, cxx;
+an assembler 'as';
+a linker from
+applelink, gnulink;
+a Fortran compiler from
+gfortran, f95, f90, g77;
+and a static archiver ar.
+It also selects all found from the list
+m4, rpm.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Default lists for other platforms can be found by
+examining the <filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>
+source code (see
+<filename>SCons/Tool/__init__.py</filename>).
+</para>
+
 </listitem>
   </varlistentry>
   <varlistentry id="t-dmd">
@@ -627,7 +709,9 @@ Sets construction variables for the <application xmlns="http://www.scons.org/dbx
     <term>link</term>
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
-Sets construction variables for generic POSIX linkers.
+Sets construction variables for generic POSIX linkers. This is
+a "smart" linker tool which selects a compiler to complete the linking
+based on the types of source files.
 </para>
 <para>Sets:  &cv-link-LDMODULE;, &cv-link-LDMODULECOM;, &cv-link-LDMODULEFLAGS;, &cv-link-LDMODULENOVERSIONSYMLINKS;, &cv-link-LDMODULEPREFIX;, &cv-link-LDMODULESUFFIX;, &cv-link-LDMODULEVERSION;, &cv-link-LDMODULEVERSIONFLAGS;, &cv-link-LIBDIRPREFIX;, &cv-link-LIBDIRSUFFIX;, &cv-link-LIBLINKPREFIX;, &cv-link-LIBLINKSUFFIX;, &cv-link-LINK;, &cv-link-LINKCOM;, &cv-link-LINKFLAGS;, &cv-link-SHLIBSUFFIX;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;, &cv-link-SHLINKFLAGS;, &cv-link-__LDMODULEVERSIONFLAGS;, &cv-link-__SHLIBVERSIONFLAGS;.</para><para>Uses:  &cv-link-LDMODULECOMSTR;, &cv-link-LINKCOMSTR;, &cv-link-SHLINKCOMSTR;.</para></listitem>
   </varlistentry>
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index 7be9c63..8f09512 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -4011,7 +4011,7 @@ The command line used to pass files to the Microsoft IDL compiler.
     <listitem>
 <para xmlns="http://www.scons.org/dbxsd/v1.0">
 The string displayed when
-the Microsoft IDL copmiler is called.
+the Microsoft IDL compiler is called.
 If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-MIDLCOM"><envar>$MIDLCOM</envar></link> (the command line) is displayed.
 </para>
 </listitem>
@@ -6518,16 +6518,6 @@ Example <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION">
 </para>
 </listitem>
   </varlistentry>
-  <varlistentry id="cv-SHLIBVERSIONFLAGS">
-    <term>SHLIBVERSIONFLAGS</term>
-    <listitem>
-<para xmlns="http://www.scons.org/dbxsd/v1.0">
-Extra flags added to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKCOM"><envar>$SHLINKCOM</envar></link> when building versioned
-<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-SharedLibrary"><function>SharedLibrary</function></link>. These flags are only used when <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> is
-set.
-</para>
-</listitem>
-  </varlistentry>
   <varlistentry id="cv-_SHLIBVERSIONFLAGS">
     <term>_SHLIBVERSIONFLAGS</term>
     <listitem>
@@ -6541,6 +6531,16 @@ and some extra dynamically generated options (such as
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="cv-SHLIBVERSIONFLAGS">
+    <term>SHLIBVERSIONFLAGS</term>
+    <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Extra flags added to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKCOM"><envar>$SHLINKCOM</envar></link> when building versioned
+<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-SharedLibrary"><function>SharedLibrary</function></link>. These flags are only used when <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> is
+set.
+</para>
+</listitem>
+  </varlistentry>
   <varlistentry id="cv-SHLINK">
     <term>SHLINK</term>
     <listitem>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index e610386..faec455 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -209,12 +209,12 @@ that you want to use to build your target files
 are not in standard system locations,
 <command>scons</command>
 will not find them unless
-you explicitly set the PATH
+you explicitly set the <envar>PATH</envar>
 to include those locations.
 Whenever you create an
 <command>scons</command>
 construction environment,
-you can propagate the value of PATH
+you can propagate the value of <envar>PATH</envar>
 from your external environment as follows:</para>
 
 <literallayout class="monospaced">
@@ -223,13 +223,20 @@ env = Environment(ENV = {'PATH' : os.environ['PATH']})
 </literallayout>
 
 <para>Similarly, if the commands use external environment variables
-like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
+like
+<envar>PATH</envar>,
+<envar>HOME</envar>,
+<envar>JAVA_HOME</envar>,
+<envar>LANG</envar>,
+<envar>SHELL</envar>,
+<envar>TERM</envar>,
+etc.,
 these variables can also be explicitly propagated:</para>
 
 <literallayout class="monospaced">
 import os
-env = Environment(ENV = {'PATH' : os.environ['PATH'],
-                         'HOME' : os.environ['HOME']})
+env = Environment(ENV = {'PATH': os.environ['PATH'],
+                         'HOME': os.environ['HOME']})
 </literallayout>
 
 <para>Or you may explicitly propagate the invoking user's
@@ -2112,36 +2119,59 @@ env = Environment(platform = my_platform)
 
 <para>Additionally, a specific set of tools
 with which to initialize the environment
-may be specified as an optional keyword argument:</para>
+may be specified using the optional keyword argument
+<parameter>tools</parameter>:</para>
 
 <literallayout class="monospaced">
-env = Environment(tools = ['msvc', 'lex'])
+env = Environment(tools=['msvc', 'lex'])
 </literallayout>
 
-<para>Non-built-in tools may be specified using the toolpath argument:</para>
+<para>
+The <parameter>tools</parameter> argument overrides
+the tool list, it does not add to it, so be
+sure to include all the tools you need.
+For example if you are  building a c/c++ program
+you must  add a tool for both compiler and linker,
+as in <literal>tools=['clang', 'link']</literal>.
+The tool name <literal>'default'</literal> can
+be used to retain the default list.
+</para>
+
+<para>Non-built-in tools may be specified using the
+optional <parameter>toolpath</parameter> keyword argument:</para>
 
 <literallayout class="monospaced">
-env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
+env = Environment(tools=['default', 'foo'], toolpath=['tools'])
 </literallayout>
 
-<para>This looks for a tool specification in tools/foo.py (as well as
-using the ordinary default tools for the platform).  foo.py should
-have two functions: generate(env, **kw) and exists(env).
+<para>
+This looks for a tool specification in <filename>tools/foo.py</filename>
+as well as using the ordinary default tools for the platform.
+</para>
+
+<para>
+A tool specification must include two functions:
+<function>generate(env, **kw)</function>
+and <function>exists(env)</function>.
 The
-<function>generate()</function>
+<function>generate</function>
 function
-modifies the passed-in environment
+modifies the environment referenced by <parameter>env</parameter>
 to set up variables so that the tool
 can be executed;
 it may use any keyword arguments
-that the user supplies (see below)
+that the user supplies in <parameter>kw</parameter> (see below)
 to vary its initialization.
 The
-<function>exists()</function>
+<function>exists</function>
 function should return a true
 value if the tool is available.
+</para>
+
+<para>
 Tools in the toolpath are used before
-any of the built-in ones.  For example, adding gcc.py to the toolpath
+any of the built-in ones.  For example, adding
+<filename>gcc.py</filename> to the toolpath
 would override the built-in gcc tool.
 Also note that the toolpath is
 stored in the environment for use
@@ -2149,7 +2179,8 @@ by later calls to
 <emphasis role="bold">Clone</emphasis>()
 and
 <emphasis role="bold">Tool</emphasis>()
-methods:</para>
+methods:
+</para>
 
 <literallayout class="monospaced">
 base = Environment(toolpath=['custom_path'])
@@ -2192,8 +2223,9 @@ or otherwise changing its initialization.</para>
 def generate(env, **kw):
   # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
   env['MY_TOOL'] = kw.get('arg1', '1')
+
 def exists(env):
-  return 1
+  return True
 
 # in SConstruct:
 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
@@ -2257,17 +2289,6 @@ env.SomeTool(targets, sources)
 <!-- '\" END GENERATED TOOL DESCRIPTIONS -->
 <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
 
-<para>Additionally, there is a "tool" named
-<emphasis role="bold">default</emphasis>
-which configures the
-environment with a default set of tools for the current platform.</para>
-
-<para>On posix and cygwin platforms
-the GNU tools (e.g. gcc) are preferred by SCons,
-on Windows the Microsoft tools (e.g. msvc)
-followed by MinGW are preferred by SCons,
-and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.</para>
-
 </refsect2>
 
 <refsect2 id='builder_methods'><title>Builder Methods</title>
diff --git a/src/engine/SCons/Tool/cc.xml b/src/engine/SCons/Tool/cc.xml
index 9330436..7ce8b36 100644
--- a/src/engine/SCons/Tool/cc.xml
+++ b/src/engine/SCons/Tool/cc.xml
@@ -26,7 +26,7 @@ See its __doc__ string for a discussion of the format.
 <tool name="cc">
 <summary>
 <para>
-Sets construction variables for generic POSIX C copmilers.
+Sets construction variables for generic POSIX C compilers.
 </para>
 </summary>
 <sets>
diff --git a/src/engine/SCons/Tool/default.xml b/src/engine/SCons/Tool/default.xml
index 38eb122..4b862fb 100644
--- a/src/engine/SCons/Tool/default.xml
+++ b/src/engine/SCons/Tool/default.xml
@@ -26,10 +26,91 @@ See its __doc__ string for a discussion of the format.
 <tool name="default">
 <summary>
 <para>
-Sets variables by calling a default list of Tool modules
-for the platform on which SCons is running.
+Sets &consvars; for a default list of Tool modules.
+Use <emphasis role="bold">default</emphasis>
+in the tools list to retain the original defaults,
+since the <parameter>tools</parameter> parameter
+is treated as a literal statement of the tools
+to be made available in that &consenv;, not an addition.
 </para>
+
+<para>
+The list of tools selected by default is not static,
+but is dependent both on
+the platform and on the software installed on the platform.
+Some tools will not initialize if an underlying command is
+not found, and some tools are selected from a list of choices
+on a first-found basis. The finished tool list can be
+examined by inspecting the <envar>TOOLS</envar> &consvar;
+in the &consenv;.
+</para>
+
+<para>
+On all platforms, all tools from the following list
+are selected whose respective conditions are met:
+filesystem, wix, lex, yacc, rpcgen, swig,
+jar, javac, javah, rmic, dvipdf, dvips, gs,
+tex, latex, pdflatex, pdftex, tar, zip, textfile.
+</para>
+
+<para>
+On Linux systems, the default tools list selects
+(first-found): a C compiler from
+gcc, intelc, icc, cc;
+a C++ compiler from
+g++, intelc, icc, cxx;
+an assembler from
+gas, nasm, masm;
+a linker from
+gnulink, ilink;
+a Fortran compiler from
+gfortran, g77, ifort, ifl, f95, f90, f77;
+and a static archiver 'ar'.
+It also selects all found from the list
+m4, rpm.
+</para>
+
+<para>
+On Windows systems, the default tools list selects
+(first-found): a C compiler from
+msvc, mingw, gcc, intelc, icl, icc, cc, bcc32;
+a C++ compiler from
+msvc, intelc, icc, g++, cxx, bcc32;
+an assembler from
+masm, nasm, gas, 386asm;
+a linker from
+mslink, gnulink, ilink, linkloc, ilink32;
+a Fortran compiler from
+gfortran, g77, ifl, cvf, f95, f90, fortran;
+and a static archiver from
+mslib, ar, tlib;
+It also selects all found from the list
+msvs, midl.
+</para>
+
+<para>
+On MacOS systems, the default tools list selects
+(first-found): a C compiler from
+gcc, cc;
+a C++ compiler from
+g++, cxx;
+an assembler 'as';
+a linker from
+applelink, gnulink;
+a Fortran compiler from
+gfortran, f95, f90, g77;
+and a static archiver ar.
+It also selects all found from the list
+m4, rpm.
+</para>
+
+<para>
+Default lists for other platforms can be found by
+examining the &scons;
+source code (see
+<filename>SCons/Tool/__init__.py</filename>).
+</para>
+
 </summary>
 </tool>
-
 </sconsdoc>
diff --git a/src/engine/SCons/Tool/link.xml b/src/engine/SCons/Tool/link.xml
index 2f913fe..75b2ed8 100644
--- a/src/engine/SCons/Tool/link.xml
+++ b/src/engine/SCons/Tool/link.xml
@@ -26,7 +26,9 @@ See its __doc__ string for a discussion of the format.
 <tool name="link">
 <summary>
 <para>
-Sets construction variables for generic POSIX linkers.
+Sets construction variables for generic POSIX linkers. This is
+a "smart" linker tool which selects a compiler to complete the linking
+based on the types of source files.
 </para>
 </summary>
 <sets>
diff --git a/src/engine/SCons/Tool/midl.xml b/src/engine/SCons/Tool/midl.xml
index efd83cc..63cf527 100644
--- a/src/engine/SCons/Tool/midl.xml
+++ b/src/engine/SCons/Tool/midl.xml
@@ -86,7 +86,7 @@ The command line used to pass files to the Microsoft IDL compiler.
 <summary>
 <para>
 The string displayed when
-the Microsoft IDL copmiler is called.
+the Microsoft IDL compiler is called.
 If this is not set, then &cv-link-MIDLCOM; (the command line) is displayed.
 </para>
 </summary>