From 834ed27f71b1a555a6354ba107e2b024c8208555 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 22 Jun 2020 10:41:19 -0600 Subject: Tool doc updates: textfile, lib/object [ci skip] Get more descriptive for Textfile/Substfile, which have a few more subtleties than the docs let on, e.g. input "strings" to textfile can also be nodes. Some formatting changes for the library and object builders in Tool/__init__.xml. Signed-off-by: Mats Wichmann --- SCons/Tool/__init__.xml | 158 +++++++++++++++++++++++------------------------- SCons/Tool/textfile.xml | 145 +++++++++++++++++++++++--------------------- 2 files changed, 154 insertions(+), 149 deletions(-) diff --git a/SCons/Tool/__init__.xml b/SCons/Tool/__init__.xml index 5461d41..b9aeb0d 100644 --- a/SCons/Tool/__init__.xml +++ b/SCons/Tool/__init__.xml @@ -28,7 +28,7 @@ See its __doc__ string for a discussion of the format. 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. @@ -50,7 +50,7 @@ env.CFile(target = 'bar', source = 'bar.y') 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. @@ -111,18 +111,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']) @@ -138,30 +139,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. @@ -170,9 +169,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. @@ -180,7 +179,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; @@ -193,37 +192,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 @@ -232,9 +231,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) @@ -247,7 +244,7 @@ when it is done linking it. -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 @@ -255,7 +252,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 @@ -265,25 +262,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. @@ -299,27 +296,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; @@ -370,26 +365,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. @@ -487,7 +483,7 @@ general information on specifying emitters. -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 @@ -533,7 +529,7 @@ general information on specifying emitters. -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 diff --git a/SCons/Tool/textfile.xml b/SCons/Tool/textfile.xml index 962d966..f2e8bb8 100644 --- a/SCons/Tool/textfile.xml +++ b/SCons/Tool/textfile.xml @@ -26,7 +26,7 @@ See its __doc__ string for a discussion of the format. -Set construction variables for the &b-Textfile; and &b-Substfile; builders. +Set &consvars; for the &b-Textfile; and &b-Substfile; builders. @@ -44,94 +44,105 @@ Set construction variables for the &b-Textfile; and &b-Substfile; builders. -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. +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 -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 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) - + + -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. @@ -151,42 +162,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"], +) @@ -195,7 +204,7 @@ subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), -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. @@ -205,9 +214,9 @@ It defaults to the current system line separator. -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. @@ -217,7 +226,7 @@ lists of tuples are also acceptable. -The prefix used for &b-Substfile; file names, +The prefix used for &b-link-Substfile; file names, an empty string by default. @@ -226,7 +235,7 @@ an empty string by default. -The suffix used for &b-Substfile; file names, +The suffix used for &b-link-Substfile; file names, an empty string by default. @@ -235,7 +244,7 @@ an empty string by default. -The prefix used for &b-Textfile; file names, +The prefix used for &b-link-Textfile; file names, an empty string by default. @@ -244,7 +253,7 @@ an empty string by default. -The suffix used for &b-Textfile; file names; +The suffix used for &b-link-Textfile; file names; .txt by default. -- cgit v0.12