From 39f1d3b19cc5724b768577fb2459deb139e0a8dc Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 10:49:26 -0600 Subject: Update manpage Extending section [ci skip] Extending SCons: this is mainly syntax: adding/adjusting markup, reformatting code examples, adding the word "Example:" in a few places, moving a paragraph outside a list since it applies to the whole list, not to the last item of the list. A list is reformatted to a for a shorter layout. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 276 ++++++++++++++++++++++-------------------------------- 1 file changed, 114 insertions(+), 162 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b58e14f..72f8667 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -4005,7 +4005,7 @@ int main(int argc, char **argv) { return ret env = Environment() -conf = Configure(env, custom_tests = {'CheckQt': CheckQt}) +conf = Configure(env, custom_tests={'CheckQt': CheckQt}) if not conf.CheckQt('/usr/lib/qt'): print('We really need qt!') Exit(1) @@ -4989,7 +4989,7 @@ or directory target. MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) env = Environment() -env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) +env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder}) env.MakeDirectory('new_directory', []) @@ -5025,7 +5025,7 @@ or directories (or both) as sources. CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) env = Environment() -env.Append(BUILDERS = {'Collect':CollectBuilder}) +env.Append(BUILDERS={'Collect': CollectBuilder}) env.Collect('archive', ['directory_name', 'file_name']) @@ -5076,14 +5076,14 @@ b = Builder("my_build < $TARGET > $SOURCE", emitter = [e, e2]) # Calling an emitter function through a &consvar;. -env = Environment(MY_EMITTER = e) +env = Environment(MY_EMITTER=e) b = Builder("my_build < $TARGET > $SOURCE", - emitter = '$MY_EMITTER') + emitter='$MY_EMITTER') # Calling a list of emitter functions through a &consvar;. -env = Environment(EMITTER_LIST = [e, e2]) +env = Environment(EMITTER_LIST=[e, e2]) b = Builder("my_build < $TARGET > $SOURCE", - emitter = '$EMITTER_LIST') + emitter='$EMITTER_LIST') # Associating multiple emitters with different file # suffixes using a dictionary. @@ -5092,8 +5092,8 @@ def e_suf1(target, source, env): def e_suf2(target, source, env): return (target, source + ['another_source_file']) b = Builder("my_build < $TARGET > $SOURCE", - emitter = {'.suf1' : e_suf1, - '.suf2' : e_suf2}) + emitter={'.suf1' : e_suf1, + '.suf2' : e_suf2}) @@ -5227,7 +5227,7 @@ and b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, source_ext_match = None) -env = Environment(BUILDERS = {'MyBuild':b}) +env = Environment(BUILDERS={'MyBuild':b}) env.MyBuild('foo.out', ['foo.in', 'foo.extra']) @@ -5247,8 +5247,8 @@ used to call the Builder for the target file.) b = Builder(action="build < $SOURCE > $TARGET") -env = Environment(BUILDERS = {'MyBuild' : b}) -env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') +env = Environment(BUILDERS={'MyBuild' : b}) +env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy') @@ -5300,7 +5300,7 @@ targets and source. b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", chdir=1) -env = Environment(BUILDERS = {'MyBuild' : b}) +env = Environment(BUILDERS={'MyBuild' : b}) env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') @@ -5483,19 +5483,19 @@ or return a non-zero exit status to indicate an unsuccessful build. -def build_it(target = None, source = None, env = None): +def build_it(target=None, source=None, env=None): # build the target from the source return 0 a = Action(build_it) -If the action argument is not one of the above, -None is returned. +If the action argument is not one of the above, +None is returned. The second argument to &f-Action; is optional and is used to define the output @@ -5510,13 +5510,14 @@ The argument must be either a Python function or a string. it's a function that returns a string to be printed to describe the action being executed. The function may also be specified by the -strfunction= +strfunction keyword argument. Like a function to build a file, -this function must accept three keyword arguments: +the strfunction function +must accept three keyword arguments: - source - + source - a Node object representing the source file. target - a Node object representing the target file. @@ -5531,8 +5532,8 @@ arguments may be lists of Node objects if there is more than one target file or source file. In the second case, you provide the string itself. -The string may also be specified by the -cmdstr= +This string may also be specified using the +cmdstr keyword argument. The string typically contains variables, notably $TARGET(S) and $SOURCE(S), @@ -5566,8 +5567,8 @@ l = Action(build_it, '$STRINGIT') may either be a &consvar; or a list of &consvars; whose values will be included in the signature of the Action when deciding whether a target should be rebuilt because the action changed. -The variables may also be specified by a -varlist= +The variables may also be specified using the +varlist keyword parameter; if both are present, they are combined. This is necessary whenever you want a target to be rebuilt @@ -5580,7 +5581,8 @@ the value of a &consvar; when generating the command line. def build_it(target, source, env): # build the target from the 'XXX' construction variable - open(target[0], 'w').write(env['XXX']) + with open(target[0], 'w') as f: + f.write(env['XXX']) return 0 # Use positional arguments. @@ -5638,7 +5640,7 @@ expansions like and ${SOURCE.file} to use just the filename portion of the -targets and source. +targets and source. Example: a = Action("build < ${SOURCE.file} > ${TARGET.file}", @@ -5661,7 +5663,7 @@ to specify that an Action object's return value should be ignored under special conditions and SCons should, therefore, -consider that the action always suceeds: +consider that the action always suceeds. Example: def always_succeed(s): @@ -5696,9 +5698,8 @@ Command lines will typically want to use the &cv-CHANGED_SOURCES; &consvar; (and possibly &cv-CHANGED_TARGETS; as well) to only pass to the command line those sources that -have actually changed since their targets were built. - -Example: +have actually changed since their targets were built. +Example: a = Action('build $CHANGED_SOURCES', batch_key=True) @@ -5829,12 +5830,17 @@ external commands: -env = Environment(TMPBUILD = '/tmp/builddir') -env.Command('foo.out', 'foo.in', - [Mkdir('$TMPBUILD'), - Copy('$TMPBUILD', '${SOURCE.dir}'), - "cd $TMPBUILD && make", - Delete('$TMPBUILD')]) +env = Environment(TMPBUILD='/tmp/builddir') +env.Command( + target='foo.out', + source='foo.in', + action=[ + Mkdir('$TMPBUILD'), + Copy('$TMPBUILD', '${SOURCE.dir}'), + "cd $TMPBUILD && make", + Delete('$TMPBUILD'), + ], +) @@ -5977,7 +5983,7 @@ Examples: Execute(Touch('file_to_be_touched')) -env.Command('marker', 'input_file', +env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')]) @@ -5994,7 +6000,7 @@ env.Command('marker', 'input_file', performs &consvar; substitution on the string that makes up the command line of the builder. &Consvars; to be interpolated are indicated in the -string with a leading +string with a leading $, to distinguish them from plain text which is not to be substituted. Besides regular &consvars;, scons provides the following @@ -6110,117 +6116,58 @@ have the following modifiers appended within the enclosing curly braces to access properties of the interpolated string: - - - base - -The base path of the file name, -including the directory path -but excluding any suffix. - - - - - dir - -The name of the directory in which the file exists. - - - - - file - -The file name, -minus any directory portion. - - - - - filebase - -Like file -but minus its suffix.. - - - - - suffix - -Just the file suffix. - - - - - abspath - -The absolute path name of the file. - - - - - posix - -The path with directories separated by forward slashes -(/). -Sometimes necessary on Windows systems -when a path references a file on other (POSIX) systems. - - - - - windows - -The path with directories separated by backslashes. -(\\). -Sometimes necessary on POSIX-style systems -when a path references a file on other (Windows) systems. -win32 is a (deprecated) synonym for -windows. - - - - - srcpath - -The directory and file name to the source file linked to this file through -VariantDir(). -If this file isn't linked, -it just returns the directory and filename unchanged. - - - - - srcdir - -The directory containing the source file linked to this file through -VariantDir(). -If this file isn't linked, -it just returns the directory part of the filename. - - - - - rsrcpath - -The directory and file name to the source file linked to this file through -VariantDir(). -If the file does not exist locally but exists in a Repository, -the path in the Repository is returned. -If this file isn't linked, it just returns the -directory and filename unchanged. - - - - - rsrcdir - -The Repository directory containing the source file linked to this file through -VariantDir(). -If this file isn't linked, -it just returns the directory part of the filename. - - - + + base - + The base path of the file name, + including the directory path + but excluding any suffix. + + dir - The name of the directory in which the file exists. + file - The file name, minus any directory portion. + filebase - Like file but minus its suffix. + suffix - Just the file suffix. + abspath - The absolute path name of the file. + posix - + The path with directories separated by forward slashes + (/). + Sometimes necessary on Windows systems + when a path references a file on other (POSIX) systems. + + windows - + The path with directories separated by backslashes + (\\). + Sometimes necessary on POSIX-style systems + when a path references a file on other (Windows) systems. + win32 is a (deprecated) synonym for + windows. + + srcpath - + The directory and file name to the source file linked to this file through + &f-VariantDir;(). + If this file isn't linked, + it just returns the directory and filename unchanged. + + srcdir - + The directory containing the source file linked to this file through + &f-VariantDir;(). + If this file isn't linked, + it just returns the directory part of the filename. + + rsrcpath - + The directory and file name to the source file linked to this file through + &f-VariantDir;(). + If the file does not exist locally but exists in a Repository, + the path in the Repository is returned. + If this file isn't linked, it just returns the + directory and filename unchanged. + + rsrcdir - + The Repository directory containing the source file linked to this file through + &VariantDir;(). + If this file isn't linked, + it just returns the directory part of the filename. + + For example, the specified target will expand as follows for the corresponding modifiers: @@ -6701,19 +6648,19 @@ issues waiting to trap the unwary. .C file suffix &scons; handles the upper-case -.C +.C file suffix differently, depending on the capabilities of the underlying system. On a case-sensitive system such as Linux or UNIX, &scons; treats a file with a -.C +.C suffix as a C++ source file. On a case-insensitive system such as Windows, &scons; treats a file with a -.C +.C suffix as a C source file. @@ -6721,21 +6668,21 @@ suffix as a C source file. .F file suffix &scons; handles the upper-case -.F +.F file suffix differently, depending on the capabilities of the underlying system. On a case-sensitive system such as Linux or UNIX, &scons; treats a file with a -.F +.F suffix as a Fortran source file that is to be first run through the standard C preprocessor. On a case-insensitive system such as Windows, &scons; treats a file with a -.F +.F suffix as a Fortran source file that should not be run through the C preprocessor. @@ -6782,11 +6729,11 @@ to run &scons;. -Windows: scons.bat file +Windows: <filename>scons.bat</filename> file On Windows systems, &scons; is executed via a wrapper -scons.bat +scons.bat file. This has (at least) two ramifications: @@ -6806,23 +6753,26 @@ as an &scons; command issued at the command-line prompt. You can work around this either by executing -scons.bat +scons.bat from the Cygwin command line, or by creating a wrapper shell script named -scons. +scons. MinGW -The MinGW bin directory must be in your PATH environment variable or the -PATH variable under the ENV &consvar; for &scons; +The MinGW bin +directory must be in your PATH +environment variable or the +ENV['PATH'] &consvar; for &scons; to detect and use the MinGW tools. When running under the native Windows Python interpreter, &scons; will prefer the MinGW tools over the Cygwin tools, if they are both installed, regardless of the order of the bin -directories in the PATH variable. If you have both MSVC and MinGW +directories in the PATH variable. +If you have both MSVC and MinGW installed and you want to use MinGW instead of MSVC, then you must explicitly tell &scons; to use MinGW by passing tools=['mingw'] @@ -6836,7 +6786,9 @@ over the MinGW tools. EXAMPLES To help you get started using &scons;, -this section contains a brief overview of some common tasks. +this section contains a brief overview of some common tasks. +See the &SCons; User Guide for many more examples. + -- cgit v0.12 From e1b67497b7af73f39af4854c841fd6e84f1bf237 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 11:40:35 -0600 Subject: [PR #3676] fix doc typo detected by sider [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 72f8667..6f526c0 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -5663,12 +5663,13 @@ to specify that an Action object's return value should be ignored under special conditions and SCons should, therefore, -consider that the action always suceeds. Example: +consider that the action always succeeds. Example: def always_succeed(s): # Always return 0, which indicates success. return 0 + a = Action("build < ${SOURCE.file} > ${TARGET.file}", exitstatfunc=always_succeed) -- cgit v0.12