From 14e6f0d1b96f3bc9684922a16424d5638c2bee3f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 4 Apr 2021 07:22:48 -0600 Subject: Add some more entity links in docs [skip appveyor] [skip travis] The only wording changes of any note are for the link tool, where it is suggested POSIX users don't fiddle with LINK and SHLINK. Signed-off-by: Mats Wichmann --- SCons/Defaults.xml | 14 +++--- SCons/Tool/compilation_db.xml | 2 +- SCons/Tool/default.xml | 66 ++++++++++++++---------- SCons/Tool/docbook/docbook.xml | 100 +++++++++++++++++++------------------ SCons/Tool/dvi.xml | 2 +- SCons/Tool/gas.xml | 2 +- SCons/Tool/gettext.xml | 4 +- SCons/Tool/gs.xml | 27 +++++----- SCons/Tool/hpcc.xml | 6 +-- SCons/Tool/intelc.xml | 6 +-- SCons/Tool/link.xml | 20 ++++++++ SCons/Tool/packaging/packaging.xml | 2 +- doc/man/scons.xml | 11 ++-- doc/scons.mod | 2 +- 14 files changed, 154 insertions(+), 110 deletions(-) diff --git a/SCons/Defaults.xml b/SCons/Defaults.xml index a6c1ec3..33d219b 100644 --- a/SCons/Defaults.xml +++ b/SCons/Defaults.xml @@ -26,7 +26,7 @@ See its __doc__ string for a discussion of the format. -A function used to produce variables like &cv-_CPPINCFLAGS;. It takes +A function used to produce variables like &cv-link-_CPPINCFLAGS;. It takes four or five arguments: a prefix to concatenate onto each element, a list of elements, a suffix to concatenate onto each element, an environment @@ -58,7 +58,7 @@ file. -The name of the Configure context log file. +The name of the &Configure; context log file. The default is config.log in the top-level directory @@ -75,7 +75,7 @@ file. An automatically-generated &consvar; containing the C preprocessor command-line options to define values. -The value of &cv-_CPPDEFFLAGS; is created +The value of &cv-link-_CPPDEFFLAGS; is created by respectively prepending and appending &cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; to each definition in &cv-link-CPPDEFINES;. @@ -99,7 +99,7 @@ If &cv-CPPDEFINES; is a string, the values of the &cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars; will be respectively prepended and appended to -each definition in &cv-CPPDEFINES;. +each definition in &cv-link-CPPDEFINES;. @@ -111,7 +111,7 @@ env = Environment(CPPDEFINES='xyz') If &cv-CPPDEFINES; is a list, the values of the -&cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars; +&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars; will be respectively prepended and appended to each element in the list. If any element is a list or tuple, @@ -128,7 +128,7 @@ env = Environment(CPPDEFINES=[('B', 2), 'A']) If &cv-CPPDEFINES; is a dictionary, the values of the -&cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars; +&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars; will be respectively prepended and appended to each item from the dictionary. The key of each dictionary item @@ -207,7 +207,7 @@ Python's os.sep. Note: -directory names in &cv-link-CPPPATH; +directory names in &cv-CPPPATH; will be looked-up relative to the directory of the SConscript file when they are used in a command. To force &scons; diff --git a/SCons/Tool/compilation_db.xml b/SCons/Tool/compilation_db.xml index aac1ed2..bad808f 100644 --- a/SCons/Tool/compilation_db.xml +++ b/SCons/Tool/compilation_db.xml @@ -103,7 +103,7 @@ See its __doc__ string for a discussion of the format. - The string displayed when the &b-CompilationDatabase; + The string displayed when the &b-link-CompilationDatabase; builder's action is run. diff --git a/SCons/Tool/default.xml b/SCons/Tool/default.xml index c729c1c..15dc2f7 100644 --- a/SCons/Tool/default.xml +++ b/SCons/Tool/default.xml @@ -41,67 +41,79 @@ 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 TOOLS &consvar; +examined by inspecting the &cv-link-TOOLS; &consvar; in the &consenv;. -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. +On all platforms, the tools from the following list +are selected if their respective conditions are met: + filesystem;, + wix, +&t-link-lex;, &t-link-yacc;, +&t-link-rpcgen;, &t-link-swig;, +&t-link-jar;, &t-link-javac;, &t-link-javah;, &t-link-rmic;, +&t-link-dvipdf;, &t-link-dvips;, &t-link-gs;, +&t-link-tex;, &t-link-latex;, &t-link-pdflatex;, &t-link-pdftex;, +&t-link-tar;, &t-link-zip;, &t-link-textfile;. On Linux systems, the default tools list selects (first-found): a C compiler from -gcc, intelc, icc, cc; +&t-link-gcc;, &t-link-intelc;, &t-link-icc;, &t-link-cc;; a C++ compiler from -g++, intelc, icc, cxx; +&t-link-gXX;, &t-link-intelc;, &t-link-icc;, &t-link-cXX;; an assembler from -gas, nasm, masm; +&t-link-gas;, &t-link-nasm;, &t-link-masm;; a linker from -gnulink, ilink; +&t-link-gnulink;, &t-link-ilink;; a Fortran compiler from -gfortran, g77, ifort, ifl, f95, f90, f77; -and a static archiver 'ar'. +&t-link-gfortran;, &t-link-g77;, &t-link-ifort;, &t-link-ifl;, +&t-link-f95;, &t-link-f90;, &t-link-f77;; +and a static archiver &t-link-ar;. It also selects all found from the list -m4, rpm. +&t-link-m4; + rpm. On Windows systems, the default tools list selects (first-found): a C compiler from -msvc, mingw, gcc, intelc, icl, icc, cc, bcc32; +&t-link-msvc;, &t-link-mingw;, &t-link-gcc;, &t-link-intelc;, +&t-link-icl;, &t-link-icc;, &t-link-cc;, &t-link-bcc32;; a C++ compiler from -msvc, intelc, icc, g++, cxx, bcc32; +&t-link-msvc;, &t-link-intelc;, &t-link-icc;, &t-link-gXX;, +&t-link-cXX;, &t-link-bcc32;; an assembler from -masm, nasm, gas, 386asm; +&t-link-masm;, &t-link-nasm;, &t-link-gas;, &t-link-386asm;; a linker from -mslink, gnulink, ilink, linkloc, ilink32; +&t-link-mslink;, &t-link-gnulink;, &t-link-ilink;, +&t-link-linkloc;, &t-link-ilink32;; a Fortran compiler from -gfortran, g77, ifl, cvf, f95, f90, fortran; +&t-link-gfortran;, &t-link-g77;, &t-link-ifl;, &t-link-cvf;, +&t-link-f95;, &t-link-f90;, &t-link-fortran;; and a static archiver from -mslib, ar, tlib; +&t-link-mslib;, &t-link-ar;, &t-link-tlib;; It also selects all found from the list -msvs, midl. +&t-link-msvs;, &t-link-midl;. On MacOS systems, the default tools list selects (first-found): a C compiler from -gcc, cc; +&t-link-gcc;, &t-link-cc;; a C++ compiler from -g++, cxx; -an assembler 'as'; +&t-link-gXX;, &t-link-cXX;; +an assembler &t-link-as;; a linker from -applelink, gnulink; +&t-link-applelink;, &t-link-gnulink;; a Fortran compiler from -gfortran, f95, f90, g77; -and a static archiver ar. +&t-link-gfortran;, &t-link-f95;, &t-link-f90;, &t-link-g77;; +and a static archiver &t-link-ar;. It also selects all found from the list -m4, rpm. +&t-link-m4;, + rpm. diff --git a/SCons/Tool/docbook/docbook.xml b/SCons/Tool/docbook/docbook.xml index 4c079b7..b0de859 100644 --- a/SCons/Tool/docbook/docbook.xml +++ b/SCons/Tool/docbook/docbook.xml @@ -40,29 +40,29 @@ stylesheet utils/xmldepend.xsl by Paul DuBois is used for t Note, that there is no support for XML catalog resolving offered! This tool calls the XSLT processors and PDF renderers with the stylesheets you specified, that's it. The rest lies in your hands and you still have to know what you're doing when -resolving names via a catalog. +resolving names via a catalog. For activating the tool "docbook", you have to add its name to the Environment constructor, like this env = Environment(tools=['docbook']) -On its startup, the Docbook tool tries to find a required xsltproc processor, and -a PDF renderer, e.g. fop. So make sure that these are added to your system's environment -PATH and can be called directly, without specifying their full path. +On its startup, the &t-docbook; tool tries to find a required xsltproc processor, and +a PDF renderer, e.g. fop. So make sure that these are added to your system's environment +PATH and can be called directly without specifying their full path. For the most basic processing of Docbook to HTML, you need to have installed -the Python lxml binding to libxml2, or - +the Python lxml +binding to libxml2, or -a standalone XSLT processor, currently detected are xsltproc, saxon, saxon-xslt -and xalan. +a standalone XSLT processor, currently detected are xsltproc, saxon, saxon-xslt +and xalan. Rendering to PDF requires you to have one of the applications -fop or xep installed. +fop or xep installed. Creating a HTML or PDF document is very simple and straightforward. Say @@ -93,14 +93,14 @@ Tool uses the given names as file stems, and adds the suffixes for target and so accordingly. -The rules given above are valid for the Builders &b-link-DocbookHtml;, -&b-link-DocbookPdf;, &b-link-DocbookEpub;, &b-link-DocbookSlidesPdf; and &b-link-DocbookXInclude;. For the +The rules given above are valid for the Builders &b-link-DocbookHtml;, +&b-link-DocbookPdf;, &b-link-DocbookEpub;, &b-link-DocbookSlidesPdf; and &b-link-DocbookXInclude;. For the &b-link-DocbookMan; transformation you can specify a target name, but the actual output names are automatically set from the refname entries in your XML source. -The Builders &b-link-DocbookHtmlChunked;, &b-link-DocbookHtmlhelp; and +The Builders &b-link-DocbookHtmlChunked;, &b-link-DocbookHtmlhelp; and &b-link-DocbookSlidesHtml; are special, in that: they create a large set of files, where the exact names and their number depend @@ -112,7 +112,7 @@ XSL transformation is not picked up by the stylesheets. -As a result, there is simply no use in specifying a target HTML name. +As a result, there is simply no use in specifying a target HTML name. So the basic syntax for these builders is always: env = Environment(tools=['docbook']) @@ -120,7 +120,7 @@ env.DocbookHtmlhelp('manual') If you want to use a specific XSL file, you can set the -additional xsl parameter to your +additional xsl parameter to your Builder call as follows: env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl') @@ -129,21 +129,24 @@ Builder call as follows: e.g. html.xsl for HTML and pdf.xsl for PDF output, a set of variables for setting the default XSL name is provided. These are: -DOCBOOK_DEFAULT_XSL_HTML -DOCBOOK_DEFAULT_XSL_HTMLCHUNKED -DOCBOOK_DEFAULT_XSL_HTMLHELP -DOCBOOK_DEFAULT_XSL_PDF -DOCBOOK_DEFAULT_XSL_EPUB -DOCBOOK_DEFAULT_XSL_MAN -DOCBOOK_DEFAULT_XSL_SLIDESPDF -DOCBOOK_DEFAULT_XSL_SLIDESHTML +DOCBOOK_DEFAULT_XSL_HTML +DOCBOOK_DEFAULT_XSL_HTMLCHUNKED +DOCBOOK_DEFAULT_XSL_HTMLHELP +DOCBOOK_DEFAULT_XSL_PDF +DOCBOOK_DEFAULT_XSL_EPUB +DOCBOOK_DEFAULT_XSL_MAN +DOCBOOK_DEFAULT_XSL_SLIDESPDF +DOCBOOK_DEFAULT_XSL_SLIDESHTML and you can set them when constructing your environment: -env = Environment(tools=['docbook'], - DOCBOOK_DEFAULT_XSL_HTML='html.xsl', - DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl') -env.DocbookHtml('manual') # now uses html.xsl + +env = Environment( + tools=['docbook'], + DOCBOOK_DEFAULT_XSL_HTML='html.xsl', + DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl', +) +env.DocbookHtml('manual') # now uses html.xsl @@ -283,7 +286,7 @@ if one of them is installed (fop gets checked first). Additonal command-line flags for the external executable -xsltproc (or saxon, +xsltproc (or saxon, xalan). @@ -321,7 +324,7 @@ for saxon and saxon-xslt, respectively. The full command-line for the external executable -xsltproc (or saxon, +xsltproc (or saxon, xalan). @@ -392,8 +395,8 @@ env.DocbookHtml('manual') -A pseudo-Builder, providing a Docbook toolchain for chunked HTML output. -It supports the base.dir parameter. The +A pseudo-Builder providing a Docbook toolchain for chunked HTML output. +It supports the base.dir parameter. The chunkfast.xsl file (requires "EXSLT") is used as the default stylesheet. Basic syntax: @@ -404,22 +407,23 @@ env.DocbookHtmlChunked('manual') where manual.xml is the input file. -If you use the root.filename +If you use the root.filename parameter in your own stylesheets you have to specify the new target name. This ensures that the dependencies get correct, especially for the cleanup via scons -c: env = Environment(tools=['docbook']) env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl') -Some basic support for the base.dir is provided. You -can add the base_dir keyword to your Builder -call, and the given prefix gets prepended to all the created filenames: +Some basic support for the base.dir parameter +is provided. You can add the base_dir keyword to +your Builder call, and the given prefix gets prepended to all the +created filenames: env = Environment(tools=['docbook']) env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/') Make sure that you don't forget the trailing slash for the base folder, else -your files get renamed only! +your files get renamed only! @@ -438,15 +442,15 @@ env.DocbookHtmlhelp('manual') where manual.xml is the input file. -If you use the root.filename +If you use the root.filename parameter in your own stylesheets you have to specify the new target name. -This ensures that the dependencies get correct, especially for the cleanup via scons -c: +This ensures that the dependencies get correct, especially for the cleanup via scons -c: env = Environment(tools=['docbook']) env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl') -Some basic support for the base.dir parameter -is provided. You can add the base_dir keyword to +Some basic support for the base.dir parameter +is provided. You can add the base_dir keyword to your Builder call, and the given prefix gets prepended to all the created filenames: @@ -454,7 +458,7 @@ created filenames: env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/') Make sure that you don't forget the trailing slash for the base folder, else -your files get renamed only! +your files get renamed only! @@ -513,7 +517,7 @@ Its basic syntax is: env.DocbookMan('manual') -where manual.xml is the input file. Note, that +where manual.xml is the input file. Note, that you can specify a target name, but the actual output names are automatically set from the refname entries in your XML source. @@ -550,25 +554,25 @@ A pseudo-Builder, providing a Docbook toolchain for HTML slides output. env.DocbookSlidesHtml('manual') -If you use the titlefoil.html parameter in +If you use the titlefoil.html parameter in your own stylesheets you have to give the new target name. This ensures -that the dependencies get correct, especially for the cleanup via -scons -c: +that the dependencies get correct, especially for the cleanup via +scons -c: env = Environment(tools=['docbook']) env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl') -Some basic support for the base.dir parameter +Some basic support for the base.dir parameter is provided. You -can add the base_dir keyword to your Builder +can add the base_dir keyword to your Builder call, and the given prefix gets prepended to all the created filenames: env = Environment(tools=['docbook']) env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/') Make sure that you don't forget the trailing slash for the base folder, else -your files get renamed only! +your files get renamed only! @@ -596,7 +600,7 @@ A pseudo-Builder, applying a given XSL transformation to the input file. env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt') -Note, that this builder requires the xsl parameter +Note, that this builder requires the xsl parameter to be set. diff --git a/SCons/Tool/dvi.xml b/SCons/Tool/dvi.xml index 3013bbc..ee67e14 100644 --- a/SCons/Tool/dvi.xml +++ b/SCons/Tool/dvi.xml @@ -26,7 +26,7 @@ See its __doc__ string for a discussion of the format. -Attaches the &b-DVI; builder to the +Attaches the &b-link-DVI; builder to the construction environment. diff --git a/SCons/Tool/gas.xml b/SCons/Tool/gas.xml index 5a12401..9cdcdb2 100644 --- a/SCons/Tool/gas.xml +++ b/SCons/Tool/gas.xml @@ -27,7 +27,7 @@ See its __doc__ string for a discussion of the format. Sets construction variables for the &gas; assembler. -Calls the &t-as; module. +Calls the &t-link-as; tool. diff --git a/SCons/Tool/gettext.xml b/SCons/Tool/gettext.xml index c7943b2..b184e44 100644 --- a/SCons/Tool/gettext.xml +++ b/SCons/Tool/gettext.xml @@ -59,8 +59,8 @@ so you're encouraged to see their individual documentation. Each of the above tools provides its own builder(s) which may be used to perform particular activities related to software internationalization. You -may be however interested in top-level builder -&b-Translate; described few paragraphs later. +may be however interested in top-level +&b-link-Translate; builder. diff --git a/SCons/Tool/gs.xml b/SCons/Tool/gs.xml index d05ea9f..6baaa15 100644 --- a/SCons/Tool/gs.xml +++ b/SCons/Tool/gs.xml @@ -27,11 +27,11 @@ See its __doc__ string for a discussion of the format. This Tool sets the required construction variables for working with -the Ghostscript command. It also registers an appropriate Action -with the PDF Builder (&b-link-PDF;), such that the conversion from +the Ghostscript software. It also registers an appropriate Action +with the &b-link-PDF; Builder, such that the conversion from PS/EPS to PDF happens automatically for the TeX/LaTeX toolchain. -Finally, it adds an explicit Ghostscript Builder (&b-link-Gs;) to the -environment. +Finally, it adds an explicit &b-link-Gs; Builder for Ghostscript +to the environment. @@ -47,7 +47,7 @@ environment. -The Ghostscript program used, e.g. to convert PostScript to PDF files. +The name of the Ghostscript program used, e.g. to convert PostScript to PDF files. @@ -84,15 +84,18 @@ is -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -A Builder for explicitly calling the gs executable. -Depending on the underlying OS, the different names gs, -gsos2 and gswin32c +A Builder for explicitly calling the gs executable. +Depending on the underlying OS, the different names gs, +gsos2 and gswin32c are tried. -env = Environment(tools=['gs']) -env.Gs('cover.jpg','scons-scons.pdf', - GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q') - ) + +env = Environment(tools=['gs']) +env.Gs( + 'cover.jpg', + 'scons-scons.pdf', + GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q', +) diff --git a/SCons/Tool/hpcc.xml b/SCons/Tool/hpcc.xml index 85ce09e..a413099 100644 --- a/SCons/Tool/hpcc.xml +++ b/SCons/Tool/hpcc.xml @@ -26,9 +26,9 @@ See its __doc__ string for a discussion of the format. -Set construction variables for the -aCC on HP/UX systems. -Calls the &t-cXX; tool for additional variables. +Set construction variables for +aCC compilers on HP/UX systems. +Calls the &t-link-cXX; tool for additional variables. diff --git a/SCons/Tool/intelc.xml b/SCons/Tool/intelc.xml index 49a9296..87958a5 100644 --- a/SCons/Tool/intelc.xml +++ b/SCons/Tool/intelc.xml @@ -28,9 +28,9 @@ See its __doc__ string for a discussion of the format. Sets construction variables for the Intel C/C++ compiler (Linux and Windows, version 7 and later). -Calls the &t-gcc; or &t-msvc; +Calls the &t-link-gcc; or &t-link-msvc; (on Linux and Windows, respectively) -to set underlying variables. +tool to set underlying variables. @@ -48,7 +48,7 @@ to set underlying variables. -Set by the "intelc" Tool +Set by the &t-link-intelc; Tool to the major version number of the Intel C compiler selected for use. diff --git a/SCons/Tool/link.xml b/SCons/Tool/link.xml index f90a33b..210d946 100644 --- a/SCons/Tool/link.xml +++ b/SCons/Tool/link.xml @@ -245,6 +245,16 @@ set. The linker. See also &cv-link-SHLINK; for linking shared objects. + +On POSIX systems (those using the &t-link-link; tool), +you should normally not change this value as it defaults +to a "smart" linker tool which selects a compiler +driver matching the type of source files in use. +So for example, if you set &cv-link-CXX; to a specific +compiler name, and are compiling C++ sources, +the smartlink function will automatically select the same compiler +for linking. + @@ -323,6 +333,16 @@ set. The linker for programs that use shared libraries. See also &cv-link-LINK; for linking static objects. + +On POSIX systems (those using the &t-link-link; tool), +you should normally not change this value as it defaults +to a "smart" linker tool which selects a compiler +driver matching the type of source files in use. +So for example, if you set &cv-link-SHCXX; to a specific +compiler name, and are compiling C++ sources, +the smartlink function will automatically select the same compiler +for linking. + diff --git a/SCons/Tool/packaging/packaging.xml b/SCons/Tool/packaging/packaging.xml index 59eb52f..8516ca5 100644 --- a/SCons/Tool/packaging/packaging.xml +++ b/SCons/Tool/packaging/packaging.xml @@ -41,7 +41,7 @@ command-line option is also enabled. Builds software distribution packages. -A Package is a container format which +A package is a container format which includes files to install along with metadata. Packaging is optional, and must be enabled by specifying the &t-link-packaging; tool. For example: diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 5bd50d3..f641aaf 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -3489,6 +3489,7 @@ but it can be indexed like one to access a env["CC"] = "cc" +flags = env.get("CPPDEFINES", []) &Consvars; can also be retrieved and set @@ -3528,13 +3529,15 @@ env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) A number of useful &consvars; are automatically defined by -scons for each supported platform, and additional &consvars; -can be defined by the user. The following is a list of the possible +scons for each supported platform, and you can modify these +or define any additional &consvars; for your own use, +taking care not to overwrite ones which &SCons; is using. +The following is a list of the possible automatically defined &consvars;. Note the actual list available -at execution time will not include all of these, as the ones +at execution time will never include all of these, as the ones detected as not being useful (wrong platform, necessary external command or files not installed, etc.) will not be set up. Correct build setups should be resilient to the possible @@ -3542,6 +3545,8 @@ absence of certain &consvars; before using them, for example by using a &Python; dictionary get method to retrieve the value and taking alternative action if the return indicates the variable is unset. +The &f-link-env-Dump; method can be called to examine the +&consvars; set in a particular environment. diff --git a/doc/scons.mod b/doc/scons.mod index 006107e..5700454 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -47,7 +47,7 @@ gas"> gcc"> g77"> -gXX"> +g++"> Jam"> jar"> javac"> -- cgit v0.12