From 5608c66d57570ed462e1dc7a263b34d6b1917871 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 10:58:28 -0600 Subject: Update manpage Examples section [ci skip] Examples: mainly syntax: adding/adjusting markup, reformatting code examples, etc. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 218 +++++++++++++++++++++++++++++------------------------- 1 file changed, 119 insertions(+), 99 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b58e14f..1b400f9 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -6836,7 +6836,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. + @@ -6844,13 +6846,14 @@ this section contains a brief overview of some common tasks. env = Environment() -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') Note: Build the file by specifying the target as an argument -("scons foo" or "scons foo.exe"). -or by specifying a dot ("scons ."). +(scons foo or scons foo.exe) +or by specifying the current directory as the target +(scons .). @@ -6859,7 +6862,7 @@ or by specifying a dot ("scons ."). env = Environment() -env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) +env.Program(target='foo', source=Split('f1.c f2.c f3.c')) @@ -6868,8 +6871,8 @@ env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) Setting a Compilation Flag -env = Environment(CCFLAGS = '-g') -env.Program(target = 'foo', source = 'foo.c') +env = Environment(CCFLAGS='-g') +env.Program(target='foo', source='foo.c') @@ -6879,12 +6882,14 @@ env.Program(target = 'foo', source = 'foo.c') Note: You do not -need to set CCFLAGS to specify -I options by hand. -&scons; will construct the right options from CPPPATH. +need to set CCFLAGS to specify + options by hand. +&scons; will construct the right +options from the contents of CPPPATH. -env = Environment(CPPPATH = ['.']) -env.Program(target = 'foo', source = 'foo.c') +env = Environment(CPPPATH=['.']) +env.Program(target='foo', source='foo.c') @@ -6893,8 +6898,8 @@ env.Program(target = 'foo', source = 'foo.c') Search Multiple Directories For .h Files -env = Environment(CPPPATH = ['include1', 'include2']) -env.Program(target = 'foo', source = 'foo.c') +env = Environment(CPPPATH=['include1', 'include2']) +env.Program(target='foo', source='foo.c') @@ -6904,8 +6909,8 @@ env.Program(target = 'foo', source = 'foo.c') env = Environment() -env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) -env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) +env.StaticLibrary(target='foo', source=Split('l1.c l2.c')) +env.StaticLibrary(target='bar', source=['l3.c', 'l4.c']) @@ -6915,8 +6920,8 @@ env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) env = Environment() -env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) -env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) +env.SharedLibrary(target='foo', source=['l5.c', 'l6.c']) +env.SharedLibrary(target='bar', source=Split('l7.c l8.c')) @@ -6925,9 +6930,9 @@ env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) Linking a Local Library Into a Program -env = Environment(LIBS = 'mylib', LIBPATH = ['.']) -env.Library(target = 'mylib', source = Split('l1.c l2.c')) -env.Program(target = 'prog', source = ['p1.c', 'p2.c']) +env = Environment(LIBS='mylib', LIBPATH=['.']) +env.Library(target='mylib', source=Split('l1.c l2.c')) +env.Program(target='prog', source=['p1.c', 'p2.c']) @@ -6940,23 +6945,24 @@ you can leave off the target file suffix, and &scons; will add it automatically. -bld = Builder(action = 'pdftex < $SOURCES > $TARGET' - suffix = '.pdf', - src_suffix = '.tex') -env = Environment(BUILDERS = {'PDFBuilder' : bld}) -env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') +bld = Builder( + action='pdftex < $SOURCES > $TARGET', + suffix='.pdf', + src_suffix='.tex' +) +env = Environment(BUILDERS={'PDFBuilder': bld}) +env.PDFBuilder(target='foo.pdf', source='foo.tex') # The following creates "bar.pdf" from "bar.tex" -env.PDFBuilder(target = 'bar', source = 'bar') +env.PDFBuilder(target='bar', source='bar') -Note also that the above initialization -overwrites the default Builder objects, -so the Environment created above -can not be used call Builders like -env.Program, -env.Object, -env.StaticLibrary etc. +Note that the above initialization +replaces the default dictionary of Builders, +so this &consenv; can not be used call Builders like +&b-link-Program;, &b-link-Object;, &b-link-StaticLibrary; etc. +See the next example for an alternative. + @@ -6964,13 +6970,15 @@ can not be used call Builders like Adding Your Own Builder Object to an Environment -bld = Builder(action = 'pdftex < $SOURCES > $TARGET' - suffix = '.pdf', - src_suffix = '.tex') +bld = Builder( + action='pdftex < $SOURCES > $TARGET' + suffix='.pdf', + src_suffix='.tex' +) env = Environment() -env.Append(BUILDERS = {'PDFBuilder' : bld}) -env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') -env.Program(target = 'bar', source = 'bar.c') +env.Append(BUILDERS={'PDFBuilder': bld}) +env.PDFBuilder(target='foo.pdf', source='foo.tex') +env.Program(target='bar', source='bar.c') You also can use other Pythonic techniques to add @@ -6986,13 +6994,12 @@ env['BUILDERS]['PDFBuilder'] = bld Defining Your Own Scanner Object -The following example shows adding an extremely simple scanner (the -kfile_scan() -function) +The following example shows adding an extremely simple scanner +(kfile_scan) that doesn't use a search path at all and simply returns the file names present on any -include +include lines in the scanned file. This would implicitly assume that all included files live in the top-level directory: @@ -7007,10 +7014,12 @@ def kfile_scan(node, env, path, arg): includes = include_re.findall(contents) return env.File(includes) -kscan = Scanner(name = 'kfile', - function = kfile_scan, - argument = None, - skeys = ['.k']) +kscan = Scanner( + name='kfile', + function=kfile_scan, + argument=None, + skeys=['.k'], +) scanners = DefaultEnvironment()['SCANNERS'] scanners.append(kscan) @@ -7025,29 +7034,28 @@ bar_in.target_scanner = kscan It is important to note that you have to return a list of File nodes from the scan function, simple -strings for the file names won't do. As in the examples we are showing here, -you can use the -File() -function of your current Environment in order to create nodes on the fly from +strings for the file names won't do. As in the examples shown here, +you can use the &f-link-env-File; +function of your current &consenv; in order to create nodes on the fly from a sequence of file names with relative paths. Here is a similar but more complete example that adds a scanner which searches a path of directories (specified as the -MYPATH -&consvar;) +MYPATH &consvar;) for files that actually exist: import re import os + include_re = re.compile(r'^include\s+(\S+)$', re.M) def my_scan(node, env, path, arg): contents = node.get_text_contents() includes = include_re.findall(contents) - if includes == []: + if not includes: return [] results = [] for inc in includes: @@ -7058,12 +7066,13 @@ def my_scan(node, env, path, arg): break return env.File(results) -scanner = Scanner(name='myscanner', - function=my_scan, - argument=None, - skeys=['.x'], - path_function=FindPathDirs('MYPATH') - ) +scanner = Scanner( + name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=FindPathDirs('MYPATH'), +) scanners = DefaultEnvironment()['SCANNERS'] scanners.append(scanner) @@ -7073,12 +7082,12 @@ env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') The -FindPathDirs() +&f-link-FindPathDirs; function used in the previous example returns a function (actually a callable Python object) that will return a list of directories specified in the -$MYPATH +MYPATH &consvar;. It lets &scons; detect the file incs/foo.inc, even if @@ -7088,7 +7097,7 @@ contains the line only. If you need to customize how the search path is derived, you would provide your own -path_function +path_function argument when creating the Scanner object, as follows: @@ -7102,12 +7111,14 @@ def pf(env, dir, target, source, arg): results.append(top_dir + os.sep + p) return results -scanner = Scanner(name='myscanner', - function=my_scan, - argument=None, - skeys=['.x'], - path_function=pf - ) + +scanner = Scanner( + name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=pf +) @@ -7116,14 +7127,13 @@ scanner = Scanner(name='myscanner', Creating a Hierarchical Build Notice that the file names specified in a subdirectory's -SConscript -file are relative to that subdirectory. +SConscript file are relative to that subdirectory. SConstruct: env = Environment() -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') SConscript('sub/SConscript') @@ -7133,7 +7143,7 @@ SConscript('sub/SConscript') env = Environment() # Builds sub/foo from sub/foo.c -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') SConscript('dir/SConscript') @@ -7143,7 +7153,7 @@ SConscript('dir/SConscript') env = Environment() # Builds sub/dir/foo from sub/dir/foo.c -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') @@ -7151,14 +7161,15 @@ env.Program(target = 'foo', source = 'foo.c') Sharing Variables Between SConscript Files -You must explicitly call &Export; and &Import; for variables that +You must explicitly call &f-link-Export; and &f-link-Import; +for variables that you want to share between SConscript files. SConstruct: env = Environment() -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') Export("env") SConscript('subdirectory/SConscript') @@ -7168,7 +7179,7 @@ SConscript('subdirectory/SConscript') Import("env") -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') @@ -7176,8 +7187,8 @@ env.Program(target = 'foo', source = 'foo.c') Building Multiple Variants From the Same Source -Use the variant_dir keyword argument to -the &SConscriptFunc; function to establish +Use the variant_dir keyword argument to +the &f-link-SConscript; function to establish one or more separate variant build directory trees for a given source directory: @@ -7197,12 +7208,12 @@ SConscript('src/SConscript', variant_dir='bar') Import("cppdefines") -env = Environment(CPPDEFINES = cppdefines) -env.Program(target = 'src', source = 'src.c') +env = Environment(CPPDEFINES=cppdefines) +env.Program(target='src', source='src.c') -Note the use of the &Export; method -to set the "cppdefines" variable to a different +Note the use of the &f-link-Export; method +to set the cppdefines variable to a different value each time we call the &SConscriptFunc; function. @@ -7249,8 +7260,9 @@ top-level directory, so they don't turn into used in Main/SConscript Specifying only 'a' and 'b' for the library names -allows &scons; to append the appropriate library -prefix and suffix for the current platform +allows &scons; to attach the appropriate library +prefix and suffix for the current platform in +creating the library filename (for example, liba.a on POSIX systems, a.lib on Windows). @@ -7264,7 +7276,7 @@ line or in the file custom.py. vars = Variables('custom.py') -vars.Add('CC', help='The C compiler.') +vars.Add('CC', 'The C compiler.') env = Environment(variables=vars) Help(vars.GenerateHelpText(env)) @@ -7296,14 +7308,19 @@ CC: The C compiler. Using Microsoft Visual C++ precompiled headers -Since windows.h includes everything and the kitchen sink, it can take quite +Since windows.h includes everything +and the kitchen sink, it can take quite some time to compile it over and over again for a bunch of object files, so Microsoft provides a mechanism to compile a set of headers once and then include the previously compiled headers in any object file. This -technology is called precompiled headers. The general recipe is to create a -file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and -then include every header you want to precompile in "StdAfx.h", and finally -include "StdAfx.h" as the first header in all the source files you are +technology is called precompiled headers (PCH). +The general recipe is to create a +file named StdAfx.cpp +that includes a single header named StdAfx.h, +and then include every header you want to precompile in +StdAfx.h, +and finally include "StdAfx.h +as the first header in all the source files you are compiling to object files. For example: StdAfx.h: @@ -7344,9 +7361,11 @@ env['PCH'] = env.PCH('StdAfx.cpp')[0] env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) -For more information see the document for the PCH builder, and the PCH and -PCHSTOP &consvars;. To learn about the details of precompiled -headers consult the MSDN documentation for /Yc, /Yu, and /Yp. +For more information see the documentation for the &b-link-PCH; builder, +and the &cv-link-PCH; and &cv-link-PCHSTOP; &consvars;. +To learn about the details of precompiled +headers consult the MSDN documentation for +, , and . @@ -7355,9 +7374,9 @@ headers consult the MSDN documentation for /Yc, /Yu, and /Yp. Since including debugging information in programs and shared libraries can cause their size to increase significantly, Microsoft provides a mechanism -for including the debugging information in an external file called a PDB -file. &scons; supports PDB files through the PDB construction -variable. +for including the debugging information in an external file called a +PDB file. +&scons; supports PDB files through the &cv-PDB; &consvar;. SConstruct: @@ -7367,7 +7386,8 @@ env['PDB'] = 'MyApp.pdb' env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) -For more information see the document for the PDB &consvar;. +For more information see the documentation for the +&cv-link-PDB; &consvar;. @@ -7430,7 +7450,7 @@ Remove the cache file in case of problems with this. &scons; will ignore failures reading or writing the file and will silently revert to non-cached behavior in such cases. -Since &scons; 3.1 (experimental). +Available since &scons; 3.1 (experimental). -- cgit v0.12