From ba4425ab5227fd9597fccd368bffff6bf1032149 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 10 Sep 2011 11:25:53 +0200 Subject: Imported Upstream version 2.1.0 --- doc/SConscript | 145 +- doc/design/scons.mod | 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/man/scons-time.1 | 6 +- doc/man/scons.1 | 4466 +++------------------------------------- doc/man/sconsign.1 | 6 +- doc/python10/scons.mod | 2 +- doc/scons.mod | 4 +- doc/user/MANIFEST | 1 + doc/user/README | 2 +- doc/user/actions.in | 2 +- doc/user/actions.xml | 2 +- doc/user/add-method.in | 2 +- doc/user/add-method.xml | 3 +- doc/user/alias.in | 2 +- doc/user/alias.xml | 2 +- doc/user/ant.in | 2 +- doc/user/ant.xml | 2 +- doc/user/build-install.in | 25 +- doc/user/build-install.xml | 25 +- doc/user/builders-built-in.in | 2 +- doc/user/builders-built-in.xml | 3 +- doc/user/builders-commands.in | 4 +- doc/user/builders-commands.xml | 2 +- doc/user/builders-writing.in | 63 +- doc/user/builders-writing.xml | 59 +- doc/user/builders.in | 2 +- doc/user/builders.xml | 2 +- doc/user/caching.in | 2 +- doc/user/caching.xml | 2 +- doc/user/command-line.in | 6 +- doc/user/command-line.xml | 17 +- doc/user/copyright.in | 2 +- doc/user/copyright.xml | 2 +- doc/user/depends.in | 61 +- doc/user/depends.xml | 60 +- doc/user/environments.in | 22 +- doc/user/environments.xml | 10 +- doc/user/errors.in | 2 +- doc/user/errors.xml | 2 +- doc/user/example.in | 2 +- doc/user/example.xml | 2 +- doc/user/factories.in | 4 +- doc/user/factories.xml | 2 +- doc/user/file-removal.in | 2 +- doc/user/file-removal.xml | 2 +- doc/user/functions.in | 38 + doc/user/functions.xml | 38 + doc/user/hierarchy.in | 6 +- doc/user/hierarchy.xml | 4 +- doc/user/install.in | 2 +- doc/user/install.xml | 2 +- doc/user/java.in | 6 +- doc/user/java.xml | 2 +- doc/user/less-simple.in | 2 +- doc/user/less-simple.xml | 4 +- doc/user/libraries.in | 2 +- doc/user/libraries.xml | 5 +- doc/user/main.in | 53 +- doc/user/main.xml | 53 +- doc/user/make.in | 2 +- doc/user/make.xml | 2 +- doc/user/mergeflags.in | 2 +- doc/user/mergeflags.xml | 2 +- doc/user/misc.in | 12 +- doc/user/misc.xml | 6 +- doc/user/nodes.in | 2 +- doc/user/nodes.xml | 4 +- doc/user/output.in | 4 +- doc/user/output.xml | 2 +- doc/user/parseconfig.in | 2 +- doc/user/parseconfig.xml | 2 +- doc/user/parseflags.in | 2 +- doc/user/parseflags.xml | 3 +- doc/user/preface.in | 6 +- doc/user/preface.xml | 2 +- doc/user/python.in | 2 +- doc/user/python.xml | 2 +- doc/user/repositories.in | 6 +- doc/user/repositories.xml | 6 +- doc/user/run.in | 2 +- doc/user/run.xml | 2 +- doc/user/scanners.in | 17 +- doc/user/scanners.xml | 17 +- doc/user/sconf.in | 6 +- doc/user/sconf.xml | 4 +- doc/user/separate.in | 2 +- doc/user/separate.xml | 2 +- doc/user/sideeffect.in | 2 +- doc/user/sideeffect.xml | 2 +- doc/user/simple.in | 10 +- doc/user/simple.xml | 10 +- doc/user/sourcecode.in | 2 +- doc/user/sourcecode.xml | 2 +- doc/user/tasks.in | 6 +- doc/user/tasks.xml | 2 +- doc/user/tools.in | 2 +- doc/user/tools.xml | 2 +- doc/user/troubleshoot.in | 49 +- doc/user/troubleshoot.xml | 57 +- doc/user/variables.in | 2 +- doc/user/variables.xml | 2 +- doc/user/variants.in | 2 +- doc/user/variants.xml | 3 +- 112 files changed, 1044 insertions(+), 4509 deletions(-) create mode 100644 doc/user/functions.in create mode 100644 doc/user/functions.xml (limited to 'doc') diff --git a/doc/SConscript b/doc/SConscript index e0b3f71..54b620e 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -43,7 +43,7 @@ dist_doc_tar_gz = '$DISTDIR/scons-doc-${VERSION}.tar.gz' # if lynx is available to do the dump. # fig2dev = whereis('fig2dev') -epydoc = whereis('epydoc') +epydoc_cli = whereis('epydoc') groff = whereis('groff') lynx = whereis('lynx') man2html = whereis('man2html') @@ -121,7 +121,7 @@ scons_doc_files = list(map(chop, open(manifest_xml_in).readlines())) scons_doc_files = [File('#src/engine/'+x).rstr() for x in scons_doc_files] if not jw: - print "jw not found, skipping building User Guide." + print "doc: jw not found, skipping building User Guide." else: # # Always create a version.xml file containing the version information @@ -151,6 +151,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. builders_gen = os.path.join(build, 'user', 'builders.gen') builders_mod = os.path.join(build, 'user', 'builders.mod') + functions_gen = os.path.join(build, 'user', 'functions.gen') + functions_mod = os.path.join(build, 'user', 'functions.mod') tools_gen = os.path.join(build, 'user', 'tools.gen') tools_mod = os.path.join(build, 'user', 'tools.mod') variables_gen = os.path.join(build, 'user', 'variables.gen') @@ -163,11 +165,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. # vs. the other. The *.gen and *.mod targets will still be dependent # on the list of the files themselves. doc_output_files = [builders_gen, builders_mod, + functions_gen, functions_mod, tools_gen, tools_mod, variables_gen, variables_mod] b = env.Command(doc_output_files, scons_doc_files, - "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -t ${TARGETS[2]},${TARGETS[3]} -v ${TARGETS[4]},${TARGETS[5]} $( $SOURCES $)") + "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -f ${TARGETS[2]},${TARGETS[3]} -t ${TARGETS[4]},${TARGETS[5]} -v ${TARGETS[6]},${TARGETS[7]} $( $SOURCES $)") env.Depends(b, "$SCONS_PROC_PY") env.Local(b) @@ -403,11 +406,11 @@ for m in man_page_list: x = orig_env.SCons_revision(os.path.join(build, 'man', m), os.path.join('man', m)) -man_i_files = ['builders.man', 'tools.man', 'variables.man'] +man_i_files = ['builders.man', 'functions.man', 'tools.man', 'variables.man'] man_intermediate_files = [os.path.join(build, 'man', x) for x in man_i_files] -cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -t ${TARGETS[1]} -v ${TARGETS[2]} $( $SOURCES $)" +cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -f ${TARGETS[1]} -t ${TARGETS[2]} -v ${TARGETS[3]} $( $SOURCES $)" man_intermediate_files = env.Command(man_intermediate_files, scons_doc_files, cmd) @@ -458,8 +461,79 @@ for man_1 in man_page_list: tar_deps.append(html) tar_list.append(html) -if not epydoc: - print "epydoc not found, skipping building API documentation." +if not epydoc_cli: + try: + import epydoc + except ImportError: + epydoc = None + else: + # adding Epydoc builder using imported module + def epydoc_builder_action(target, source, env): + """ + Take a list of `source` files and build docs for them in + `target` dir. + + `target` and `source` are lists. + + Uses OUTDIR and EPYDOCFLAGS environment variables. + + http://www.scons.org/doc/2.0.1/HTML/scons-user/x3594.html + """ + + # the epydoc build process is the following: + # 1. build documentation index + # 2. feed doc index to writer for docs + + from epydoc.docbuilder import build_doc_index + from epydoc.docwriter.html import HTMLWriter + from epydoc.docwriter.latex import LatexWriter + + # first arg is a list where can be names of python package dirs, + # python files, object names or objects itself + docindex = build_doc_index([str(src) for src in source]) + if docindex == None: + return -1 + + if env['EPYDOCFLAGS'] == '--html': + html_writer = HTMLWriter(docindex, + docformat='restructuredText', + prj_name='SCons', + prj_url='http://www.scons.org/') + try: + html_writer.write(env['OUTDIR']) + except OSError: # If directory cannot be created or any file cannot + # be created or written to. + return -2 + + """ + # PDF support requires external Linux utilites, so it's not crossplatform. + # Leaving for now. + # http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/src/epydoc/cli.py + + elif env['EPYDOCFLAGS'] == '--pdf': + pdf_writer = LatexWriter(docindex, + docformat='restructuredText', + prj_name='SCons', + prj_url='http://www.scons.org/') + """ + return 0 + + epydoc_commands = [ + Delete('$OUTDIR'), + epydoc_builder_action, + Touch('$TARGET'), + ] + +else: # epydoc_cli is found + epydoc_commands = [ + Delete('$OUTDIR'), + '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES', + Touch('$TARGET'), + ] + + +if not epydoc_cli and not epydoc: + print "doc: epydoc not found, skipping building API documentation." else: # XXX Should be in common with reading the same thing in # the SConstruct file. @@ -475,40 +549,37 @@ else: e = os.path.join(build, '..', 'scons', 'engine') sources = [os.path.join(e, x) for x in sources] - epydoc_commands = [ - Delete('$OUTDIR'), - '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES', - Touch('$TARGET'), - ] - htmldir = os.path.join(build, 'HTML', 'scons-api') env.Command('${OUTDIR}/index.html', sources, epydoc_commands, - EPYDOC=epydoc, EPYDOCFLAGS='--html', OUTDIR=htmldir) + EPYDOC=epydoc_cli, EPYDOCFLAGS='--html', OUTDIR=htmldir) tar_deps.append(htmldir) tar_list.append(htmldir) - # PDF and PostScript and TeX are built from the - # same invocation. - api_dir = os.path.join(build, 'scons-api') - api_pdf = os.path.join(api_dir, 'api.pdf') - api_ps = os.path.join(api_dir, 'api.ps') - api_tex = os.path.join(api_dir, 'api.tex') - api_targets = [api_pdf, api_ps, api_tex] - env.Command(api_targets, sources, epydoc_commands, - EPYDOC=epydoc, EPYDOCFLAGS='--pdf', OUTDIR=api_dir) - Local(api_targets) - - pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf') - env.InstallAs(pdf_install, api_pdf) - tar_deps.append(pdf_install) - tar_list.append(pdf_install) - Local(pdf_install) - - ps_install = os.path.join(build, 'PS', 'scons-api.ps') - env.InstallAs(ps_install, api_ps) - tar_deps.append(ps_install) - tar_list.append(ps_install) - Local(ps_install) + if not epydoc_cli: + 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. + api_dir = os.path.join(build, 'scons-api') + api_pdf = os.path.join(api_dir, 'api.pdf') + api_ps = os.path.join(api_dir, 'api.ps') + api_tex = os.path.join(api_dir, 'api.tex') + api_targets = [api_pdf, api_ps, api_tex] + env.Command(api_targets, sources, epydoc_commands, + EPYDOC=epydoc_cli, EPYDOCFLAGS='--pdf', OUTDIR=api_dir) + Local(api_targets) + + pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf') + env.InstallAs(pdf_install, api_pdf) + tar_deps.append(pdf_install) + tar_list.append(pdf_install) + Local(pdf_install) + + ps_install = os.path.join(build, 'PS', 'scons-api.ps') + env.InstallAs(ps_install, api_ps) + tar_deps.append(ps_install) + tar_list.append(ps_install) + Local(ps_install) # # Now actually create the tar file of the documentation, diff --git a/doc/design/scons.mod b/doc/design/scons.mod index 012bc3e..33538fb 100644 --- a/doc/design/scons.mod +++ b/doc/design/scons.mod @@ -1,6 +1,6 @@ - Similarly, a more full-fledged tool with + A more full-fledged tool with exists() and generate() - methods can be installed in - site_scons/site_tools/toolname.py. Since - site_scons/site_tools is automatically added - to the head of the tool search path, any tool found there will be - available to all environments. Furthermore, a tool found there - will override a built-in tool of the same name, so if you need to - change the behavior of a built-in tool, site_scons gives you the - hook you need. + methods can be installed either as a module in the file + site_scons/site_tools/toolname.py or as a + package in the + directory site_scons/site_tools/toolname. In + the case of using a package, the exists() + and generate() are in the + file site_scons/site_tools/toolname/__init__.py. + (In all the above case toolname is replaced + by the name of the tool.) + Since site_scons/site_tools is automatically + added to the head of the tool search path, any tool found there + will be available to all environments. Furthermore, a tool found + there will override a built-in tool of the same name, so if you + need to change the behavior of a built-in + tool, site_scons gives you the hook you need. @@ -998,7 +1013,7 @@ This functionality could be invoked as in the following example: - + from SCons.Script import * # for Execute and Mkdir def build_id(): """Return a build ID (stub version)""" @@ -1047,13 +1062,15 @@ This functionality could be invoked as in the following example: - If you have a machine-wide site dir you'd like to use instead of - ./site_scons, use the - --site-dir option to point to your dir. + You can use any of the user- or machine-wide site dirs such as + ~/.scons/site_scons instead of + ./site_scons, or use the + --site-dir option to point to your own dir. site_init.py and site_tools will be located under that dir. - To avoid using a site_scons dir at all, even - if it exists, use the --no-site-dir option. + To avoid using a site_scons dir at all, + even if it exists, use the --no-site-dir + option. diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index f364e27..d9bda79 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -1,6 +1,6 @@ - Similarly, a more full-fledged tool with + A more full-fledged tool with exists() and generate() - methods can be installed in - site_scons/site_tools/toolname.py. Since - site_scons/site_tools is automatically added - to the head of the tool search path, any tool found there will be - available to all environments. Furthermore, a tool found there - will override a built-in tool of the same name, so if you need to - change the behavior of a built-in tool, site_scons gives you the - hook you need. + methods can be installed either as a module in the file + site_scons/site_tools/toolname.py or as a + package in the + directory site_scons/site_tools/toolname. In + the case of using a package, the exists() + and generate() are in the + file site_scons/site_tools/toolname/__init__.py. + (In all the above case toolname is replaced + by the name of the tool.) + Since site_scons/site_tools is automatically + added to the head of the tool search path, any tool found there + will be available to all environments. Furthermore, a tool found + there will override a built-in tool of the same name, so if you + need to change the behavior of a built-in + tool, site_scons gives you the hook you need. @@ -913,13 +928,15 @@ This functionality could be invoked as in the following example: - If you have a machine-wide site dir you'd like to use instead of - ./site_scons, use the - --site-dir option to point to your dir. + You can use any of the user- or machine-wide site dirs such as + ~/.scons/site_scons instead of + ./site_scons, or use the + --site-dir option to point to your own dir. site_init.py and site_tools will be located under that dir. - To avoid using a site_scons dir at all, even - if it exists, use the --no-site-dir option. + To avoid using a site_scons dir at all, + even if it exists, use the --no-site-dir + option. diff --git a/doc/user/builders.in b/doc/user/builders.in index 9e9b647..f2bf36d 100644 --- a/doc/user/builders.in +++ b/doc/user/builders.in @@ -1,6 +1,6 @@ + + + +This appendix contains descriptions of all of the +function and construction environment methods +in this version of &SCons; + + + + + +&functions-gen; + + diff --git a/doc/user/functions.xml b/doc/user/functions.xml new file mode 100644 index 0000000..7c96c54 --- /dev/null +++ b/doc/user/functions.xml @@ -0,0 +1,38 @@ + + + + +This appendix contains descriptions of all of the +function and construction environment methods +in this version of &SCons; + + + + + +&functions-gen; + + diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index 16d9389..950bc8a 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -1,6 +1,6 @@ diff --git a/doc/user/main.in b/doc/user/main.in index fbc28df..feb8c25 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -1,7 +1,7 @@ - - Merging Options into the Environment: the &MergeFlags; Function - &mergeflags; - - - Separating Compile Arguments into their Variables: the &ParseFlags; Function - &parseflags; - - - Finding Installed Library Information: the &ParseConfig; Function - &parseconfig; + + Automatically Putting Command-line Options into their Construction Variables + + + This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;. + +
+ Merging Options into the Environment: the &MergeFlags; Function + &mergeflags; +
+
+ Separating Compile Arguments into their Variables: the &ParseFlags; Function + &parseflags; +
+
+ Finding Installed Library Information: the &ParseConfig; Function + &parseconfig; +
+ @@ -341,6 +363,11 @@ &tools; + + Functions and Environment Methods + &functions; + + Handling Common Tasks &tasks; diff --git a/doc/user/main.xml b/doc/user/main.xml index fbc28df..feb8c25 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -1,7 +1,7 @@ - - Merging Options into the Environment: the &MergeFlags; Function - &mergeflags; - - - Separating Compile Arguments into their Variables: the &ParseFlags; Function - &parseflags; - - - Finding Installed Library Information: the &ParseConfig; Function - &parseconfig; + + Automatically Putting Command-line Options into their Construction Variables + + + This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;. + +
+ Merging Options into the Environment: the &MergeFlags; Function + &mergeflags; +
+
+ Separating Compile Arguments into their Variables: the &ParseFlags; Function + &parseflags; +
+
+ Finding Installed Library Information: the &ParseConfig; Function + &parseconfig; +
+ @@ -341,6 +363,11 @@ &tools; + + Functions and Environment Methods + &functions; + + Handling Common Tasks &tasks; diff --git a/doc/user/make.in b/doc/user/make.in index c17b047..7102557 100644 --- a/doc/user/make.in +++ b/doc/user/make.in @@ -1,6 +1,6 @@