From a0d0c531358297245fdaefdc130ce8e0ab569e9b Mon Sep 17 00:00:00 2001 From: William Deegan Date: Tue, 23 Jun 2020 12:22:50 -0700 Subject: [appveyor skip] fix ulink vs link xml syntax --- .travis.yml | 2 +- doc/generated/builders.gen | 289 ++++++++++++++++++++++---------------------- doc/generated/tools.gen | 2 +- doc/generated/variables.gen | 54 ++++----- doc/man/scons.xml | 8 +- 5 files changed, 180 insertions(+), 175 deletions(-) diff --git a/.travis.yml b/.travis.yml index 48ceca9..5bf5784 100644 --- a/.travis.yml +++ b/.travis.yml @@ -86,7 +86,7 @@ jobs: - python bin/docs-update-generated.py - python bin/docs-validate.py - python bin/docs-create-example-outputs.py - - python script/scons.py + - python scripts/scons.py - python setup.py bdist_wheel - python setup.py sdist --formats=gztar,zip - ls -l build/dist diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index 77f9bfb..94c8eff 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -18,7 +18,7 @@ Builds a C source file given a lex (.l) or yacc (.y) input file. -The suffix specified by the &cv-link-CFILESUFFIX; construction variable +The suffix specified by the &cv-link-CFILESUFFIX; &consvar; (.c by default) is automatically added to the target if it is not already present. @@ -90,7 +90,7 @@ env.CompilationDatabase('my_output.json') Builds a C++ source file given a lex (.ll) or yacc (.yy) input file. -The suffix specified by the &cv-link-CXXFILESUFFIX; construction variable +The suffix specified by the &cv-link-CXXFILESUFFIX; &consvar; (.cc by default) is automatically added to the target if it is not already present. @@ -1737,18 +1737,19 @@ builder method; see that builder method's description for a list of legal source file suffixes and how they are interpreted. -The target executable file prefix -(specified by the &cv-link-PROGPREFIX; construction variable; nothing by default) -and suffix -(specified by the &cv-link-PROGSUFFIX; construction variable; -by default, .exe on Windows systems, -nothing on POSIX systems) +The target executable file prefix, +specified by the &cv-link-PROGPREFIX; &consvar; +(nothing by default), +and suffix, +specified by the &cv-link-PROGSUFFIX; &consvar; +(by default, .exe on Windows systems, +nothing on POSIX systems), are automatically added to the target if not already present. Example: -env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) +env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f']) @@ -1925,30 +1926,28 @@ or C, C++, D or Fortran source files. If any source files are given, then they will be automatically compiled to object files. -The static library prefix and suffix (if any) -are automatically added to the target. -The target library file prefix -(specified by the &cv-link-SHLIBPREFIX; construction variable; -by default, lib on POSIX systems, -nothing on Windows systems) -and suffix -(specified by the &cv-link-SHLIBSUFFIX; construction variable; -by default, .dll on Windows systems, -.so on POSIX systems) +The target library file prefix, +specified by the &cv-link-SHLIBPREFIX; &consvar; +(by default, lib on POSIX systems, +nothing on Windows systems), +and suffix, +specified by the &cv-link-SHLIBSUFFIX; &consvar; +(by default, .dll on Windows systems, +.so on POSIX systems), are automatically added to the target if not already present. Example: -env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +env.SharedLibrary(target='bar', source=['bar.c', 'foo.o']) On Windows systems, the &b-SharedLibrary; -builder method will always build an import -(.lib) library -in addition to the shared (.dll) library, +builder method will always build an import library +(.lib) +in addition to the shared library (.dll), adding a .lib library with the same basename if there is not already a .lib file explicitly listed in the targets. @@ -1957,9 +1956,9 @@ listed in the targets. On Cygwin systems, the &b-SharedLibrary; -builder method will always build an import -(.dll.a) library -in addition to the shared (.dll) library, +builder method will always build an import library +(.dll.a) +in addition to the shared library (.dll), adding a .dll.a library with the same basename if there is not already a .dll.a file explicitly listed in the targets. @@ -1967,7 +1966,7 @@ listed in the targets. Any object files listed in the -source +source must have been built for a shared library (that is, using the &b-SharedObject; @@ -1980,37 +1979,37 @@ will raise an error if there is any mismatch. On some platforms, there is a distinction between a shared library (loaded automatically by the system to resolve external references) and a loadable module (explicitly loaded by user action). -For maximum portability, use the &b-LoadableModule; builder for the latter. +For maximum portability, use the &b-link-LoadableModule; builder for the latter. -When the &cv-link-SHLIBVERSION; construction variable is defined a versioned -shared library is created. This modifies the &cv-link-SHLINKFLAGS; as required, -adds the version number to the library name, and creates the symlinks that -are needed. +When the &cv-link-SHLIBVERSION; &consvar; is defined, a versioned +shared library is created. This modifies &cv-link-SHLINKFLAGS; as required, +adds the version number to the library name, and creates any +symbolic links that are needed. -env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'], SHLIBVERSION='1.5.2') +env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2') On a POSIX system, versions with a single token create exactly one symlink: -libbar.so.6 would have symlinks libbar.so only. +libbar.so.6 would have symlink libbar.so only. On a POSIX system, versions with two or more -tokens create exactly two symlinks: libbar.so.2.3.1 would have symlinks -libbar.so and libbar.so.2; on a Darwin (OSX) system the library would be -libbar.2.3.1.dylib and the link would be libbar.dylib. +tokens create exactly two symlinks: libbar.so.2.3.1 would have symlinks +libbar.so and libbar.so.2; on a Darwin (OSX) system the library would be +libbar.2.3.1.dylib and the link would be libbar.dylib. On Windows systems, specifying -register=1 +register=1 will cause the .dll to be -registered after it is built using REGSVR32. -The command that is run -("regsvr32" by default) is determined by &cv-link-REGSVR; construction -variable, and the flags passed are determined by &cv-link-REGSVRFLAGS;. By +registered after it is built. +The command that is run is determined by the &cv-link-REGSVR; &consvar; +(regsvr32 by default), +and the flags passed are determined by &cv-link-REGSVRFLAGS;. By default, &cv-link-REGSVRFLAGS; includes the option, to prevent dialogs from popping up and requiring user attention when it is run. If you change @@ -2019,9 +2018,7 @@ For example, -env.SharedLibrary(target = 'bar', - source = ['bar.cxx', 'foo.obj'], - register=1) +env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1) @@ -2034,7 +2031,7 @@ when it is done linking it. SharedObject() env.SharedObject() -Builds an object file for +Builds an object file intended for inclusion in a shared library. Source files must have one of the same set of extensions specified above for the @@ -2042,7 +2039,7 @@ specified above for the builder method. On some platforms building a shared object requires additional compiler option -(e.g. for gcc) +(e.g. for gcc) in addition to those needed to build a normal (static) object, but on some platforms there is no difference between a shared object and a normal (static) one. When there is a difference, SCons @@ -2052,25 +2049,25 @@ difference, SCons will allow both normal (static) and shared objects to be linked into a shared library, and will use the same suffix for shared and normal (static) objects. -The target object file prefix -(specified by the &cv-link-SHOBJPREFIX; construction variable; -by default, the same as &cv-link-OBJPREFIX;) -and suffix -(specified by the &cv-link-SHOBJSUFFIX; construction variable) +The target object file prefix, +specified by the &cv-link-SHOBJPREFIX; &consvar; +(by default, the same as &cv-link-OBJPREFIX;), +and suffix, +specified by the &cv-link-SHOBJSUFFIX; &consvar;, are automatically added to the target if not already present. Examples: -env.SharedObject(target = 'ddd', source = 'ddd.c') -env.SharedObject(target = 'eee.o', source = 'eee.cpp') -env.SharedObject(target = 'fff.obj', source = 'fff.for') +env.SharedObject(target='ddd', source='ddd.c') +env.SharedObject(target='eee.o', source='eee.cpp') +env.SharedObject(target='fff.obj', source='fff.for') Note that the source files will be scanned according to the suffix mappings in the -SourceFileScanner +SourceFileScanner object. See the section "Scanner Objects," below, for more information. @@ -2086,27 +2083,25 @@ or C, C++, D or Fortran source files. If any source files are given, then they will be automatically compiled to object files. -The static library prefix and suffix (if any) -are automatically added to the target. -The target library file prefix -(specified by the &cv-link-LIBPREFIX; construction variable; -by default, lib on POSIX systems, -nothing on Windows systems) -and suffix -(specified by the &cv-link-LIBSUFFIX; construction variable; -by default, .lib on Windows systems, -.a on POSIX systems) +The static library file prefix, +specified by the &cv-link-LIBPREFIX; &consvar; +(by default, lib on POSIX systems, +nothing on Windows systems), +and suffix, +specified by the &cv-link-LIBSUFFIX; &consvar; +(by default, .lib on Windows systems, +.a on POSIX systems), are automatically added to the target if not already present. Example: -env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +env.StaticLibrary(target='bar', source=['bar.c', 'foo.o']) Any object files listed in the -source +source must have been built for a static library (that is, using the &b-StaticObject; @@ -2157,26 +2152,27 @@ Source files must have one of the following extensions: -The target object file prefix -(specified by the &cv-link-OBJPREFIX; construction variable; nothing by default) -and suffix -(specified by the &cv-link-OBJSUFFIX; construction variable; -.obj on Windows systems, -.o on POSIX systems) +The target object file prefix, +specified by the &cv-link-OBJPREFIX; &consvar; +(nothing by default), +and suffix, +specified by the &cv-link-OBJSUFFIX; &consvar; +(.obj on Windows systems, +.o on POSIX systems), are automatically added to the target if not already present. Examples: -env.StaticObject(target = 'aaa', source = 'aaa.c') -env.StaticObject(target = 'bbb.o', source = 'bbb.c++') -env.StaticObject(target = 'ccc.obj', source = 'ccc.f') +env.StaticObject(target='aaa', source='aaa.c') +env.StaticObject(target='bbb.o', source='bbb.c++') +env.StaticObject(target='ccc.obj', source='ccc.f') Note that the source files will be scanned -according to the suffix mappings in -SourceFileScanner +according to the suffix mappings in the +SourceFileScanner object. See the section "Scanner Objects," below, for more information. @@ -2187,28 +2183,35 @@ below, for more information. Substfile() env.Substfile() -The &b-Substfile; builder creates a single text file from another file or set of -files by concatenating them with &cv-LINESEPARATOR; and replacing text -using the &cv-SUBST_DICT; construction variable. Nested lists of source files -are flattened. See also &b-Textfile;. +The &b-Substfile; builder creates a single text file from +a template consisting of a file or set of files (or nodes), +replacing text using the &cv-link-SUBST_DICT; &consvar; (if set). +If a set, they are concatenated into the target file +using the value of the +&cv-link-LINESEPARATOR; &consvar; as a separator between contents; +the separator is not emitted after the contents of the last file. +Nested lists of source files +are flattened. See also &b-link-Textfile;. -If a single source file is present with an .in suffix, -the suffix is stripped and the remainder is used as the default target name. +If a single source file name is specified and has a .in suffix, +the suffix is stripped and the remainder of the name is used as the default target name. -The prefix and suffix specified by the &cv-SUBSTFILEPREFIX; -and &cv-SUBSTFILESUFFIX; construction variables +The prefix and suffix specified by the &cv-link-SUBSTFILEPREFIX; +and &cv-link-SUBSTFILESUFFIX; &consvars; (an empty string by default in both cases) are automatically added to the target if they are not already present. -If a construction variable named &cv-SUBST_DICT; is present, -it may be either a Python dictionary or a sequence of (key,value) tuples. -If it is a dictionary it is converted into a list of tuples in an arbitrary order, +If a construction variable named &cv-link-SUBST_DICT; is present, +it may be either a Python dictionary or a sequence of +(key, value) tuples. +If it is a dictionary it is converted into a list of tuples +with unspecified order, so if one key is a prefix of another key or if one substitution could be further expanded by another subsitition, it is unpredictable whether the expansion will occur. @@ -2228,42 +2231,40 @@ env = Environment(tools=['default']) env['prefix'] = '/usr/bin' script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'} -env.Substfile('script.in', SUBST_DICT = script_dict) +env.Substfile('script.in', SUBST_DICT=script_dict) conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'} -env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict) +env.Substfile('config.h.in', conf_dict, SUBST_DICT=conf_dict) # UNPREDICTABLE - one key is a prefix of another bad_foo = {'$foo': '$foo', '$foobar': '$foobar'} -env.Substfile('foo.in', SUBST_DICT = bad_foo) +env.Substfile('foo.in', SUBST_DICT=bad_foo) # PREDICTABLE - keys are applied longest first good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')] -env.Substfile('foo.in', SUBST_DICT = good_foo) +env.Substfile('foo.in', SUBST_DICT=good_foo) # UNPREDICTABLE - one substitution could be futher expanded bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'} -env.Substfile('bar.in', SUBST_DICT = bad_bar) +env.Substfile('bar.in', SUBST_DICT=bad_bar) # PREDICTABLE - substitutions are expanded in order good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye')) -env.Substfile('bar.in', SUBST_DICT = good_bar) +env.Substfile('bar.in', SUBST_DICT=good_bar) # the SUBST_DICT may be in common (and not an override) substutions = {} subst = Environment(tools=['textfile'], SUBST_DICT=substitutions) substitutions['@foo@'] = 'foo' subst['SUBST_DICT']['@bar@'] = 'bar' -subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'), - Value('#include "@bar@.h"'), - "common.in", - "pgm1.in" - ]) -subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), - Value('#include "@bar@.h"'), - "common.in", - "pgm2.in" - ]) +subst.Substfile( + 'pgm1.c', + [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in"], +) +subst.Substfile( + 'pgm2.c', + [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in"], +) @@ -2313,66 +2314,70 @@ env.Tar('foo') Textfile() env.Textfile() -The &b-Textfile; builder generates a single text file. -The source strings constitute the lines; -nested lists of sources are flattened. -&cv-LINESEPARATOR; is used to separate the strings. - - - -If present, the &cv-SUBST_DICT; construction variable -is used to modify the strings before they are written; -see the &b-Substfile; description for details. - - - -The prefix and suffix specified by the &cv-TEXTFILEPREFIX; -and &cv-TEXTFILESUFFIX; construction variables -(an empty string and .txt by default, respectively) +The &b-Textfile; builder generates a single text file from +a template consisting of a list of strings, replacing text +using the &cv-link-SUBST_DICT; &consvar; (if set) - +see &b-link-Substfile; for a description of replacement. +The strings will be separated in the target file using the +value of the +&cv-link-LINESEPARATOR; &consvar;; +the line separator is not emitted after the last string. +Nested lists of source strings +are flattened. +Source strings need not literally be Python strings: +they can be Nodes or Python objects that convert cleanly +to &f-link-Value; nodes + + + +The prefix and suffix specified by the &cv-link-TEXTFILEPREFIX; +and &cv-link-TEXTFILESUFFIX; &consvars; +(by default an empty string and .txt, respectively) are automatically added to the target if they are not already present. Examples: # builds/writes foo.txt -env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller']) +env.Textfile(target='foo.txt', source=['Goethe', 42, 'Schiller']) # builds/writes bar.txt -env.Textfile(target = 'bar', - source = ['lalala', 'tanteratei'], - LINESEPARATOR='|*') +env.Textfile(target='bar', source=['lalala', 'tanteratei'], LINESEPARATOR='|*') # nested lists are flattened automatically -env.Textfile(target = 'blob', - source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei']) +env.Textfile(target='blob', source=['lalala', ['Goethe', 42, 'Schiller'], 'tanteratei']) # files may be used as input by wraping them in File() -env.Textfile(target = 'concat', # concatenate files with a marker between - source = [File('concat1'), File('concat2')], - LINESEPARATOR = '====================\n') +env.Textfile( + target='concat', # concatenate files with a marker between + source=[File('concat1'), File('concat2')], + LINESEPARATOR='====================\n', +) + -Results are: -foo.txt - ....8<---- +Results: + +foo.txt + Goethe 42 Schiller - ....8<---- (no linefeed at the end) + -bar.txt: - ....8<---- +bar.txt + lalala|*tanteratei - ....8<---- (no linefeed at the end) + -blob.txt - ....8<---- +blob.txt + lalala Goethe 42 Schiller tanteratei - ....8<---- (no linefeed at the end) - + + diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen index 794b553..6353c6f 100644 --- a/doc/generated/tools.gen +++ b/doc/generated/tools.gen @@ -964,7 +964,7 @@ Sets construction variables for the TeX formatter and typesetter. textfile -Set construction variables for the &b-Textfile; and &b-Substfile; builders. +Set &consvars; for the &b-Textfile; and &b-Substfile; builders. Sets: &cv-link-LINESEPARATOR;, &cv-link-SUBSTFILEPREFIX;, &cv-link-SUBSTFILESUFFIX;, &cv-link-TEXTFILEPREFIX;, &cv-link-TEXTFILESUFFIX;.Uses: &cv-link-SUBST_DICT;. diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index 6f23d98..e100939 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -1361,7 +1361,7 @@ PDF renderer fop or xep. The path to the external executable xmllint, if it's installed. Note, that this is only used as last fallback for resolving -XIncludes, if no libxml2 or lxml Python binding can be imported +XIncludes, if no lxml Python binding can be imported in the current system. @@ -1405,7 +1405,7 @@ The path to the external executable xsltproc (or saxon, xalan), if one of them is installed. Note, that this is only used as last fallback for XSL transformations, if -no libxml2 or lxml Python binding can be imported in the current system. +no lxml Python binding can be imported in the current system. @@ -3038,6 +3038,14 @@ is -dNOPAUSE -dBATCH -sDEVICE=pdfwrite HOST_ARCH + The name of the host hardware architecture used to create the Environment. + If a platform is specified when creating the Environment, then + that Platform's logic will handle setting this value. + This value is immutable, and should not be changed by the user after + the Environment is initialized. + Currently only set for Win32. + + Sets the host architecture for Visual Studio compiler. If not set, default to the detected host architecture: note that this may depend on the python you are using. @@ -3053,15 +3061,7 @@ Valid values are the same as for &cv-TARGET_ARCH;. This is currently only used on Windows, but in the future it will be used on other OSes as well. - - The name of the host hardware architecture used to create the Environment. - If a platform is specified when creating the Environment, then - that Platform's logic will handle setting this value. - This value is immutable, and should not be changed by the user after - the Environment is initialized. - Currently only set for Win32. - - + @@ -3810,7 +3810,7 @@ the same as $SHLIBSUFFIX. LDMODULEVERSION -When this construction variable is defined, a versioned loadable module +When this &consvar; is defined, a versioned loadable module is created by &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 @@ -4165,7 +4165,7 @@ for a list of license names and SPDX codes. LINESEPARATOR -The separator used by the &b-Substfile; and &b-Textfile; builders. +The separator used by the &b-link-Substfile; and &b-link-Textfile; builders. This value is used between sources when constructing the target. It defaults to the current system line separator. @@ -7111,7 +7111,7 @@ The suffix used for shared library file names. SHLIBVERSION -When this construction variable is defined, a versioned shared library +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 @@ -7320,9 +7320,9 @@ in which the command should be executed. SUBST_DICT -The dictionary used by the &b-Substfile; or &b-Textfile; builders +The dictionary used by the &b-link-Substfile; or &b-link-Textfile; builders for substitution values. -It can be anything acceptable to the dict() constructor, +It can be anything acceptable to the dict() constructor, so in addition to a dictionary, lists of tuples are also acceptable. @@ -7333,7 +7333,7 @@ lists of tuples are also acceptable. SUBSTFILEPREFIX -The prefix used for &b-Substfile; file names, +The prefix used for &b-link-Substfile; file names, an empty string by default. @@ -7343,7 +7343,7 @@ an empty string by default. SUBSTFILESUFFIX -The suffix used for &b-Substfile; file names, +The suffix used for &b-link-Substfile; file names, an empty string by default. @@ -7651,6 +7651,12 @@ for more information). TARGET_ARCH + The name of the target hardware architecture for the compiled objects + created by this Environment. + This defaults to the value of HOST_ARCH, and the user can override it. + Currently only set for Win32. + + Sets the target architecture for Visual Studio compiler (i.e. the arch of the binaries generated by the compiler). If not set, default to &cv-HOST_ARCH;, or, if that is unset, to the architecture of the @@ -7681,13 +7687,7 @@ and ia64 (Itanium). For example, if you want to compile 64-bit binaries, you would set TARGET_ARCH='x86_64' in your SCons environment. - - The name of the target hardware architecture for the compiled objects - created by this Environment. - This defaults to the value of HOST_ARCH, and the user can override it. - Currently only set for Win32. - - + @@ -7823,7 +7823,7 @@ directories for \include and \import files. TEXTFILEPREFIX -The prefix used for &b-Textfile; file names, +The prefix used for &b-link-Textfile; file names, an empty string by default. @@ -7833,7 +7833,7 @@ an empty string by default. TEXTFILESUFFIX -The suffix used for &b-Textfile; file names; +The suffix used for &b-link-Textfile; file names; .txt by default. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 18e4321..70a1731 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -7447,22 +7447,22 @@ and will silently revert to non-cached behavior in such cases. The SCons User Guide at - + The SCons Design Document (old) The SCons Cookbook at - + for examples of how to solve various problems with &SCons;. SCons source code - + on GitHub The SCons API Reference - + (for internal details) -- cgit v0.12