From baee03c569c91b745a1e025660b19a718db16e7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Thu, 28 Sep 2017 12:18:58 +0200 Subject: New upstream version 3.0.0 --- doc/SConscript | 109 +-- doc/design/SConstruct | 2 +- doc/design/acks.xml | 2 +- doc/design/bground.xml | 2 +- doc/design/chtml.xsl | 2 +- doc/design/copyright.xml | 2 +- doc/design/engine.xml | 2 +- doc/design/goals.xml | 2 +- doc/design/html.xsl | 2 +- doc/design/install.xml | 2 +- doc/design/intro.xml | 2 +- doc/design/issues.xml | 2 +- doc/design/main.xml | 2 +- doc/design/native.xml | 2 +- doc/design/overview.xml | 2 +- doc/design/pdf.xsl | 2 +- doc/design/scons_title.xsl | 2 +- doc/design/summary.xml | 2 +- doc/developer/SConstruct | 2 +- doc/developer/architecture.xml | 2 +- doc/developer/branches.xml | 2 +- doc/developer/copyright.xml | 2 +- doc/developer/cycle.xml | 2 +- doc/developer/main.xml | 2 +- doc/developer/packaging.xml | 2 +- doc/developer/preface.xml | 2 +- doc/developer/sourcetree.xml | 2 +- doc/developer/testing.xml | 2 +- doc/generated/builders.gen | 87 ++- doc/generated/builders.mod | 4 + doc/generated/examples/caching_ex-random_1.xml | 6 +- doc/generated/examples/environments_ex3_1.xml | 22 +- doc/generated/examples/environments_missing2_1.xml | 2 +- doc/generated/examples/java_jar1_1.xml | 2 +- .../examples/mergeflags_MergeFlags1_1.xml | 9 +- .../examples/mergeflags_MergeFlags2_1.xml | 9 +- .../examples/mergeflags_MergeFlags3_1.xml | 10 +- doc/generated/examples/misc_Flatten2_1.xml | 2 +- doc/generated/examples/parseflags_ex1_1.xml | 12 +- doc/generated/examples/parseflags_ex1_2.xml | 13 +- doc/generated/examples/parseflags_ex2_1.xml | 10 +- doc/generated/examples/parseflags_ex3_1.xml | 12 +- doc/generated/examples/parseflags_ex4_1.xml | 12 +- doc/generated/examples/sourcecode_bitkeeper_1.xml | 6 +- doc/generated/examples/sourcecode_cvs_1.xml | 6 +- doc/generated/examples/sourcecode_rcs_1.xml | 6 +- doc/generated/examples/sourcecode_sccs_1.xml | 6 +- doc/generated/examples/tasks_ex1_1.xml | 2 +- doc/generated/examples/troubleshoot_Dump_1.xml | 78 +- doc/generated/examples/troubleshoot_Dump_2.xml | 110 +-- doc/generated/examples/troubleshoot_Dump_ENV_1.xml | 12 +- doc/generated/examples/troubleshoot_Dump_ENV_2.xml | 14 +- doc/generated/examples/troubleshoot_explain1_3.xml | 2 +- .../examples/troubleshoot_stacktrace_2.xml | 6 +- doc/generated/functions.gen | 251 +------ doc/generated/functions.mod | 24 +- doc/generated/tools.gen | 79 +- doc/generated/tools.mod | 18 +- doc/generated/variables.gen | 805 +++++++++++---------- doc/generated/variables.mod | 78 +- doc/man/SConstruct | 2 +- doc/man/epub.xsl | 2 +- doc/man/html.xsl | 2 +- doc/man/pdf.xsl | 2 +- doc/man/scons-time.xml | 6 +- doc/man/scons.xml | 58 +- doc/man/scons_title.xsl | 2 +- doc/man/sconsign.xml | 6 +- doc/python10/SConstruct | 2 +- doc/python10/abstract.xml | 2 +- doc/python10/acks.xml | 2 +- doc/python10/copyright.xml | 2 +- doc/python10/design.xml | 2 +- doc/python10/future.xml | 2 +- doc/python10/install.xml | 2 +- doc/python10/intro.xml | 2 +- doc/python10/main.xml | 2 +- doc/python10/process.xml | 2 +- doc/python10/summary.xml | 2 +- doc/reference/Alias.xml | 2 +- doc/reference/CFile.xml | 2 +- doc/reference/CXXFile.xml | 2 +- doc/reference/Command.xml | 2 +- doc/reference/Install.xml | 2 +- doc/reference/InstallAs.xml | 2 +- doc/reference/Library.xml | 2 +- doc/reference/Object.xml | 2 +- doc/reference/PCH.xml | 2 +- doc/reference/PDF.xml | 2 +- doc/reference/PostScript.xml | 2 +- doc/reference/Program.xml | 2 +- doc/reference/RES.xml | 2 +- doc/reference/SConstruct | 2 +- doc/reference/SharedLibrary.xml | 2 +- doc/reference/SharedObject.xml | 2 +- doc/reference/StaticLibrary.xml | 2 +- doc/reference/StaticObject.xml | 2 +- doc/reference/chtml.xsl | 2 +- doc/reference/copyright.xml | 2 +- doc/reference/errors.xml | 2 +- doc/reference/html.xsl | 2 +- doc/reference/main.xml | 2 +- doc/reference/pdf.xsl | 2 +- doc/reference/preface.xml | 2 +- doc/reference/scons_title.xsl | 2 +- doc/scons.mod | 3 +- doc/user/README | 2 +- doc/user/SConstruct | 2 +- doc/user/actions.xml | 2 +- doc/user/add-method.xml | 2 +- doc/user/alias.xml | 2 +- doc/user/ant.xml | 2 +- doc/user/build-install.xml | 4 +- doc/user/builders-built-in.xml | 2 +- doc/user/builders-commands.xml | 2 +- doc/user/builders-writing.xml | 6 +- doc/user/builders.xml | 2 +- doc/user/caching.xml | 2 +- doc/user/chtml.xsl | 2 +- doc/user/command-line.xml | 16 +- doc/user/copyright.xml | 2 +- doc/user/depends.xml | 2 +- doc/user/environments.xml | 201 ++++- doc/user/epub.xsl | 2 +- doc/user/errors.xml | 2 +- doc/user/example.xml | 2 +- doc/user/factories.xml | 2 +- doc/user/file-removal.xml | 2 +- doc/user/functions.xml | 2 +- doc/user/gettext.xml | 2 +- doc/user/hierarchy.xml | 2 +- doc/user/html.xsl | 2 +- doc/user/install.xml | 2 +- doc/user/java.xml | 2 +- doc/user/less-simple.xml | 2 +- doc/user/libraries.xml | 2 +- doc/user/main.xml | 6 +- doc/user/make.xml | 2 +- doc/user/mergeflags.xml | 2 +- doc/user/misc.xml | 32 +- doc/user/nodes.xml | 14 +- doc/user/output.xml | 10 +- doc/user/parseconfig.xml | 2 +- doc/user/parseflags.xml | 2 +- doc/user/pdf.xsl | 2 +- doc/user/preface.xml | 2 +- doc/user/python.xml | 2 +- doc/user/repositories.xml | 2 +- doc/user/run.xml | 2 +- doc/user/scanners.xml | 2 +- doc/user/sconf.xml | 12 +- doc/user/scons_title.xsl | 2 +- doc/user/separate.xml | 2 +- doc/user/sideeffect.xml | 2 +- doc/user/simple.xml | 8 +- doc/user/sourcecode.xml | 2 +- doc/user/tasks.xml | 2 +- doc/user/tools.xml | 2 +- doc/user/troubleshoot.xml | 2 +- doc/user/variables.xml | 2 +- doc/user/variants.xml | 2 +- 161 files changed, 1175 insertions(+), 1259 deletions(-) (limited to 'doc') diff --git a/doc/SConscript b/doc/SConscript index d49b88c..46d4533 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001 - 2016 The SCons Foundation +# Copyright (c) 2001 - 2017 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -24,6 +24,8 @@ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +from __future__ import print_function + import os.path import re import sys @@ -51,7 +53,7 @@ fop = whereis('fop') xep = whereis('xep') if not fop and not xep: - print "doc: No PDF renderer found (fop|xep)!" + print("doc: No PDF renderer found (fop|xep)!") skip_doc = True # @@ -109,16 +111,17 @@ man_replace_tpl = """.TH "%(uctitle)s" "1" "%(today)s" "SCons %(version)s" "SCon .ad l .SH "NOTE" %(title)s \- This is a replacement file, stemming from an incomplete -packaging process without the required doc modules installed. Please +packaging process without the required doc modules installed. Please update the system and try running bootstrap.py again. """ # # --- Processing --- # + if skip_doc: - print "doc: ...skipping building User Guide." - print " ...creating fake MAN pages." + print("doc: ...skipping building User Guide.") + print(" ...creating fake MAN pages.") # Since the top-level SConstruct requires the MAN # pages to exist for the basic packaging, we create simple @@ -126,7 +129,7 @@ if skip_doc: scdir = os.path.join(build, 'man') if not os.path.isdir(scdir): os.makedirs(scdir) - + import datetime today = datetime.date.today().strftime("%m/%d/%Y") version = env.subst('$VERSION') @@ -140,8 +143,8 @@ if skip_doc: fman.close() else: if not lynx: - print "doc: Warning, lynx is not installed...created release packages won't be complete!" - + print("doc: Warning, lynx is not installed...created release packages won't be complete!") + # # Always create a version.xml file containing the version information # for this run. Ignore it for dependency purposes so we don't @@ -157,7 +160,7 @@ else: # # Builder for copying files to an Install dir, based # on their extension (better: glob matching pattern)... - # + # def _glob_install_action(target, source, env): if not SCons.Util.is_List(target): target = [target] @@ -170,7 +173,7 @@ else: target = [target] if not SCons.Util.is_List(source): source = [source] - + res = [] res_src = [] tdir = env.Dir(target[0]) @@ -185,7 +188,7 @@ else: # # Builder for copying ChunkedHTML files to an Install dir... - # + # def _chunked_install_action(target, source, env): if not SCons.Util.is_List(target): target = [target] @@ -195,13 +198,13 @@ else: spattern = os.path.join(os.path.split(str(source[0]))[0], '*.html') for g in glob.glob(spattern): shutil.copy(g, tdir) - + def _chunked_install_emitter(target, source, env): if not SCons.Util.is_List(target): target = [target] if not SCons.Util.is_List(source): source = [source] - + tdir = env.Dir(target[0]) head, tail = os.path.split(str(source[0])) return os.path.join(str(tdir), tail), source @@ -214,23 +217,23 @@ else: # Ensure that all XML files are valid against our XSD, and # that all example names and example output suffixes are unique # - print "Validating files against SCons XSD..." + print("Validating files against SCons XSD...") if SConsDoc.validate_all_xml(['src'], xsdfile='xsd/scons.xsd'): - print "OK" + print("OK") else: - print "Validation failed! Please correct the errors above and try again." - sys.exit(0) - - print "Checking whether all example names are unique..." + print("Validation failed! Please correct the errors above and try again.") + sys.exit(1) + + print("Checking whether all example names are unique...") if SConsExamples.exampleNamesAreUnique(os.path.join('doc','user')): - print "OK" + print("OK") else: - print "Not all example names and suffixes are unique! Please correct the errors listed above and try again." - sys.exit(0) - + print("Not all example names and suffixes are unique! Please correct the errors listed above and try again.") + sys.exit(1) + # List of prerequisite files in the build/doc folder buildsuite = [] - + def copy_dbfiles(env, toolpath, paths, fpattern, use_builddir=True): """ Helper function, copies a bunch of files matching the given fpattern to a target directory. @@ -251,7 +254,7 @@ else: target_dir = env.Dir(os.path.join(*(toolpath+paths))) buildsuite.extend(env.GlobInstall(target_dir, os.path.join(*(paths + fpattern)))) - + # # Copy generated files (.gen/.mod/.xml) to the build folder # @@ -300,7 +303,7 @@ else: # installing/copying them to the build directory. It basically # links the original sources to the respective build folder, # such that a simple 'python bootstrap.py' rebuilds the - # documentation when a file, like 'doc/user/depends.xml' + # documentation when a file, like 'doc/user/depends.xml' # for example, changes. # Finally, in DOCNODES we store the created PDF and HTML files, # such that we can then install them in the proper places for @@ -315,7 +318,7 @@ else: 'user' : (['chunked','html','pdf','epub','text'], [], []), 'man' : (['man','epub','text'], [], []) } - + # # We have to tell SCons to scan the top-level XML files which # get included by the document XML files in the subdirectories. @@ -327,15 +330,15 @@ else: continue base, ext = os.path.splitext(s) if ext in ['.fig', '.jpg']: - buildsuite.extend(env.Command(os.path.join(build, s), - s, + buildsuite.extend(env.Command(os.path.join(build, s), + s, Copy("$TARGET", "$SOURCE"))) else: revaction([env.File(os.path.join(build, s))], [env.File(s)], env) for doc in docs: - + # # Read MANIFEST file and copy the listed files to the # build directory, while branding them with the @@ -359,7 +362,7 @@ else: else: target_dir = os.path.join(build, doc) if ext in ['.fig', '.jpg', '.svg']: - docs[doc][DOCDEPENDS].extend(env.Command(build_s, doc_s, + docs[doc][DOCDEPENDS].extend(env.Command(build_s, doc_s, Copy("$TARGET", "$SOURCE"))) else: btarget = env.File(build_s) @@ -389,18 +392,18 @@ else: sctargets.append(env.File(os.path.join(scdir, 'scons-%s.pdf' % doc))) if 'epub' in docs[doc][DOCTARGETS]: sctargets.append(env.File(os.path.join(scdir, 'scons-%s.epub' % doc))) - + if 'man' in docs[doc][DOCTARGETS]: for m in man_page_list: sctargets.append(os.path.join(scdir, m)) man, _1 = os.path.splitext(m) - + sctargets.append(os.path.join(scdir, 'scons-%s.pdf' % man)) sctargets.append(os.path.join(scdir, 'scons-%s.html' % man)) - - docs[doc][DOCNODES].extend(env.Command(sctargets, buildsuite + docs[doc][DOCDEPENDS], + + docs[doc][DOCNODES].extend(env.Command(sctargets, buildsuite + docs[doc][DOCDEPENDS], "cd %s && $PYTHON ${SCONS_PY.abspath}%s" % (scdir, cleanopt))) - + install_css = False for doc in docs: @@ -412,13 +415,13 @@ else: epub = os.path.join(build, 'EPUB', 'scons-%s.epub' % doc) text = os.path.join(build, 'TEXT', 'scons-%s.txt' % doc) if 'chunked' in docs[doc][DOCTARGETS]: - installed_chtml = env.ChunkedInstall(env.Dir(htmldir), + installed_chtml = env.ChunkedInstall(env.Dir(htmldir), os.path.join(build, doc,'scons-%s' % doc, 'index.html')) installed_chtml_css = env.Install(env.Dir(htmldir), os.path.join(build, doc, 'scons.css')) env.Depends(installed_chtml, docs[doc][DOCNODES]) env.Depends(installed_chtml_css, docs[doc][DOCNODES]) - + tar_deps.extend([htmlindex, installed_chtml_css]) tar_list.extend([htmldir]) Local(htmlindex) @@ -431,7 +434,7 @@ else: Local(html) env.Ignore(html, version_xml) install_css = True - + if 'pdf' in docs[doc][DOCTARGETS]: env.InstallAs(env.File(pdf), env.File(os.path.join(build, doc,'scons-%s.pdf' % doc))) Local(pdf) @@ -447,14 +450,14 @@ else: tar_deps.append(epub) tar_list.append(epub) - - if ('text' in docs[doc][DOCTARGETS] and lynx and + + if ('text' in docs[doc][DOCTARGETS] and lynx and (('html' in docs[doc][DOCTARGETS]) or (doc == 'man'))): texthtml = os.path.join(build, doc,'index.html') if doc == 'man': # Special handling for single MAN file texthtml = os.path.join(build, doc, 'scons-scons.html') - + env.Command(text, env.File(texthtml), "lynx -dump ${SOURCE.abspath} > $TARGET") Local(text) @@ -462,21 +465,21 @@ else: tar_deps.append(text) tar_list.append(text) - - + + if 'man' in docs[doc][DOCTARGETS]: # # Man page(s) # for m in man_page_list: man, _1 = os.path.splitext(m) - + pdf = os.path.join(build, 'PDF', '%s-man.pdf' % man) html = os.path.join(build, 'HTML' , '%s-man.html' % man) - + env.InstallAs(env.File(pdf), env.File(os.path.join(build, 'man','scons-%s.pdf' % man))) env.InstallAs(env.File(html), env.File(os.path.join(build, 'man','scons-%s.html' % man))) - + tar_deps.extend([pdf, html]) tar_list.extend([pdf, html]) @@ -484,7 +487,7 @@ else: # Install CSS file, common to all single HTMLs if install_css: css_file = os.path.join(build, 'HTML', 'scons.css') - env.InstallAs(env.File(css_file), + env.InstallAs(env.File(css_file), env.File(os.path.join(build, 'user','scons.css'))) tar_deps.extend([css_file]) tar_list.extend([css_file]) @@ -540,7 +543,7 @@ if not epydoc_cli: # http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/src/epydoc/cli.py elif env['EPYDOCFLAGS'] == '--pdf': - pdf_writer = LatexWriter(docindex, + pdf_writer = LatexWriter(docindex, docformat='restructuredText', prj_name='SCons', prj_url='http://www.scons.org/') @@ -560,9 +563,9 @@ else: # epydoc_cli is found Touch('$TARGET'), ] - + if not epydoc_cli and not epydoc: - print "doc: epydoc not found, skipping building API documentation." + print("doc: epydoc not found, skipping building API documentation.") else: # XXX Should be in common with reading the same thing in # the SConstruct file. @@ -584,7 +587,7 @@ else: tar_list.append(htmldir) if not epydoc_cli: - print "doc: command line epydoc is not found, skipping PDF/PS/Tex output" + print("doc: command line epydoc is not found, skipping PDF/PS/Tex output") else: # PDF and PostScript and TeX are built from the # same invocation. @@ -617,7 +620,7 @@ if tar_deps: tar_list = ' '.join([x.replace(build+'/', '') for x in tar_list]) t = env.Command(dist_doc_tar_gz, tar_deps, "tar cf${TAR_HFLAG} - -C %s %s | gzip > $TARGET" % (build, tar_list)) - AddPostAction(dist_doc_tar_gz, Chmod(dist_doc_tar_gz, 0644)) + AddPostAction(dist_doc_tar_gz, Chmod(dist_doc_tar_gz, 0o644)) Local(t) Alias('doc', t) else: diff --git a/doc/design/SConstruct b/doc/design/SConstruct index d90dcfd..2bec66f 100644 --- a/doc/design/SConstruct +++ b/doc/design/SConstruct @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001 - 2016 The SCons Foundation +# Copyright (c) 2001 - 2017 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the diff --git a/doc/design/acks.xml b/doc/design/acks.xml index 875daf7..f9969f4 100644 --- a/doc/design/acks.xml +++ b/doc/design/acks.xml @@ -12,7 +12,7 @@ @@ -2483,7 +2499,7 @@ foo = Object('foo.c') bar = Object('bar.c') objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] for object in objects: - print str(object) + print(str(object)) Or you can use the @@ -2497,7 +2513,7 @@ foo = Object('foo.c') bar = Object('bar.c') objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o']) for object in objects: - print str(object) + print(str(object)) Note also that because Builder calls return @@ -2541,7 +2557,7 @@ function: bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') -print "The path to bar_obj is:", str(bar_obj_list[0]) +print("The path to bar_obj is:", str(bar_obj_list[0])) Note again that because the Builder call returns a list, @@ -2842,10 +2858,10 @@ of the tuple, respectively. Example: -print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1] -print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1] +print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]) +print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]) third_tuple = ARGLIST[2] -print "third keyword, value =", third_tuple[0], third_tuple[1] +print("third keyword, value =", third_tuple[0], third_tuple[1]) for key, value in ARGLIST: # process key and value @@ -2913,7 +2929,7 @@ for additional information. if 'foo' in BUILD_TARGETS: - print "Don't forget to test the `foo' program!" + print("Don't forget to test the `foo' program!") if 'special/program' in BUILD_TARGETS: SConscript('special') @@ -2951,7 +2967,7 @@ is explicitly being built. if 'foo' in COMMAND_LINE_TARGETS: - print "Don't forget to test the `foo' program!" + print("Don't forget to test the `foo' program!") if 'special/program' in COMMAND_LINE_TARGETS: SConscript('special') @@ -2975,9 +2991,9 @@ function to get at the path name for each Node. Example: -print str(DEFAULT_TARGETS[0]) +print(str(DEFAULT_TARGETS[0])) if 'foo' in map(str, DEFAULT_TARGETS): - print "Don't forget to test the `foo' program!" + print("Don't forget to test the `foo' program!") @@ -2990,13 +3006,13 @@ list change on on each successive call to the function: -print map(str, DEFAULT_TARGETS) # originally [] +print(map(str, DEFAULT_TARGETS)) # originally [] Default('foo') -print map(str, DEFAULT_TARGETS) # now a node ['foo'] +print(map(str, DEFAULT_TARGETS)) # now a node ['foo'] Default('bar') -print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar'] +print(map(str, DEFAULT_TARGETS)) # now a node ['foo', 'bar'] Default(None) -print map(str, DEFAULT_TARGETS) # back to [] +print(map(str, DEFAULT_TARGETS)) # back to [] Consequently, be sure to use @@ -3525,7 +3541,7 @@ a shared library, only that the compilation (not link) succeeds. env = Environment() conf = Configure( env ) if not conf.CheckCHeader( 'math.h' ): - print 'We really need math.h!' + print('We really need math.h!') Exit(1) if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ): @@ -3815,7 +3831,7 @@ int main(int argc, char **argv) { env = Environment() conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } ) if not conf.CheckQt('/usr/lib/qt'): - print 'We really need qt!' + print('We really need qt!') Exit(1) env = conf.Finish() @@ -3995,7 +4011,7 @@ not configured. env = Environment(variables=vars) for key, value in vars.UnknownVariables(): - print "unknown variable: %s=%s" % (key, value) + print("unknown variable: %s=%s" % (key, value)) @@ -4400,7 +4416,7 @@ File('foo.c').srcnode().path # source path of the given source file. # Builders also return File objects: foo = env.Program('foo.c') -print "foo will be built in %s"%foo.path +print("foo will be built in %s"%foo.path) A diff --git a/doc/man/scons_title.xsl b/doc/man/scons_title.xsl index 11de773..cc5ae5e 100644 --- a/doc/man/scons_title.xsl +++ b/doc/man/scons_title.xsl @@ -1,7 +1,7 @@