diff options
| author | Steven Knight <knight@baldmt.com> | 2005-02-15 13:55:44 (GMT) |
|---|---|---|
| committer | Steven Knight <knight@baldmt.com> | 2005-02-15 13:55:44 (GMT) |
| commit | d809676c50c89f74f3210d4faf61c3f66a600777 (patch) | |
| tree | 18a308eb5aa145b95de56c05aca90a609c3eaaf6 | |
| parent | f995934a8dca09977039d3a9bdb263805c1282b6 (diff) | |
| download | SCons-d809676c50c89f74f3210d4faf61c3f66a600777.zip SCons-d809676c50c89f74f3210d4faf61c3f66a600777.tar.gz SCons-d809676c50c89f74f3210d4faf61c3f66a600777.tar.bz2 | |
Accumulated documentation changes.
182 files changed, 11005 insertions, 735 deletions
diff --git a/bin/SConsDoc.py b/bin/SConsDoc.py new file mode 100644 index 0000000..df28b76 --- /dev/null +++ b/bin/SConsDoc.py @@ -0,0 +1,241 @@ +#!/usr/bin/env python +# +# Module for handling SCons documentation processing. +# +import os.path +import imp +import sys +import xml.sax.handler + +class Item: + def __init__(self, name): + self.name = name + self.sort_name = name.lower() + if self.sort_name[0] == '_': + self.sort_name = self.sort_name[1:] + self.summary = [] + self.uses = None + def cmp_name(self, name): + if name[0] == '_': + name = name[1:] + return name.lower() + def __cmp__(self, other): + return cmp(self.sort_name, other.sort_name) + +class Builder(Item): + pass + +class Tool(Item): + def __init__(self, name): + Item.__init__(self, name) + self.entity = self.name.replace('+', 'X') + +class ConstructionVariable(Item): + pass + +class Chunk: + def __init__(self, tag, body=None): + self.tag = tag + if not body: + body = [] + self.body = body + def __str__(self): + body = ''.join(self.body) + return "<%s>%s</%s>\n" % (self.tag, body, self.tag) + def append(self, data): + self.body.append(data) + +class Summary: + def __init__(self): + self.body = [] + self.collect = [] + def append(self, data): + self.collect.append(data) + def end_para(self): + text = ''.join(self.collect) + paras = text.split('\n\n') + if paras == ['\n']: + return + if paras[0] == '': + self.body.append('\n') + paras = paras[1:] + paras[0] = '\n' + paras[0] + if paras[-1] == '': + paras = paras[:-1] + paras[-1] = paras[-1] + '\n' + last = '\n' + else: + last = None + sep = None + for p in paras: + c = Chunk("para", p) + if sep: + self.body.append(sep) + self.body.append(c) + sep = '\n' + if last: + self.body.append(last) + def begin_chunk(self, chunk): + self.end_para() + self.collect = chunk + def end_chunk(self): + self.body.append(self.collect) + self.collect = [] + +class SConsDocHandler(xml.sax.handler.ContentHandler, + xml.sax.handler.ErrorHandler): + def __init__(self): + self._start_dispatch = {} + self._end_dispatch = {} + keys = self.__class__.__dict__.keys() + start_tag_method_names = filter(lambda k: k[:6] == 'start_', keys) + end_tag_method_names = filter(lambda k: k[:4] == 'end_', keys) + for method_name in start_tag_method_names: + tag = method_name[6:] + self._start_dispatch[tag] = getattr(self, method_name) + for method_name in end_tag_method_names: + tag = method_name[4:] + self._end_dispatch[tag] = getattr(self, method_name) + self.stack = [] + self.collect = [] + self.current_object = [] + self.builders = {} + self.tools = {} + self.cvars = {} + + def startElement(self, name, attrs): + try: + start_element_method = self._start_dispatch[name] + except KeyError: + self.characters('<%s>' % name) + else: + start_element_method(attrs) + + def endElement(self, name): + try: + end_element_method = self._end_dispatch[name] + except KeyError: + self.characters('</%s>' % name) + else: + end_element_method() + + # + # + def characters(self, chars): + self.collect.append(chars) + + def begin_collecting(self, chunk): + self.collect = chunk + def end_collecting(self): + self.collect = [] + + def begin_chunk(self): + pass + def end_chunk(self): + pass + + # + # + # + + def begin_xxx(self, obj): + self.stack.append(self.current_object) + self.current_object = obj + def end_xxx(self): + self.current_object = self.stack.pop() + + # + # + # + def start_scons_doc(self, attrs): + pass + def end_scons_doc(self): + pass + + def start_builder(self, attrs): + name = attrs.get('name') + try: + builder = self.builders[name] + except KeyError: + builder = Builder(name) + self.builders[name] = builder + self.begin_xxx(builder) + def end_builder(self): + self.end_xxx() + + def start_tool(self, attrs): + name = attrs.get('name') + try: + tool = self.tools[name] + except KeyError: + tool = Tool(name) + self.tools[name] = tool + self.begin_xxx(tool) + def end_tool(self): + self.end_xxx() + + def start_cvar(self, attrs): + name = attrs.get('name') + try: + cvar = self.cvars[name] + except KeyError: + cvar = ConstructionVariable(name) + self.cvars[name] = cvar + self.begin_xxx(cvar) + def end_cvar(self): + self.end_xxx() + + def start_summary(self, attrs): + summary = Summary() + self.current_object.summary = summary + self.begin_xxx(summary) + self.begin_collecting(summary) + def end_summary(self): + self.current_object.end_para() + self.end_xxx() + + def start_example(self, attrs): + example = Chunk("programlisting") + self.current_object.begin_chunk(example) + def end_example(self): + self.current_object.end_chunk() + + def start_uses(self, attrs): + self.begin_collecting([]) + def end_uses(self): + self.current_object.uses = ''.join(self.collect).split() + self.end_collecting() + + # Stuff for the ErrorHandler portion. + def error(self, exception): + linenum = exception._linenum - self.preamble_lines + sys.stderr.write('%s:%d:%d: %s (error)\n' % (self.filename, linenum, exception._colnum, ''.join(exception.args))) + + def fatalError(self, exception): + linenum = exception._linenum - self.preamble_lines + sys.stderr.write('%s:%d:%d: %s (fatalError)\n' % (self.filename, linenum, exception._colnum, ''.join(exception.args))) + + def set_file_info(self, filename, preamble_lines): + self.filename = filename + self.preamble_lines = preamble_lines + +# lifted from Ka-Ping Yee's way cool pydoc module. +def importfile(path): + """Import a Python source file or compiled file given its path.""" + magic = imp.get_magic() + file = open(path, 'r') + if file.read(len(magic)) == magic: + kind = imp.PY_COMPILED + else: + kind = imp.PY_SOURCE + file.close() + filename = os.path.basename(path) + name, ext = os.path.splitext(filename) + file = open(path, 'r') + try: + module = imp.load_module(name, file, path, (ext, 'r', kind)) + except ImportError, e: + sys.stderr.write("Could not import %s: %s\n" % (path, e)) + return None + file.close() + return module diff --git a/bin/scons-proc.py b/bin/scons-proc.py new file mode 100644 index 0000000..809c3d0 --- /dev/null +++ b/bin/scons-proc.py @@ -0,0 +1,195 @@ +#!/usr/bin/env python +# +# Process a list of Python and/or XML files containing SCons documentation. +# +# Depending on the options, this script creates DocBook-formatted lists +# of the Builders, Tools or construction variables in generated SGML +# files containing the summary text and/or .mod files contining the +# ENTITY definitions for each item. +# +import getopt +import os.path +import re +import string +import StringIO +import sys +import xml.sax + +import SConsDoc + +base_sys_path = [os.getcwd() + '/build/test-tar-gz/lib/scons'] + sys.path + +helpstr = """\ +Usage: scons-varlist.py [-b .gen,.mod] [-t .gen,.mod] [-v .gen,.mod] [infile] +Options: + -m, --modfile .mod file to hold Builder entities +""" + +opts, args = getopt.getopt(sys.argv[1:], + "b:t:v:", + ['builders=', 'tools=', 'variables=']) + +buildersfiles = None +toolsfiles = None +variablesfiles = None + +for o, a in opts: + if o == '-b' or o == '--builders': + buildersfiles = a + elif o == '-t' or o == '--tools': + toolsfiles = a + elif o == '-v' or o == '--variables': + variablesfiles = a + +h = SConsDoc.SConsDocHandler() +saxparser = xml.sax.make_parser() +saxparser.setContentHandler(h) +saxparser.setErrorHandler(h) + +preamble = """\ +<?xml version="1.0"?> +<scons_doc> +""" + +postamble = """\ +</scons_doc> +""" + +for f in args: + _, ext = os.path.splitext(f) + if ext == '.py': + dir, _ = os.path.split(f) + if dir: + sys.path = [dir] + base_sys_path + module = SConsDoc.importfile(f) + h.set_file_info(f, len(preamble.split('\n'))) + try: + content = module.__scons_doc__ + except AttributeError: + content = None + else: + del module.__scons_doc__ + else: + h.set_file_info(f, len(preamble.split('\n'))) + content = open(f).read() + if content: + content = content.replace('&', '&') + input = preamble + content + postamble + try: + saxparser.parse(StringIO.StringIO(input)) + except: + sys.stderr.write("error in %s\n" % f) + raise + +Warning = """\ +<!-- +THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. +--> +""" + +Regular_Entities_Header = """\ +<!-- + + Regular %s entities. + +--> +""" + +Link_Entities_Header = """\ +<!-- + + Entities that are links to the %s entries in the appendix. + +--> +""" + +class XXX: + def __init__(self, entries, **kw): + values = entries.values() + values.sort() + self.values = values + for k, v in kw.items(): + setattr(self, k, v) + def write_gen(self, filename): + if not filename: + return + f = open(filename, 'w') + for v in self.values: + f.write('\n<varlistentry id="%s%s">\n' % + (self.prefix, self.idfunc(v.name))) + for term in self.termfunc(v.name): + f.write('<term><%s>%s</%s></term>\n' % + (self.tag, term, self.tag)) + f.write('<listitem>\n') + for chunk in v.summary.body: + f.write(str(chunk)) + #if v.uses: + # u = map(lambda x, s: '&%slink-%s;' % (s.prefix, x), v.uses) + # f.write('<para>\n') + # f.write('Uses: ' + ', '.join(u) + '.\n') + # f.write('</para>\n') + f.write('</listitem>\n') + f.write('</varlistentry>\n') + def write_mod(self, filename): + if not filename: + return + f = open(filename, 'w') + f.write(Warning) + f.write('\n') + f.write(Regular_Entities_Header % self.description) + f.write('\n') + for v in self.values: + f.write('<!ENTITY %s%s "<%s>%s</%s>">\n' % + (self.prefix, self.idfunc(v.name), + self.tag, self.entityfunc(v.name), self.tag)) + f.write('\n') + f.write(Warning) + f.write('\n') + f.write(Link_Entities_Header % self.description) + f.write('\n') + for v in self.values: + f.write('<!ENTITY %slink-%s \'<link linkend="%s%s"><%s>%s</%s></link>\'>\n' % + (self.prefix, self.idfunc(v.name), + self.prefix, self.idfunc(v.name), + self.tag, self.entityfunc(v.name), self.tag)) + f.write('\n') + f.write(Warning) + +if buildersfiles: + g = XXX(h.builders, + description = 'builder', + prefix = 'b-', + tag = 'function', + idfunc = lambda x: x, + termfunc = lambda x: [x+'()', 'env.'+x+'()'], + entityfunc = lambda x: x) + + gen, mod = string.split(buildersfiles, ',') + g.write_gen(gen) + g.write_mod(mod) + +if toolsfiles: + g = XXX(h.tools, + description = 'tool', + prefix = 't-', + tag = 'literal', + idfunc = lambda x: string.replace(x, '+', 'X'), + termfunc = lambda x: [x], + entityfunc = lambda x: x) + + gen, mod = string.split(toolsfiles, ',') + g.write_gen(gen) + g.write_mod(mod) + +if variablesfiles: + g = XXX(h.cvars, + description = 'construction variable', + prefix = 'cv-', + tag = 'envar', + idfunc = lambda x: x, + termfunc = lambda x: [x], + entityfunc = lambda x: '$'+x) + + gen, mod = string.split(variablesfiles, ',') + g.write_gen(gen) + g.write_mod(mod) diff --git a/bin/sconsoutput.py b/bin/sconsoutput.py index 3ca8a32..974646c 100644 --- a/bin/sconsoutput.py +++ b/bin/sconsoutput.py @@ -23,7 +23,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # -__revision__ = "src/sconsoutput.py 0.D003 2003/09/22 22:17:34 software" +__revision__ = "/home/scons/sconsoutput/branch.0/baseline/src/sconsoutput.py 0.4.D001 2004/11/27 18:44:37 knight" # # sconsoutput.py - an SGML preprocessor for capturing SCons output @@ -76,14 +76,14 @@ __revision__ = "src/sconsoutput.py 0.D003 2003/09/22 22:17:34 software" # SCons output is generated from the following sort of tag: # # <scons_output example="ex1" os="posix"> -# <command>scons -Q foo</command> -# <command>scons -Q foo</command> +# <scons_output_command>scons -Q foo</scons_output_command> +# <scons_output_command>scons -Q foo</scons_output_command> # </scons_output> # -# You tell it which example to use with the "example" attribute, and -# then give it a list of <command> tags to execute. You can also supply -# an "os" tag, which specifies the type of operating system this example -# is intended to show; if you omit this, default value is "posix". +# You tell it which example to use with the "example" attribute, and then +# give it a list of <scons_output_command> tags to execute. You can also +# supply an "os" tag, which specifies the type of operating system this +# example is intended to show; if you omit this, default value is "posix". # # The generated SGML will show the command line (with the appropriate # command-line prompt for the operating system), execute the command in @@ -194,7 +194,7 @@ import SCons.Action import SCons.Defaults import SCons.Node.FS -platform = '%s' +platform = '%(osname)s' Sep = { 'posix' : '/', @@ -263,6 +263,10 @@ class ToolSurrogate: env[v] = SCons.Action.Action(self.func, strfunction=strfunction, varlist=self.varlist) + def __repr__(self): + # This is for the benefit of printing the 'TOOLS' + # variable through env.Dump(). + return repr(self.tool) def Null(target, source, env): pass @@ -365,7 +369,12 @@ ToolList = { ], } -tools = map(lambda t: apply(ToolSurrogate, t), ToolList[platform]) +toollist = ToolList[platform] +filter_tools = string.split('%(tools)s') +if filter_tools: + toollist = filter(lambda x, ft=filter_tools: x[0] in ft, toollist) + +toollist = map(lambda t: apply(ToolSurrogate, t), toollist) def surrogate_spawn(sh, escape, cmd, args, env): pass @@ -375,7 +384,7 @@ def surrogate_pspawn(sh, escape, cmd, args, env, stdout, stderr): SCons.Defaults.ConstructionEnvironment.update({ 'PLATFORM' : platform, - 'TOOLS' : tools, + 'TOOLS' : toollist, 'SPAWN' : surrogate_spawn, 'PSPAWN' : surrogate_pspawn, }) @@ -384,7 +393,7 @@ SConscript('SConstruct') """ # "Commands" that we will execute in our examples. -def command_scons(args, c, test, osname): +def command_scons(args, c, test, dict): save_vals = {} delete_keys = [] try: @@ -403,7 +412,7 @@ def command_scons(args, c, test, osname): program = scons_py, arguments = '-f - ' + string.join(args), chdir = test.workpath('WORK'), - stdin = Stdin % osname) + stdin = Stdin % dict) os.environ.update(save_vals) for key in delete_keys: del(os.environ[key]) @@ -417,7 +426,7 @@ def command_scons(args, c, test, osname): # sys.stderr.write(err) return lines -def command_touch(args, c, test, osname): +def command_touch(args, c, test, dict): time.sleep(1) for file in args: if not os.path.isabs(file): @@ -427,7 +436,7 @@ def command_touch(args, c, test, osname): os.utime(file, None) return [] -def command_edit(args, c, test, osname): +def command_edit(args, c, test, dict): try: add_string = c.edit[:] except AttributeError: @@ -441,7 +450,7 @@ def command_edit(args, c, test, osname): open(file, 'wb').write(contents + add_string) return [] -def command_ls(args, c, test, osname): +def command_ls(args, c, test, dict): def ls(a): files = os.listdir(a) files = filter(lambda x: x[0] != '.', files) @@ -462,12 +471,12 @@ CommandDict = { 'ls' : command_ls, } -def ExecuteCommand(args, c, t, osname): +def ExecuteCommand(args, c, t, dict): try: func = CommandDict[args[0]] except KeyError: - func = lambda args, c, t, osname: [] - return func(args[1:], c, t, osname) + func = lambda args, c, t, dict: [] + return func(args[1:], c, t, dict) class MySGML(sgmllib.SGMLParser): """A subclass of the standard Python 2.2 sgmllib SGML parser. @@ -647,6 +656,7 @@ class MySGML(sgmllib.SGMLParser): o = Output() o.preserve = None o.os = 'posix' + o.tools = '' o.e = e # Locally-set. for name, value in attrs: @@ -706,11 +716,16 @@ class MySGML(sgmllib.SGMLParser): e = string.replace(c.data, '__ROOT__', t.workpath('ROOT')) args = string.split(e) - lines = ExecuteCommand(args, c, t, o.os) + lines = ExecuteCommand(args, c, t, {'osname':o.os, 'tools':o.tools}) + content = None if c.output: - sys.stdout.write(p + c.output + '\n') + content = c.output elif lines: - sys.stdout.write(p + string.join(lines, '\n' + p) + '\n') + content = string.join(lines, '\n' + p) + if content: + content = string.replace(content, '<', '<') + content = string.replace(content, '>', '>') + sys.stdout.write(p + content + '\n') if o.data[0] == '\n': o.data = o.data[1:] @@ -718,11 +733,11 @@ class MySGML(sgmllib.SGMLParser): delattr(self, 'o') self.afunclist = self.afunclist[:-1] - def start_command(self, attrs): + def start_scons_output_command(self, attrs): try: o = self.o except AttributeError: - self.error("<command> tag outside of <scons_output>") + self.error("<scons_output_command> tag outside of <scons_output>") try: o.prefix except AttributeError: @@ -734,7 +749,7 @@ class MySGML(sgmllib.SGMLParser): o.commandlist.append(c) self.afunclist.append(c.afunc) - def end_command(self): + def end_scons_output_command(self): self.o.data = "" self.afunclist = self.afunclist[:-1] diff --git a/doc/SConscript b/doc/SConscript index 0dd41d1..008f205 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -31,6 +31,10 @@ import string Import('env', 'whereis') +env = env.Copy() + +env.TargetSignatures('content') + build = os.path.join('#build', 'doc') # @@ -97,8 +101,28 @@ def scansgml(node, env, target): return includes s = Scanner(name = 'sgml', function = scansgml, skeys = ['.sgml', '.mod']) + orig_env = env -env = orig_env.Copy(SCANNERS = [s]) +env = orig_env.Copy(SCANNERS = [s], + SCONS_PROC_PY = File('#bin/scons-proc.py').rfile(), + SCONSOUTPUT_PY = File('#bin/sconsoutput.py').rfile()) + +# Fetch the list of files in the build engine that contain +# SCons documentation XML for processing. +def chop(s): return s[:-1] + +# If we ever read doc from __scons_doc__ strings in *.py files again, +# here's how it's done: +#manifest_in = File('#src/engine/MANIFEST.in').rstr() +#manifest_xml_in = File('#src/engine/MANIFEST-xml.in').rstr() +#scons_doc_files = map(chop, open(manifest_in).readlines() +\ +# open(manifest_xml_in).readlines()) +#scons_doc_files = map(lambda x: '#src/engine/'+x, scons_doc_files) +#manifest_in = File('#src/engine/MANIFEST.in').rstr() + +manifest_xml_in = File('#src/engine/MANIFEST-xml.in').rstr() +scons_doc_files = map(chop, open(manifest_xml_in).readlines()) +scons_doc_files = map(lambda x: File('#src/engine/'+x).rstr(), scons_doc_files) if jw: # @@ -127,6 +151,20 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY buildrevision "%s"> """ % (date, ver, rev)) + builders_gen = os.path.join(build, 'user', 'builders.gen') + builders_mod = os.path.join(build, 'user', 'builders.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') + variables_mod = os.path.join(build, 'user', 'variables.mod') + + b = env.Command([builders_gen, builders_mod, + tools_gen, tools_mod, + variables_gen, variables_mod], + scons_doc_files, + "python $SCONS_PROC_PY -b ${TARGETS[0]},${TARGETS[1]} -t ${TARGETS[2]},${TARGETS[3]} -v ${TARGETS[4]},${TARGETS[5]} $SOURCES") + env.Depends(b, "$SCONS_PROC_PY") + # # Each document will live in its own subdirectory. List them here # as hash keys, with a hash of the info to control its build. @@ -138,21 +176,24 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. 'pdf' : 1, 'text' : 0, }, - 'python10' : { - 'htmlindex' : 't1.html', - 'html' : 1, - 'ps' : 1, - 'pdf' : 0, - 'text' : 0, - 'graphics' : [ - 'arch.fig', - 'builder.fig', - 'job-task.fig', - 'node.fig', - 'scanner.fig', - 'sig.fig' - ], - }, + # This doesn't build on all systems, and the document is old + # enough that there's reallyno need to build it every time any + # more, so just comment it out for now. + #'python10' : { + # 'htmlindex' : 't1.html', + # 'html' : 1, + # 'ps' : 1, + # 'pdf' : 0, + # 'text' : 0, + # 'graphics' : [ + # 'arch.fig', + # 'builder.fig', + # 'job-task.fig', + # 'node.fig', + # 'scanner.fig', + # 'sig.fig' + # ], + #}, 'reference' : { 'htmlindex' : 'book1.html', 'html' : 1, @@ -172,6 +213,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. 'SCons-win32-install-3.jpg', 'SCons-win32-install-4.jpg', ], + 'sconsoutput' : 1, }, } @@ -197,14 +239,20 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. manifest = File(os.path.join(doc, 'MANIFEST')).rstr() src_files = map(lambda x: x[:-1], open(manifest).readlines()) + build_doc = docs[doc].get('sconsoutput') and int(ARGUMENTS.get('BUILDDOC', 0)) for s in src_files: - base, ext = os.path.splitext(s) + doc_s = os.path.join(doc, s) + build_s = os.path.join(build, doc, s) + base, ext = os.path.splitext(doc_s) if ext in ['.fig', '.jpg']: - orig_env.Install(os.path.join(build, doc), os.path.join(doc, s)) + orig_env.InstallAs(build_s, doc_s) else: - orig_env.SCons_revision(os.path.join(build, doc, s), - os.path.join(doc, s)) - Local(os.path.join(build, doc, s)) + if build_doc and ext == '.sgml': + env.Command(doc_s, + base + '.in', + "python $SCONSOUTPUT_PY $SOURCE > $TARGET") + orig_env.SCons_revision(build_s, doc_s) + Local(build_s) main = os.path.join(build, doc, 'main.sgml') out = 'main.out' @@ -247,13 +295,18 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. tar_list.extend([html, htmldir]) for g in docs[doc].get('graphics', []): - if g[-4:] == '.fig' and fig2dev: - fig = os.path.join(build, doc, g) - jpg = os.path.join(htmldir, g[:-4] + '.jpg') - env.Command(jpg, fig, - "%s -L jpeg -q 100 $SOURCES $TARGET" % fig2dev) - env.Depends(html, jpg) - Local(jpg) + base, ext = os.path.splitext(g) + if ext == '.fig': + jpg = base + '.jpg' + htmldir_jpg = os.path.join(htmldir, jpg) + if fig2dev: + fig = os.path.join(build, doc, g) + env.Command(htmldir_jpg, fig, + "%s -L jpeg -q 100 $SOURCES $TARGET" % fig2dev) + else: + env.InstallAs(htmldir_jpg, jpg) + env.Depends(html, htmldir_jpg) + Local(htmldir_jpg) else: src = os.path.join(build, doc, g) Local(env.Install(htmldir, src)) @@ -273,12 +326,17 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. tar_list.append(ps) for g in docs[doc].get('graphics', []): - if g[-4:] == '.fig' and fig2dev: - fig = os.path.join(build, doc, g) - eps = os.path.join(build, 'PS', g[:-4] + '.eps') - env.Command(eps, fig, "%s -L eps $SOURCES $TARGET" % fig2dev) - env.Depends(ps, eps) - Local(eps) + base, ext = os.path.splitext(g) + if ext == '.fig': + eps = base + '.eps' + build_eps = os.path.join(build, 'PS', eps) + if fig2dev: + fig = os.path.join(build, doc, g) + env.Command(build_eps, fig, "%s -L eps $SOURCES $TARGET" % fig2dev) + else: + env.InstallAs(build_eps, eps) + env.Depends(ps, build_eps) + Local(build_eps) else: src = os.path.join(build, doc, g) Local(env.Install(htmldir, src)) diff --git a/doc/design/MANIFEST b/doc/design/MANIFEST index 72d78be..3fb99f0 100644 --- a/doc/design/MANIFEST +++ b/doc/design/MANIFEST @@ -11,3 +11,4 @@ issues.sgml main.sgml native.sgml overview.sgml +scons.mod diff --git a/doc/design/copyright.sgml b/doc/design/copyright.sgml index 3f908a4..d73906e 100644 --- a/doc/design/copyright.sgml +++ b/doc/design/copyright.sgml @@ -26,7 +26,7 @@ <blockquote> <para> - Copyright (c) 2001, 2002, 2003 Steven Knight + Copyright (c) 2001 Steven Knight Portions of this document, by the same author, were previously published Copyright 2000 by CodeSourcery LLC, under the Software Carpentry diff --git a/doc/design/main.sgml b/doc/design/main.sgml index 6780d2c..6246a73 100644 --- a/doc/design/main.sgml +++ b/doc/design/main.sgml @@ -26,10 +26,24 @@ <!doctype book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ + <!-- + We haven't updated the design document in ages. + Rather than fool people into thinking that it's + actually up-to-date and reflects the current design, + hard-code the version from back when we last updated it. <!ENTITY % version SYSTEM "../version.sgml"> %version; - + --> + <!ENTITY builddate "2001/12/13 20:55:46"> + <!ENTITY buildversion "0.91"> + <!ENTITY buildrevision "0.01.D177"> + + <!-- + Also freeze the scons.mod DTD extensions + to what they were way back when. <!ENTITY % scons SYSTEM "../scons.mod"> + --> + <!ENTITY % scons SYSTEM "scons.mod"> %scons; <!ENTITY acks SYSTEM "acks.sgml"> diff --git a/doc/design/scons.mod b/doc/design/scons.mod new file mode 100644 index 0000000..58a6576 --- /dev/null +++ b/doc/design/scons.mod @@ -0,0 +1,428 @@ +<!-- + + __COPYRIGHT__ + + An SCons-specific DTD module, for use with SCons DocBook + documentation, that contains names, phrases, acronyms, etc. used + throughout the SCons documentation. + +--> + + + +<!-- + + Other applications that we reference. + +--> + +<!ENTITY Aegis "<application>Aegis</application>"> +<!ENTITY Ant "<application>Ant</application>"> +<!ENTITY Autoconf "<application>Autoconf</application>"> +<!ENTITY Automake "<application>Automake</application>"> +<!ENTITY cc "<application>cc</application>"> +<!ENTITY Cons "<application>Cons</application>"> +<!ENTITY cp "<application>cp</application>"> +<!ENTITY csh "<application>csh</application>"> +<!ENTITY gcc "<application>gcc</application>"> +<!ENTITY Jam "<application>Jam</application>"> +<!ENTITY jar "<application>jar</application>"> +<!ENTITY javac "<application>javac</application>"> +<!ENTITY javah "<application>javah</application>"> +<!ENTITY Make "<application>Make</application>"> +<!ENTITY Makepp "<application>Make++</application>"> +<!ENTITY Python "<application>Python</application>"> +<!ENTITY ranlib "<application>ranlib</application>"> +<!ENTITY rmic "<application>rmic</application>"> +<!ENTITY SCons "<application>SCons</application>"> +<!ENTITY scons "<application>scons</application>"> +<!ENTITY ScCons "<application>ScCons</application>"> +<!ENTITY tar "<application>tar</application>"> +<!ENTITY touch "<application>touch</application>"> +<!ENTITY zip "<application>zip</application>"> + + +<!-- + + Classes. + +--> + +<!ENTITY Action "<classname>Action</classname>"> +<!ENTITY ActionBase "<classname>ActionBase</classname>"> +<!ENTITY CommandAction "<classname>CommandAction</classname>"> +<!ENTITY FunctionAction "<classname>FunctionAction</classname>"> +<!ENTITY ListAction "<classname>ListAction</classname>"> +<!ENTITY Builder "<classname>Builder</classname>"> +<!ENTITY BuilderBase "<classname>BuilderBase</classname>"> +<!ENTITY CompositeBuilder "<classname>CompositeBuilder</classname>"> +<!ENTITY MultiStepBuilder "<classname>MultiStepBuilder</classname>"> +<!ENTITY Job "<classname>Job</classname>"> +<!ENTITY Jobs "<classname>Jobs</classname>"> +<!ENTITY Serial "<classname>Serial</classname>"> +<!ENTITY Parallel "<classname>Parallel</classname>"> +<!ENTITY Node "<classname>Node</classname>"> +<!ENTITY Node_FS "<classname>Node.FS</classname>"> +<!ENTITY Scanner "<classname>Scanner</classname>"> +<!ENTITY Sig "<classname>Sig</classname>"> +<!ENTITY Signature "<classname>Signature</classname>"> +<!ENTITY Taskmaster "<classname>Taskmaster</classname>"> +<!ENTITY TimeStamp "<classname>TimeStamp</classname>"> +<!ENTITY Walker "<classname>Walker</classname>"> +<!ENTITY Wrapper "<classname>Wrapper</classname>"> + + + +<!-- + + Options, command-line. + +--> + +<!ENTITY debug-explain "<literal>--debug=explain</literal>"> +<!ENTITY implicit-cache "<literal>--implicit-cache</literal>"> +<!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>"> +<!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>"> +<!ENTITY Q "<literal>-Q</literal>"> + +<!-- + + Options, SConscript-settable. + +--> + +<!ENTITY implicit_cache "<literal>implicit_cache</literal>"> +<!ENTITY implicit_deps_changed "<literal>implicit_deps_changed</literal>"> +<!ENTITY implicit_deps_unchanged "<literal>implicit_deps_unchanged</literal>"> + + + +<!-- + + File and directory names. + +--> + +<!ENTITY build "<filename>build</filename>"> +<!ENTITY Makefile "<filename>Makefile</filename>"> +<!ENTITY Makefiles "<filename>Makefiles</filename>"> +<!ENTITY SConscript "<filename>SConscript</filename>"> +<!ENTITY SConstruct "<filename>SConstruct</filename>"> +<!ENTITY Sconstruct "<filename>Sconstruct</filename>"> +<!ENTITY sconstruct "<filename>sconstruct</filename>"> +<!ENTITY sconsign "<filename>.sconsign</filename>"> +<!ENTITY src "<filename>src</filename>"> + + + +<!-- + + Methods and functions. This includes functions from both + the Build Engine and the Native Python Interface. + +--> + +<!ENTITY Add "<function>Add</function>"> +<!ENTITY AddOptions "<function>AddOptions</function>"> +<!ENTITY Alias "<function>Alias</function>"> +<!ENTITY Aliases "<function>Aliases</function>"> +<!ENTITY Append "<function>Append</function>"> +<!ENTITY BoolOption "<function>BoolOption</function>"> +<!ENTITY Build "<function>Build</function>"> +<!ENTITY CacheDir "<function>CacheDir</function>"> +<!ENTITY Clean "<function>Clean</function>"> +<!ENTITY Clone "<function>Clone</function>"> +<!ENTITY Command "<function>Command</function>"> +<!ENTITY Configure "<function>Configure</function>"> +<!ENTITY Copy "<function>Copy</function>"> +<!ENTITY Default "<function>Default</function>"> +<!ENTITY DefaultRules "<function>DefaultRules</function>"> +<!ENTITY Depends "<function>Depends</function>"> +<!ENTITY Dir "<function>Dir</function>"> +<!ENTITY Entry "<function>Entry</function>"> +<!ENTITY EnumOption "<function>EnumOption</function>"> +<!ENTITY Environment "<function>Environment</function>"> +<!ENTITY Export "<function>Export</function>"> +<!ENTITY File "<function>File</function>"> +<!ENTITY Finish "<function>Finish</function>"> +<!ENTITY GenerateHelpText "<function>GenerateHelpText</function>"> +<!ENTITY Help "<function>Help</function>"> +<!ENTITY Ignore "<function>Ignore</function>"> +<!ENTITY Import "<function>Import</function>"> +<!ENTITY Install "<function>Install</function>"> +<!ENTITY InstallAs "<function>InstallAs</function>"> +<!ENTITY Link "<function>Link</function>"> +<!ENTITY ListOption "<function>ListOption</function>"> +<!ENTITY Local "<function>Local</function>"> +<!ENTITY Module "<function>Module</function>"> +<!ENTITY Objects "<function>Objects</function>"> +<!ENTITY Options "<function>Options</function>"> +<!ENTITY PackageOption "<function>PackageOption</function>"> +<!ENTITY PathOption "<function>PathOption</function>"> +<!ENTITY Precious "<function>Precious</function>"> +<!ENTITY Prepend "<function>Prepend</function>"> +<!ENTITY Replace "<function>Replace</function>"> +<!ENTITY Repository "<function>Repository</function>"> +<!ENTITY Return "<function>Return</function>"> +<!ENTITY RuleSet "<function>RuleSet</function>"> +<!ENTITY Salt "<function>Salt</function>"> +<!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>"> +<!ENTITY SetContentSignatureType "<function>SetContentSignatureType</function>"> +<!ENTITY SourceSignature "<function>SourceSignature</function>"> +<!ENTITY SourceSignatures "<function>SourceSignatures</function>"> +<!ENTITY Split "<function>Split</function>"> +<!ENTITY TargetSignatures "<function>TargetSignatures</function>"> +<!ENTITY Task "<function>Task</function>"> + +<!-- Environment methods --> +<!ENTITY subst "<function>subst</function>"> + +<!-- Configure context functions --> +<!ENTITY Message "<function>Message</function>"> +<!ENTITY Result "<function>Result</function>"> +<!ENTITY CheckCHeader "<function>CheckCHeader</function>"> +<!ENTITY CheckCXXHeader "<function>CheckCXXHeader</function>"> +<!ENTITY CheckFunc "<function>CheckFunc</function>"> +<!ENTITY CheckHeader "<function>CheckHeader</function>"> +<!ENTITY CheckLib "<function>CheckLib</function>"> +<!ENTITY CheckLibWithHeader "<function>CheckLibWithHeader</function>"> +<!ENTITY CheckType "<function>CheckType</function>"> +<!ENTITY TryAction "<function>TryAction</function>"> +<!ENTITY TryBuild "<function>TryBuild</function>"> +<!ENTITY TryCompile "<function>TryCompile</function>"> +<!ENTITY TryLink "<function>TryLink</function>"> +<!ENTITY TryRun "<function>TryRun</function>"> + +<!-- Python functions --> +<!ENTITY str "<function>str</function>"> +<!ENTITY zipfile "<function>zipfile</function>"> + +<!-- Obsolete, but referenced in old documents. --> +<!ENTITY Cache "<function>Cache</function>"> + + + +<!-- + + Global variables. + +--> + +<!ENTITY ARGUMENTS "<varname>ARGUMENTS</varname>"> +<!ENTITY BUILD_TARGETS "<varname>BUILD_TARGETS</varname>"> +<!ENTITY COMMAND_LINE_TARGETS "<varname>COMMAND_LINE_TARGETS</varname>"> +<!ENTITY DEFAULT_TARGETS "<varname>DEFAULT_TARGETS</varname>"> + + + +<!-- + + Construction variables. + +--> + +<!ENTITY BUILDERMAP "<varname>BUILDERMAP</varname>"> +<!ENTITY BUILDERS "<varname>BUILDERS</varname>"> +<!ENTITY CC "<varname>CC</varname>"> +<!ENTITY CCFLAGS "<varname>CCFLAGS</varname>"> +<!ENTITY CCCOM "<varname>CCCOM</varname>"> +<!ENTITY COLOR "<varname>COLOR</varname>"> +<!ENTITY COLORS "<varname>COLORS</varname>"> +<!ENTITY CONFIG "<varname>CONFIG</varname>"> +<!ENTITY CPPDEFINES "<varname>CPPDEFINES</varname>"> +<!ENTITY ENV "<varname>ENV</varname>"> +<!ENTITY JAVACLASSDIR "<varname>JAVACLASSDIR</varname>"> +<!ENTITY LIBDIRPREFIX "<varname>LIBDIRPREFIX</varname>"> +<!ENTITY LIBDIRSUFFIX "<varname>LIBDIRSUFFIX</varname>"> +<!ENTITY LIBLINKPREFIX "<varname>LIBLINKPREFIX</varname>"> +<!ENTITY LIBLINKSUFFIX "<varname>LIBLINKSUFFIX</varname>"> +<!ENTITY LIBPATH "<varname>LIBPATH</varname>"> +<!ENTITY LIBS "<varname>LIBS</varname>"> +<!ENTITY LINK "<varname>LINK</varname>"> +<!ENTITY LINKCOM "<varname>LINKCOM</varname>"> +<!ENTITY LINKFLAGS "<varname>LINKFLAGS</varname>"> +<!ENTITY RELEASE "<varname>RELEASE</varname>"> +<!ENTITY RELEASE_BUILD "<varname>RELEASE_BUILD</varname>"> +<!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>"> +<!ENTITY SCANNERS "<varname>SCANNERS</varname>"> +<!ENTITY TARFLAGS "<varname>TARFLAGS</varname>"> +<!ENTITY TARSUFFIX "<varname>TARSUFFIX</varname>"> + + + +<!-- + + Environment variables. + +--> + +<!ENTITY PATH "<varname>PATH</varname>"> +<!ENTITY PYTHONPATH "<varname>PYTHONPATH</varname>"> +<!ENTITY SCONSFLAGS "<varname>SCONSFLAGS</varname>"> + + + +<!-- + + Function and method arguments. + +--> + +<!ENTITY allowed_values "<varname>allowed_values</varname>"> +<!ENTITY build_dir "<varname>build_dir</varname>"> +<!ENTITY map "<varname>map</varname>"> +<!ENTITY ignorecase "<varname>ignorecase</varname>"> +<!ENTITY options "<varname>options</varname>"> +<!ENTITY exports "<varname>exports</varname>"> +<!ENTITY source "<varname>source</varname>"> +<!ENTITY target "<varname>target</varname>"> + + + +<!-- + + Values of function and method arguments. + +--> + +<!ENTITY all "<literal>all</literal>"> +<!ENTITY none "<literal>none</literal>"> + + + +<!-- + + Builder and Scanner objects. + +--> + +<!ENTITY BuildDir "<function>BuildDir</function>"> +<!ENTITY CFile "<function>CFile</function>"> +<!ENTITY CXXFile "<function>CXXFile</function>"> +<!ENTITY DVI "<function>DVI</function>"> +<!ENTITY Jar "<function>Jar</function>"> +<!ENTITY Java "<function>Java</function>"> +<!ENTITY JavaH "<function>JavaH</function>"> +<!ENTITY Library "<function>Library</function>"> +<!ENTITY Object "<function>Object</function>"> +<!ENTITY PCH "<function>PCH</function>"> +<!ENTITY PDF "<function>PDF</function>"> +<!ENTITY PostScript "<function>PostScript</function>"> +<!ENTITY Program "<function>Program</function>"> +<!ENTITY RES "<function>RES</function>"> +<!ENTITY RMIC "<function>RMIC</function>"> +<!ENTITY SharedLibrary "<function>SharedLibrary</function>"> +<!ENTITY SharedObject "<function>SharedObject</function>"> +<!ENTITY StaticLibrary "<function>StaticLibrary</function>"> +<!ENTITY StaticObject "<function>StaticObject</function>"> +<!ENTITY Tar "<function>Tar</function>"> +<!ENTITY Zip "<function>Zip</function>"> + +<!-- Obsolete, but referenced in old documents. --> +<!ENTITY MakeBuilder "<function>Make</function>"> + + + +<!-- + + Terms. Define both singular and plural forms in various + case-sensitive combinations for use in titles, in-line, etc. + +--> + +<!ENTITY buildfunc "<literal>builder function</literal>"> +<!ENTITY builder_method "<literal>builder method</literal>"> + +<!ENTITY Configure_Contexts "<literal>Configure Contexts</literal>"> +<!ENTITY configure_context "<literal>configure context</literal>"> + +<!ENTITY ConsEnv "<literal>Construction Environment</literal>"> +<!ENTITY ConsEnvs "<literal>Construction Environments</literal>"> +<!ENTITY Consenv "<literal>Construction environment</literal>"> +<!ENTITY Consenvs "<literal>Construction environments</literal>"> +<!ENTITY consenv "<literal>construction environment</literal>"> +<!ENTITY consenvs "<literal>construction environments</literal>"> + +<!ENTITY ConsVar "<literal>Construction Variable</literal>"> +<!ENTITY ConsVars "<literal>Construction Variables</literal>"> +<!ENTITY Consvar "<literal>Construction variable</literal>"> +<!ENTITY Consvars "<literal>Construction variables</literal>"> +<!ENTITY consvar "<literal>construction variable</literal>"> +<!ENTITY consvars "<literal>construction variables</literal>"> + +<!ENTITY CPPPATH "<literal>CPPPATH</literal>"> + +<!ENTITY Dictionary "<literal>Dictionary</literal>"> + +<!ENTITY Emitter "<literal>Emitter</literal>"> +<!ENTITY emitter "<literal>emitter</literal>"> +<!ENTITY Generator "<literal>Generator</literal>"> +<!ENTITY generator "<literal>generator</literal>"> + +<!ENTITY Nodes "<literal>Nodes</literal>"> + +<!ENTITY signature "<literal>signature</literal>"> +<!ENTITY buildsignature "<literal>build signature</literal>"> + +<!ENTITY true "<literal>true</literal>"> +<!ENTITY false "<literal>false</literal>"> + +<!ENTITY typedef "<literal>typedef</literal>"> + +<!-- + + File and program names used in examples. + +--> + +<!ENTITY bar "<application>bar</application>"> +<!ENTITY common1_c "<filename>common1.c</filename>"> +<!ENTITY common2_c "<filename>common2.c</filename>"> +<!ENTITY custom_py "<filename>custom.py</filename>"> +<!ENTITY goodbye "<application>goodbye</application>"> +<!ENTITY goodbye_o "<filename>goodbye.o</filename>"> +<!ENTITY goodbye_obj "<filename>goodbye.obj</filename>"> +<!ENTITY file_dll "<filename>file.dll</filename>"> +<!ENTITY file_in "<filename>file.in</filename>"> +<!ENTITY file_lib "<filename>file.lib</filename>"> +<!ENTITY file_o "<filename>file.o</filename>"> +<!ENTITY file_obj "<filename>file.obj</filename>"> +<!ENTITY file_out "<filename>file.out</filename>"> +<!ENTITY foo "<application>foo</application>"> +<!ENTITY foo_o "<filename>foo.o</filename>"> +<!ENTITY foo_obj "<filename>foo.obj</filename>"> +<!ENTITY hello "<application>hello</application>"> +<!ENTITY hello_c "<filename>hello.c</filename>"> +<!ENTITY hello_exe "<filename>hello.exe</filename>"> +<!ENTITY hello_h "<filename>hello.h</filename>"> +<!ENTITY hello_o "<filename>hello.o</filename>"> +<!ENTITY hello_obj "<filename>hello.obj</filename>"> +<!ENTITY libfile_a "<filename>libfile_a</filename>"> +<!ENTITY libfile_so "<filename>libfile_so</filename>"> +<!ENTITY new_hello "<application>new_hello</application>"> +<!ENTITY new_hello_exe "<application>new_hello.exe</application>"> +<!ENTITY prog "<filename>prog</filename>"> +<!ENTITY prog1 "<filename>prog1</filename>"> +<!ENTITY prog2 "<filename>prog2</filename>"> +<!ENTITY prog_c "<filename>prog.c</filename>"> +<!ENTITY prog_exe "<filename>prog.exe</filename>"> +<!ENTITY stdio_h "<filename>stdio.h</filename>"> + +<!-- + + Punctuation. + +--> + +<!ENTITY plus "<literal>+</literal>"> +<!ENTITY hash "<literal>#</literal>"> + +<!-- + + Mailing lists + +--> + +<!ENTITY scons-announce "<literal>announce@scons.tigris.org</literal>"> +<!ENTITY scons-devel "<literal>dev@scons.tigris.org</literal>"> +<!ENTITY scons-users "<literal>users@scons.tigris.org</literal>"> diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 690803f..d26abdc 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -31,7 +31,7 @@ .fi .RE .. -.TH SCONS 1 "October 2004" +.TH SCONS 1 "January 2005" .SH NAME scons \- a software construction tool .SH SYNOPSIS @@ -1010,7 +1010,7 @@ have two functions: generate(env, **kw) and exists(env). The .B generate() function -modifies the passed in environment +modifies the passed-in environment to set up variables so that the tool can be executed; it may use any keyword arguments @@ -1293,7 +1293,7 @@ to add a specific flag when compiling one specific object file: .ES -bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR') +bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') env.Program(source = ['foo.c', bar_obj_list, 'main.c']) .EE @@ -1340,7 +1340,7 @@ by passing the Node to the Python-builtin function: .ES -bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR') +bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') print "The path to bar_obj is:", str(bar_obj_list[0]) .EE @@ -4998,6 +4998,10 @@ env = Environment(CXXCOMSTR = "Compiling static object $TARGET") .IP CXXFLAGS General options that are passed to the C++ compiler. +By default, this includes the value of $CCFLAGS, +so that setting $CCFLAGS affects both C and C++ compilation. +If you want to add C++-specific flags, +you must set or override the value of $CXXFLAGS. .IP CXXVERSION The version number of the C++ compiler. @@ -5582,7 +5586,7 @@ target being built. .IP FRAMEWORKSFLAGS On Mac OS X, -frameworks options to be addad at +frameworks options to be added at the end of a command line building a loadable module. @@ -5789,13 +5793,13 @@ General user options passed to the linker for building loadable modules. The prefix used for loadable module file names. On Mac OS X, this is null; on other systems, this is -the same $SHLIBPREFIX. +the same as $SHLIBPREFIX. .IP LDMODULESUFFIX The suffix used for loadable module file names. On Mac OS X, this is null; on other systems, this is -the same $SHLIBSUFFIX. +the same as $SHLIBSUFFIX. .IP LEX The lexical analyzer generator. @@ -5844,7 +5848,7 @@ for specifying libraries to be linked with the resulting target. The value of $_LIBFLAGS is created by appending $LIBLINKPREFIX and $LIBLINKSUFFIX to the beginning and end -of each directory in $LIBS. +of each filename in $LIBS. .IP LIBLINKPREFIX The prefix used to specify a library to link on the linker command line. @@ -5930,7 +5934,7 @@ appending the values of the $LIBLINKPREFIX and $LIBLINKSUFFIX construction variables to the beginning and end -of each directory in $LIBS. +of each filename in $LIBS. Any command lines you define that need the LIBS library list should include $_LIBFLAGS: @@ -5939,6 +5943,26 @@ include $_LIBFLAGS: env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") .EE +.IP +If you add a +File +object to the +LIBS +list, the name of that file will be added to +$_LIBFLAGS, +and thus the link line, as is, without +$LIBLINKPREFIX +or +$LIBLINKSUFFIX. +For example: +.ES +env.Append(LIBS=File('/tmp/mylib.so')) +.EE + +.IP +In all cases, scons will add dependencies from the executable program to +all the libraries in this list. + .IP LIBSUFFIX The suffix used for (static) library file names. A default value is set for each platform @@ -7933,7 +7957,7 @@ which verifies that the specified path is an existing directory; and .BR PathOption.PathIsDirCreate , which verifies that the specified path is a directory, -and will create the specified directory if the path exist. +and will create the specified directory if the path does not exist. You may supply your own .I validator function, @@ -8219,6 +8243,15 @@ env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) env.MakeDirectory('new_directory', []) .EE +Note that the call to the MakeDirectory Builder +needs to specify an empty source list +to make the string represent the builder's target; +without that, it would assume the argument is the source, +and would try to deduce the target name from it, +which in the absence of an automatically-added prefix or suffix +would lead to a matching target and source name +and a circular dependency. + .IP source_factory A factory function that the Builder will use to turn any sources specified as strings into SCons Nodes. @@ -9006,7 +9039,7 @@ ${TARGET.filebase} => file ${TARGET.suffix} => .x ${TARGET.abspath} => /top/dir/sub/dir/file.x -BuildDir('sub/dir','src') +SConscript('src/SConscript', build_dir='sub/dir') $SOURCE => sub/dir/file.x ${SOURCE.srcpath} => src/file.x ${SOURCE.srcdir} => src @@ -9620,36 +9653,32 @@ subdirectory/SConscript: .SS Building Multiple Variants From the Same Source -Use the BuildDir() method to establish +Use the build_dir keyword argument to +the SConscript function to establish one or more separate build directories for -a given source directory, -then use the SConscript() method -to specify the SConscript files -in the build directories: +a given source directory: .ES SConstruct: - ccflags = '-DFOO' - Export("ccflags") - BuildDir('foo', 'src') - SConscript('foo/SConscript') + cppdefines = ['FOO'] + Export("cppdefines") + SConscript('src/SConscript', build_dir='foo') - ccflags = '-DBAR' - Export("ccflags") - BuildDir('bar', 'src') - SConscript('bar/SConscript') + cppdefines = ['BAR'] + Export("cppdefines") + SConscript('src/SConscript', build_dir='bar') src/SConscript: - Import("ccflags") - env = Environment(CCFLAGS = ccflags) + Import("cppdefines") + env = Environment(CPPDEFINES = cppdefines) env.Program(target = 'src', source = 'src.c') .EE Note the use of the Export() method -to set the "ccflags" variable to a different -value for each variant build. +to set the "cppdefines" variable to a different +value each time we call the SConscript function. .SS Hierarchical Build of Two Libraries Linked With a Program diff --git a/doc/python10/MANIFEST b/doc/python10/MANIFEST index 56a94d4..e962e6a 100644 --- a/doc/python10/MANIFEST +++ b/doc/python10/MANIFEST @@ -12,4 +12,5 @@ main.sgml node.fig process.sgml scanner.fig +scons.mod sig.fig diff --git a/doc/python10/arch.eps b/doc/python10/arch.eps new file mode 100644 index 0000000..1fdd51f --- /dev/null +++ b/doc/python10/arch.eps @@ -0,0 +1,134 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/arch.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 218 182 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 182 moveto 0 0 lineto 218 0 lineto 218 182 lineto closepath clip newpath +-215.3 324.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +/Courier-Bold ff 300.00 scf sf +3825 2925 m +gs 1 -1 sc (scons) col0 sh gr +/Times-Roman ff 300.00 scf sf +3825 3225 m +gs 1 -1 sc (Script) col0 sh gr +/Times-Roman ff 300.00 scf sf +5100 4875 m +gs 1 -1 sc (Build Engine) col0 sh gr +/Courier-Bold ff 300.00 scf sf +4200 4875 m +gs 1 -1 sc (SCons) col0 sh gr +% Polyline +7.500 slw +n 3600 4200 m 7200 4200 l 7200 5400 l 3600 5400 l + cp gs col0 s gr +/Courier-Bold ff 300.00 scf sf +4725 4050 m +gs 1 -1 sc (SCons) col0 sh gr +/Times-Roman ff 300.00 scf sf +5625 4050 m +gs 1 -1 sc (API) col0 sh gr +% Polyline +n 3600 2400 m 3600 2400 l 3600 2400 l 3600 2400 l + cp gs col0 s gr +% Polyline +n 3600 2400 m 4800 2400 l 4800 3600 l 3600 3600 l + cp gs col0 s gr +% Polyline +n 3600 3600 m 7200 3600 l 7200 4200 l 3600 4200 l + cp gs col0 s gr +% Polyline + [60] 0 sd +n 6000 3600 m 7200 3600 l 7200 2400 l 6000 2400 l + cp gs col0 s gr [] 0 sd +/Times-Italic ff 300.00 scf sf +6300 2925 m +gs 1 -1 sc (other) col0 sh gr +/Times-Italic ff 300.00 scf sf +6150 3225 m +gs 1 -1 sc (interface) col0 sh gr +$F2psEnd +rs diff --git a/doc/python10/arch.jpg b/doc/python10/arch.jpg Binary files differnew file mode 100644 index 0000000..4e69437 --- /dev/null +++ b/doc/python10/arch.jpg diff --git a/doc/python10/builder.eps b/doc/python10/builder.eps new file mode 100644 index 0000000..db87afc --- /dev/null +++ b/doc/python10/builder.eps @@ -0,0 +1,325 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/builder.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 668 290 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 290 moveto 0 0 lineto 668 0 lineto 668 290 lineto closepath clip newpath +-53.3 342.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/reencdict 12 dict def /ReEncode { reencdict begin +/newcodesandnames exch def /newfontname exch def /basefontname exch def +/basefontdict basefontname findfont def /newfont basefontdict maxlength dict def +basefontdict { exch dup /FID ne { dup /Encoding eq +{ exch dup length array copy newfont 3 1 roll put } +{ exch newfont 3 1 roll put } ifelse } { pop pop } ifelse } forall +newfont /FontName newfontname put newcodesandnames aload pop +128 1 255 { newfont /Encoding get exch /.notdef put } for +newcodesandnames length 2 idiv { newfont /Encoding get 3 1 roll put } repeat +newfontname newfont definefont pop end } def +/isovec [ +8#055 /minus 8#200 /grave 8#201 /acute 8#202 /circumflex 8#203 /tilde +8#204 /macron 8#205 /breve 8#206 /dotaccent 8#207 /dieresis +8#210 /ring 8#211 /cedilla 8#212 /hungarumlaut 8#213 /ogonek 8#214 /caron +8#220 /dotlessi 8#230 /oe 8#231 /OE +8#240 /space 8#241 /exclamdown 8#242 /cent 8#243 /sterling +8#244 /currency 8#245 /yen 8#246 /brokenbar 8#247 /section 8#250 /dieresis +8#251 /copyright 8#252 /ordfeminine 8#253 /guillemotleft 8#254 /logicalnot +8#255 /hyphen 8#256 /registered 8#257 /macron 8#260 /degree 8#261 /plusminus +8#262 /twosuperior 8#263 /threesuperior 8#264 /acute 8#265 /mu 8#266 /paragraph +8#267 /periodcentered 8#270 /cedilla 8#271 /onesuperior 8#272 /ordmasculine +8#273 /guillemotright 8#274 /onequarter 8#275 /onehalf +8#276 /threequarters 8#277 /questiondown 8#300 /Agrave 8#301 /Aacute +8#302 /Acircumflex 8#303 /Atilde 8#304 /Adieresis 8#305 /Aring +8#306 /AE 8#307 /Ccedilla 8#310 /Egrave 8#311 /Eacute +8#312 /Ecircumflex 8#313 /Edieresis 8#314 /Igrave 8#315 /Iacute +8#316 /Icircumflex 8#317 /Idieresis 8#320 /Eth 8#321 /Ntilde 8#322 /Ograve +8#323 /Oacute 8#324 /Ocircumflex 8#325 /Otilde 8#326 /Odieresis 8#327 /multiply +8#330 /Oslash 8#331 /Ugrave 8#332 /Uacute 8#333 /Ucircumflex +8#334 /Udieresis 8#335 /Yacute 8#336 /Thorn 8#337 /germandbls 8#340 /agrave +8#341 /aacute 8#342 /acircumflex 8#343 /atilde 8#344 /adieresis 8#345 /aring +8#346 /ae 8#347 /ccedilla 8#350 /egrave 8#351 /eacute +8#352 /ecircumflex 8#353 /edieresis 8#354 /igrave 8#355 /iacute +8#356 /icircumflex 8#357 /idieresis 8#360 /eth 8#361 /ntilde 8#362 /ograve +8#363 /oacute 8#364 /ocircumflex 8#365 /otilde 8#366 /odieresis 8#367 /divide +8#370 /oslash 8#371 /ugrave 8#372 /uacute 8#373 /ucircumflex +8#374 /udieresis 8#375 /yacute 8#376 /thorn 8#377 /ydieresis] def +/Times-Roman /Times-Roman-iso isovec ReEncode +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 2700 1200 m 4500 1200 l 4500 1800 l 2700 1800 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +2925 1575 m +gs 1 -1 sc (Environment) col0 sh gr +% Polyline +n 2700 2400 m 4500 2400 l 4500 3000 l 2700 3000 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +3600 2775 m +gs 1 -1 sc (BuilderWrapper) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2700 3600 m 4500 3600 l 4500 4200 l 2700 4200 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +3600 3975 m +gs 1 -1 sc (BuilderBase) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 8400 3600 m 9900 3600 l 9900 4200 l 8400 4200 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +9150 3975 m +gs 1 -1 sc (ActionBase) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +4650 5175 m +gs 1 -1 sc (MultiStep-) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +4650 5460 m +gs 1 -1 sc (Builder) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 3900 4800 m 5400 4800 l 5400 5700 l 3900 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +2550 5175 m +gs 1 -1 sc (Composite-) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +2550 5460 m +gs 1 -1 sc (Builder) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 1800 4800 m 3300 4800 l 3300 5700 l 1800 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +7050 5175 m +gs 1 -1 sc (Command) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +7050 5460 m +gs 1 -1 sc (Action) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 6300 4800 m 7800 4800 l 7800 5700 l 6300 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +9150 5460 m +gs 1 -1 sc (Action) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +9150 5175 m +gs 1 -1 sc (Function) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 8400 4800 m 9900 4800 l 9900 5700 l 8400 5700 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +11250 5175 m +gs 1 -1 sc (List) dup sw pop 2 div neg 0 rm col0 sh gr +/Times-Roman-iso ff 240.00 scf sf +11250 5460 m +gs 1 -1 sc (Action) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 10500 4800 m 12000 4800 l 12000 5700 l 10500 5700 l + cp gs col0 s gr +% Polyline +n 900 2400 m 2100 2400 l 2100 3000 l 900 3000 l + cp gs col0 s gr +/Times-Roman-iso ff 240.00 scf sf +1500 2775 m +gs 1 -1 sc (Node) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 3600 4200 m 3525 4350 l 3675 4350 l + cp gs col0 s gr +% Polyline +n 3150 4800 m 3150 4500 l 4050 4500 l + 4050 4800 l gs col0 s gr +% Polyline +n 3600 4350 m + 3600 4500 l gs col0 s gr +% Polyline +n 9150 4200 m 9075 4350 l 9225 4350 l + cp gs col0 s gr +% Polyline +n 7050 4800 m 7050 4500 l 10950 4500 l + 10950 4800 l gs col0 s gr +% Polyline +n 9150 4350 m + 9150 4800 l gs col0 s gr +% Polyline +gs clippath +9885 3870 m 9885 3930 l 10036 3930 l 9916 3900 l 10036 3870 l cp +eoclip +n 11550 4650 m 11550 3900 l + 9900 3900 l gs col0 s gr gr + +% arrowhead +n 10036 3870 m 9916 3900 l 10036 3930 l 10036 3870 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +8415 3930 m 8415 3870 l 8264 3870 l 8384 3900 l 8264 3930 l cp +eoclip +n 4650 3900 m + 8400 3900 l gs col0 s gr gr + +% arrowhead +n 8264 3930 m 8384 3900 l 8264 3870 l 8264 3930 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3930 1785 m 3870 1785 l 3870 1936 l 3900 1816 l 3930 1936 l cp +eoclip +n 3900 2250 m + 3900 1800 l gs col0 s gr gr + +% arrowhead +n 3930 1936 m 3900 1816 l 3870 1936 l 3930 1936 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3270 2415 m 3330 2415 l 3330 2264 l 3300 2384 l 3270 2264 l cp +eoclip +n 3300 1950 m + 3300 2400 l gs col0 s gr gr + +% arrowhead +n 3270 2264 m 3300 2384 l 3330 2264 l 3270 2264 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3570 3615 m 3630 3615 l 3630 3464 l 3600 3584 l 3570 3464 l cp +eoclip +n 3600 3150 m + 3600 3600 l gs col0 s gr gr + +% arrowhead +n 3570 3464 m 3600 3584 l 3630 3464 l 3570 3464 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4380 4185 m 4320 4185 l 4320 4336 l 4350 4216 l 4380 4336 l cp +eoclip +n 4350 4650 m + 4350 4200 l gs col0 s gr gr + +% arrowhead +n 4380 4336 m 4350 4216 l 4320 4336 l 4380 4336 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2880 4185 m 2820 4185 l 2820 4336 l 2850 4216 l 2880 4336 l cp +eoclip +n 2850 4650 m + 2850 4200 l gs col0 s gr gr + +% arrowhead +n 2880 4336 m 2850 4216 l 2820 4336 l 2880 4336 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2715 3930 m 2715 3870 l 2564 3870 l 2684 3900 l 2564 3930 l cp +eoclip +n 1500 3150 m 1500 3900 l + 2700 3900 l gs col0 s gr gr + +% arrowhead +n 2564 3930 m 2684 3900 l 2564 3870 l 2564 3930 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 4650 3900 m 4575 3860 l 4500 3900 l 4575 3940 l + cp gs col0 s gr +% Polyline +n 1500 3000 m 1460 3075 l 1500 3150 l 1540 3075 l + cp gs col0 s gr +% Polyline +n 3600 3000 m 3560 3075 l 3600 3150 l 3640 3075 l + cp gs col0 s gr +% Polyline +n 3300 1800 m 3260 1875 l 3300 1950 l 3340 1875 l + cp gs col0 s gr +% Polyline +n 3900 2250 m 3860 2325 l 3900 2400 l 3940 2325 l + cp gs col0 s gr +% Polyline +n 4350 4650 m 4310 4725 l 4350 4800 l 4390 4725 l + cp gs col0 s gr +% Polyline +n 2850 4650 m 2810 4725 l 2850 4800 l 2890 4725 l + cp gs col0 s gr +% Polyline +n 11550 4650 m 11510 4725 l 11550 4800 l 11590 4725 l + cp gs col0 s gr +% Polyline + [60] 0 sd +n 3600 1200 m + 3600 900 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/builder.jpg b/doc/python10/builder.jpg Binary files differnew file mode 100644 index 0000000..e9085e8 --- /dev/null +++ b/doc/python10/builder.jpg diff --git a/doc/python10/job-task.eps b/doc/python10/job-task.eps new file mode 100644 index 0000000..b3eeaff --- /dev/null +++ b/doc/python10/job-task.eps @@ -0,0 +1,238 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/job-task.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 416 236 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 236 moveto 0 0 lineto 416 0 lineto 416 236 lineto closepath clip newpath +-35.3 342.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 4200 3900 m 5100 3900 l 5100 4500 l 4200 4500 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4650 4275 m +gs 1 -1 sc (Task) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 4200 5100 m 5100 5100 l 5100 5700 l 4200 5700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4650 5475 m +gs 1 -1 sc (Node) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 6300 2100 m 7200 2100 l 7200 2700 l 6300 2700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +6750 2475 m +gs 1 -1 sc (Sig) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 6300 3300 m 7500 3300 l 7500 3900 l 6300 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +6900 3675 m +gs 1 -1 sc (Walker) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 4200 2100 m 5700 2100 l 5700 2700 l 4200 2700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4950 2475 m +gs 1 -1 sc (TaskMaster) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2400 3300 m 3600 3300 l 3600 3900 l 2400 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3000 3675 m +gs 1 -1 sc (Parallel) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 600 3300 m 1800 3300 l 1800 3900 l 600 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1200 3675 m +gs 1 -1 sc (Serial) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 1200 2100 m 3000 2100 l 3000 2700 l 1200 2700 l + cp gs col0 s gr +/Times-Roman ff 255.00 scf sf +2099 2475 m +gs 1 -1 sc (Jobs) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2700 2700 m 2660 2775 l 2700 2850 l 2740 2775 l + cp gs col0 s gr +% Polyline +n 5700 2400 m 5775 2440 l 5850 2400 l 5775 2360 l + cp gs col0 s gr +% Polyline +n 5400 2700 m 5360 2775 l 5400 2850 l 5440 2775 l + cp gs col0 s gr +% Polyline +n 4650 2700 m 4610 2775 l 4650 2850 l 4690 2775 l + cp gs col0 s gr +% Polyline +n 1500 2700 m 1460 2775 l 1500 2850 l 1540 2775 l + cp gs col0 s gr +% Polyline +n 4650 4500 m 4610 4575 l 4650 4650 l 4690 4575 l + cp gs col0 s gr +% Polyline +gs clippath +1470 3315 m 1530 3315 l 1530 3164 l 1500 3284 l 1470 3164 l cp +eoclip +n 1500 2850 m + 1500 3300 l gs col0 s gr gr + +% arrowhead +n 1470 3164 m 1500 3284 l 1530 3164 l 1470 3164 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2670 3315 m 2730 3315 l 2730 3164 l 2700 3284 l 2670 3164 l cp +eoclip +n 2700 2850 m + 2700 3300 l gs col0 s gr gr + +% arrowhead +n 2670 3164 m 2700 3284 l 2730 3164 l 2670 3164 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4620 3915 m 4680 3915 l 4680 3764 l 4650 3884 l 4620 3764 l cp +eoclip +n 4650 2850 m + 4650 3900 l gs col0 s gr gr + +% arrowhead +n 4620 3764 m 4650 3884 l 4680 3764 l 4620 3764 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4620 5115 m 4680 5115 l 4680 4964 l 4650 5084 l 4620 4964 l cp +eoclip +n 4650 4650 m + 4650 5100 l gs col0 s gr gr + +% arrowhead +n 4620 4964 m 4650 5084 l 4680 4964 l 4620 4964 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6315 3630 m 6315 3570 l 6164 3570 l 6284 3600 l 6164 3630 l cp +eoclip +n 5400 2850 m 5400 3600 l + 6300 3600 l gs col0 s gr gr + +% arrowhead +n 6164 3630 m 6284 3600 l 6164 3570 l 6164 3630 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6315 2430 m 6315 2370 l 6164 2370 l 6284 2400 l 6164 2430 l cp +eoclip +n 5850 2400 m + 6300 2400 l gs col0 s gr gr + +% arrowhead +n 6164 2430 m 6284 2400 l 6164 2370 l 6164 2430 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 3000 2400 m 3075 2440 l 3150 2400 l 3075 2360 l + cp gs col0 s gr +% Polyline +gs clippath +4215 2430 m 4215 2370 l 4064 2370 l 4184 2400 l 4064 2430 l cp +eoclip +n 3150 2400 m + 4200 2400 l gs col0 s gr gr + +% arrowhead +n 4064 2430 m 4184 2400 l 4064 2370 l 4064 2430 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 2100 2100 m + 2100 1800 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 4950 2100 m + 4950 1800 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 6750 2100 m + 6750 1800 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/job-task.jpg b/doc/python10/job-task.jpg Binary files differnew file mode 100644 index 0000000..ff3ded0 --- /dev/null +++ b/doc/python10/job-task.jpg diff --git a/doc/python10/main.sgml b/doc/python10/main.sgml index 0708f30..ff1e317 100644 --- a/doc/python10/main.sgml +++ b/doc/python10/main.sgml @@ -26,7 +26,7 @@ <!doctype article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ - <!ENTITY % scons SYSTEM "../scons.mod"> + <!ENTITY % scons SYSTEM "scons.mod"> %scons; <!ENTITY abstract SYSTEM "abstract.sgml"> diff --git a/doc/python10/node.eps b/doc/python10/node.eps new file mode 100644 index 0000000..995235d --- /dev/null +++ b/doc/python10/node.eps @@ -0,0 +1,351 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/node.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 452 362 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 362 moveto 0 0 lineto 452 0 lineto 452 362 lineto closepath clip newpath +0.7 414.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 2700 1200 m 4500 1200 l 4500 1800 l 2700 1800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2925 1575 m +gs 1 -1 sc (Environment) col0 sh gr +% Polyline +n 2700 3600 m 4500 3600 l 4500 4200 l 2700 4200 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3375 3975 m +gs 1 -1 sc (Node) col0 sh gr +% Polyline +n 5700 1800 m 6900 1800 l 6900 2400 l 5700 2400 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +5925 2175 m +gs 1 -1 sc (Walker) col0 sh gr +% Polyline +n 2100 2400 m 3300 2400 l 3300 3000 l 2100 3000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2325 2775 m +gs 1 -1 sc (Builder) col0 sh gr +% Polyline +n 3900 2400 m 5100 2400 l 5100 3000 l 3900 3000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4125 2775 m +gs 1 -1 sc (Scanner) col0 sh gr +% Polyline +n 2400 6300 m 3300 6300 l 3300 6900 l 2400 6900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2700 6675 m +gs 1 -1 sc (Dir) col0 sh gr +% Polyline +n 0 6300 m 900 6300 l 900 6900 l 0 6900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +150 6675 m +gs 1 -1 sc (Entry) col0 sh gr +% Polyline +n 1200 6300 m 2100 6300 l 2100 6900 l 1200 6900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1425 6675 m +gs 1 -1 sc (File) col0 sh gr +% Polyline +n 1050 5100 m 2250 5100 l 2250 5700 l 1050 5700 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1200 5475 m +gs 1 -1 sc (Node.FS) col0 sh gr +% Polyline +n 1650 5700 m 1575 5850 l 1725 5850 l + cp gs col0 s gr +% Polyline +n 450 6300 m 450 6000 l 2700 6000 l + 2700 6300 l gs col0 s gr +% Polyline +n 1650 6300 m + 1650 5850 l gs col0 s gr +% Polyline + [60] 0 sd +n 5100 6300 m 6300 6300 l 6300 6900 l 5100 6900 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +5325 6675 m +gs 1 -1 sc (Record) col0 sh gr +% Polyline + [60] 0 sd +n 6600 6300 m 7500 6300 l 7500 6900 l 6600 6900 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +6750 6675 m +gs 1 -1 sc (Field) col0 sh gr +% Polyline + [60] 0 sd +n 4950 5100 m 6150 5100 l 6150 5700 l 4950 5700 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +5100 5475 m +gs 1 -1 sc (Node.DB) col0 sh gr +% Polyline +n 5550 5700 m 5475 5850 l 5625 5850 l + cp gs col0 s gr +% Polyline + [60] 0 sd +n 4350 6300 m 4350 6000 l 7050 6000 l + 7050 6300 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 5550 5850 m + 5550 6300 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 3900 6300 m 4800 6300 l 4800 6900 l 3900 6900 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +4050 6675 m +gs 1 -1 sc (Table) col0 sh gr +% Polyline +n 5700 3000 m 6900 3000 l 6900 3600 l 5700 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +5850 3375 m +gs 1 -1 sc (Wrapper) col0 sh gr +% Polyline +n 900 1200 m 1800 1200 l 1800 1800 l 900 1800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1200 1575 m +gs 1 -1 sc (FS) col0 sh gr +% Polyline +n 3600 4200 m 3525 4350 l 3675 4350 l + cp gs col0 s gr +% Polyline +n 1800 5100 m 1800 4800 l 5550 4800 l + 5550 5100 l gs col0 s gr +% Polyline +n 3600 4800 m + 3600 4350 l gs col0 s gr +% Polyline +n 4200 1800 m 4160 1875 l 4200 1950 l 4240 1875 l + cp gs col0 s gr +% Polyline +n 3000 6150 m 2960 6225 l 3000 6300 l 3040 6225 l + cp gs col0 s gr +% Polyline +n 6300 3600 m 6260 3675 l 6300 3750 l 6340 3675 l + cp gs col0 s gr +% Polyline +n 6300 2400 m 6260 2475 l 6300 2550 l 6340 2475 l + cp gs col0 s gr +% Polyline +n 3000 4200 m 2960 4275 l 3000 4350 l 3040 4275 l + cp gs col0 s gr +% Polyline +n 4200 3450 m 4160 3525 l 4200 3600 l 4240 3525 l + cp gs col0 s gr +% Polyline +n 3000 3450 m 2960 3525 l 3000 3600 l 3040 3525 l + cp gs col0 s gr +% Polyline +gs clippath +2235 5370 m 2235 5430 l 2386 5430 l 2266 5400 l 2386 5370 l cp +eoclip +n 3000 6150 m 3000 5400 l + 2250 5400 l gs col0 s gr gr + +% arrowhead +n 2386 5370 m 2266 5400 l 2386 5430 l 2386 5370 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +2715 3930 m 2715 3870 l 2564 3870 l 2684 3900 l 2564 3930 l cp +eoclip +n 3000 4350 m 3000 4500 l 1800 4500 l 1800 3900 l + 2700 3900 l gs col0 s gr gr + +% arrowhead +n 2564 3930 m 2684 3900 l 2564 3870 l 2564 3930 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4485 3870 m 4485 3930 l 4636 3930 l 4516 3900 l 4636 3870 l cp +eoclip +n 6300 3750 m 6300 3900 l + 4500 3900 l gs col0 s gr gr + +% arrowhead +n 4636 3870 m 4516 3900 l 4636 3930 l 4636 3870 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4230 2985 m 4170 2985 l 4170 3136 l 4200 3016 l 4230 3136 l cp +eoclip +n 4200 3450 m + 4200 3000 l gs col0 s gr gr + +% arrowhead +n 4230 3136 m 4200 3016 l 4170 3136 l 4230 3136 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3030 2985 m 2970 2985 l 2970 3136 l 3000 3016 l 3030 3136 l cp +eoclip +n 3000 3450 m + 3000 3000 l gs col0 s gr gr + +% arrowhead +n 3030 3136 m 3000 3016 l 2970 3136 l 3030 3136 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 3000 1800 m 2960 1875 l 3000 1950 l 3040 1875 l + cp gs col0 s gr +% Polyline +gs clippath +2970 2415 m 3030 2415 l 3030 2264 l 3000 2384 l 2970 2264 l cp +eoclip +n 3000 1950 m + 3000 2400 l gs col0 s gr gr + +% arrowhead +n 2970 2264 m 3000 2384 l 3030 2264 l 2970 2264 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4170 2415 m 4230 2415 l 4230 2264 l 4200 2384 l 4170 2264 l cp +eoclip +n 4200 1950 m + 4200 2400 l gs col0 s gr gr + +% arrowhead +n 4170 2264 m 4200 2384 l 4230 2264 l 4170 2264 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6270 3015 m 6330 3015 l 6330 2864 l 6300 2984 l 6270 2864 l cp +eoclip +n 6300 2550 m + 6300 3000 l gs col0 s gr gr + +% arrowhead +n 6270 2864 m 6300 2984 l 6330 2864 l 6270 2864 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +4785 6570 m 4785 6630 l 4936 6630 l 4816 6600 l 4936 6570 l cp +eoclip +n 5100 6600 m + 4800 6600 l gs col0 s gr gr + +% arrowhead +n 4936 6570 m 4816 6600 l 4936 6630 l 4936 6570 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +6285 6570 m 6285 6630 l 6436 6630 l 6316 6600 l 6436 6570 l cp +eoclip +n 6600 6600 m + 6300 6600 l gs col0 s gr gr + +% arrowhead +n 6436 6570 m 6316 6600 l 6436 6630 l 6436 6570 l cp gs 0.00 setgray ef gr col0 s +% Polyline +n 1350 1800 m 1310 1875 l 1350 1950 l 1390 1875 l + cp gs col0 s gr +% Polyline +gs clippath +1320 5115 m 1380 5115 l 1380 4964 l 1350 5084 l 1320 4964 l cp +eoclip +n 1350 1950 m + 1350 5100 l gs col0 s gr gr + +% arrowhead +n 1320 4964 m 1350 5084 l 1380 4964 l 1320 4964 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 1350 1200 m + 1350 900 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 3600 1200 m + 3600 900 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/node.jpg b/doc/python10/node.jpg Binary files differnew file mode 100644 index 0000000..98ceb5e --- /dev/null +++ b/doc/python10/node.jpg diff --git a/doc/python10/scanner.eps b/doc/python10/scanner.eps new file mode 100644 index 0000000..35614f8 --- /dev/null +++ b/doc/python10/scanner.eps @@ -0,0 +1,168 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/scanner.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 398 200 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 200 moveto 0 0 lineto 398 0 lineto 398 200 lineto closepath clip newpath +-17.3 360.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 2700 5400 m 4500 5400 l 4500 6000 l 2700 6000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3000 5775 m +gs 1 -1 sc (ProgScanner) col0 sh gr +% Polyline +n 2700 4200 m 4500 4200 l 4500 4800 l 2700 4800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3225 4575 m +gs 1 -1 sc (Scanner) col0 sh gr +% Polyline +n 2700 3000 m 4500 3000 l 4500 3600 l 2700 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +2925 3375 m +gs 1 -1 sc (Environment) col0 sh gr +% Polyline + [60] 0 sd +n 5100 5400 m 6900 5400 l 6900 6000 l 5100 6000 l + cp gs col0 s gr [] 0 sd +/Times-Roman ff 240.00 scf sf +5400 5775 m +gs 1 -1 sc (JavaScanner) col0 sh gr +% Polyline +n 300 5400 m 2100 5400 l 2100 6000 l 300 6000 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +750 5775 m +gs 1 -1 sc (CScanner) col0 sh gr +% Polyline +n 600 3300 m 1500 3300 l 1500 3900 l 600 3900 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +825 3675 m +gs 1 -1 sc (Node) col0 sh gr +% Polyline +n 1200 5400 m 1200 5100 l 6000 5100 l + 6000 5400 l gs col0 s gr +% Polyline +n 3600 4950 m + 3600 5400 l gs col0 s gr +% Polyline +n 3600 4800 m 3525 4950 l 3675 4950 l + cp gs col0 s gr +% Polyline +n 3600 3600 m 3560 3675 l 3600 3750 l 3640 3675 l + cp gs col0 s gr +% Polyline +n 1050 3900 m 1010 3975 l 1050 4050 l 1090 3975 l + cp gs col0 s gr +% Polyline +gs clippath +2715 4530 m 2715 4470 l 2564 4470 l 2684 4500 l 2564 4530 l cp +eoclip +n 1050 4050 m 1050 4500 l + 2700 4500 l gs col0 s gr gr + +% arrowhead +n 2564 4530 m 2684 4500 l 2564 4470 l 2564 4530 l cp gs 0.00 setgray ef gr col0 s +% Polyline +gs clippath +3570 4215 m 3630 4215 l 3630 4064 l 3600 4184 l 3570 4064 l cp +eoclip +n 3600 3750 m + 3600 4200 l gs col0 s gr gr + +% arrowhead +n 3570 4064 m 3600 4184 l 3630 4064 l 3570 4064 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 3600 3000 m + 3600 2700 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/scanner.jpg b/doc/python10/scanner.jpg Binary files differnew file mode 100644 index 0000000..08e5dcb --- /dev/null +++ b/doc/python10/scanner.jpg diff --git a/doc/python10/scons.mod b/doc/python10/scons.mod new file mode 100644 index 0000000..58a6576 --- /dev/null +++ b/doc/python10/scons.mod @@ -0,0 +1,428 @@ +<!-- + + __COPYRIGHT__ + + An SCons-specific DTD module, for use with SCons DocBook + documentation, that contains names, phrases, acronyms, etc. used + throughout the SCons documentation. + +--> + + + +<!-- + + Other applications that we reference. + +--> + +<!ENTITY Aegis "<application>Aegis</application>"> +<!ENTITY Ant "<application>Ant</application>"> +<!ENTITY Autoconf "<application>Autoconf</application>"> +<!ENTITY Automake "<application>Automake</application>"> +<!ENTITY cc "<application>cc</application>"> +<!ENTITY Cons "<application>Cons</application>"> +<!ENTITY cp "<application>cp</application>"> +<!ENTITY csh "<application>csh</application>"> +<!ENTITY gcc "<application>gcc</application>"> +<!ENTITY Jam "<application>Jam</application>"> +<!ENTITY jar "<application>jar</application>"> +<!ENTITY javac "<application>javac</application>"> +<!ENTITY javah "<application>javah</application>"> +<!ENTITY Make "<application>Make</application>"> +<!ENTITY Makepp "<application>Make++</application>"> +<!ENTITY Python "<application>Python</application>"> +<!ENTITY ranlib "<application>ranlib</application>"> +<!ENTITY rmic "<application>rmic</application>"> +<!ENTITY SCons "<application>SCons</application>"> +<!ENTITY scons "<application>scons</application>"> +<!ENTITY ScCons "<application>ScCons</application>"> +<!ENTITY tar "<application>tar</application>"> +<!ENTITY touch "<application>touch</application>"> +<!ENTITY zip "<application>zip</application>"> + + +<!-- + + Classes. + +--> + +<!ENTITY Action "<classname>Action</classname>"> +<!ENTITY ActionBase "<classname>ActionBase</classname>"> +<!ENTITY CommandAction "<classname>CommandAction</classname>"> +<!ENTITY FunctionAction "<classname>FunctionAction</classname>"> +<!ENTITY ListAction "<classname>ListAction</classname>"> +<!ENTITY Builder "<classname>Builder</classname>"> +<!ENTITY BuilderBase "<classname>BuilderBase</classname>"> +<!ENTITY CompositeBuilder "<classname>CompositeBuilder</classname>"> +<!ENTITY MultiStepBuilder "<classname>MultiStepBuilder</classname>"> +<!ENTITY Job "<classname>Job</classname>"> +<!ENTITY Jobs "<classname>Jobs</classname>"> +<!ENTITY Serial "<classname>Serial</classname>"> +<!ENTITY Parallel "<classname>Parallel</classname>"> +<!ENTITY Node "<classname>Node</classname>"> +<!ENTITY Node_FS "<classname>Node.FS</classname>"> +<!ENTITY Scanner "<classname>Scanner</classname>"> +<!ENTITY Sig "<classname>Sig</classname>"> +<!ENTITY Signature "<classname>Signature</classname>"> +<!ENTITY Taskmaster "<classname>Taskmaster</classname>"> +<!ENTITY TimeStamp "<classname>TimeStamp</classname>"> +<!ENTITY Walker "<classname>Walker</classname>"> +<!ENTITY Wrapper "<classname>Wrapper</classname>"> + + + +<!-- + + Options, command-line. + +--> + +<!ENTITY debug-explain "<literal>--debug=explain</literal>"> +<!ENTITY implicit-cache "<literal>--implicit-cache</literal>"> +<!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>"> +<!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>"> +<!ENTITY Q "<literal>-Q</literal>"> + +<!-- + + Options, SConscript-settable. + +--> + +<!ENTITY implicit_cache "<literal>implicit_cache</literal>"> +<!ENTITY implicit_deps_changed "<literal>implicit_deps_changed</literal>"> +<!ENTITY implicit_deps_unchanged "<literal>implicit_deps_unchanged</literal>"> + + + +<!-- + + File and directory names. + +--> + +<!ENTITY build "<filename>build</filename>"> +<!ENTITY Makefile "<filename>Makefile</filename>"> +<!ENTITY Makefiles "<filename>Makefiles</filename>"> +<!ENTITY SConscript "<filename>SConscript</filename>"> +<!ENTITY SConstruct "<filename>SConstruct</filename>"> +<!ENTITY Sconstruct "<filename>Sconstruct</filename>"> +<!ENTITY sconstruct "<filename>sconstruct</filename>"> +<!ENTITY sconsign "<filename>.sconsign</filename>"> +<!ENTITY src "<filename>src</filename>"> + + + +<!-- + + Methods and functions. This includes functions from both + the Build Engine and the Native Python Interface. + +--> + +<!ENTITY Add "<function>Add</function>"> +<!ENTITY AddOptions "<function>AddOptions</function>"> +<!ENTITY Alias "<function>Alias</function>"> +<!ENTITY Aliases "<function>Aliases</function>"> +<!ENTITY Append "<function>Append</function>"> +<!ENTITY BoolOption "<function>BoolOption</function>"> +<!ENTITY Build "<function>Build</function>"> +<!ENTITY CacheDir "<function>CacheDir</function>"> +<!ENTITY Clean "<function>Clean</function>"> +<!ENTITY Clone "<function>Clone</function>"> +<!ENTITY Command "<function>Command</function>"> +<!ENTITY Configure "<function>Configure</function>"> +<!ENTITY Copy "<function>Copy</function>"> +<!ENTITY Default "<function>Default</function>"> +<!ENTITY DefaultRules "<function>DefaultRules</function>"> +<!ENTITY Depends "<function>Depends</function>"> +<!ENTITY Dir "<function>Dir</function>"> +<!ENTITY Entry "<function>Entry</function>"> +<!ENTITY EnumOption "<function>EnumOption</function>"> +<!ENTITY Environment "<function>Environment</function>"> +<!ENTITY Export "<function>Export</function>"> +<!ENTITY File "<function>File</function>"> +<!ENTITY Finish "<function>Finish</function>"> +<!ENTITY GenerateHelpText "<function>GenerateHelpText</function>"> +<!ENTITY Help "<function>Help</function>"> +<!ENTITY Ignore "<function>Ignore</function>"> +<!ENTITY Import "<function>Import</function>"> +<!ENTITY Install "<function>Install</function>"> +<!ENTITY InstallAs "<function>InstallAs</function>"> +<!ENTITY Link "<function>Link</function>"> +<!ENTITY ListOption "<function>ListOption</function>"> +<!ENTITY Local "<function>Local</function>"> +<!ENTITY Module "<function>Module</function>"> +<!ENTITY Objects "<function>Objects</function>"> +<!ENTITY Options "<function>Options</function>"> +<!ENTITY PackageOption "<function>PackageOption</function>"> +<!ENTITY PathOption "<function>PathOption</function>"> +<!ENTITY Precious "<function>Precious</function>"> +<!ENTITY Prepend "<function>Prepend</function>"> +<!ENTITY Replace "<function>Replace</function>"> +<!ENTITY Repository "<function>Repository</function>"> +<!ENTITY Return "<function>Return</function>"> +<!ENTITY RuleSet "<function>RuleSet</function>"> +<!ENTITY Salt "<function>Salt</function>"> +<!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>"> +<!ENTITY SetContentSignatureType "<function>SetContentSignatureType</function>"> +<!ENTITY SourceSignature "<function>SourceSignature</function>"> +<!ENTITY SourceSignatures "<function>SourceSignatures</function>"> +<!ENTITY Split "<function>Split</function>"> +<!ENTITY TargetSignatures "<function>TargetSignatures</function>"> +<!ENTITY Task "<function>Task</function>"> + +<!-- Environment methods --> +<!ENTITY subst "<function>subst</function>"> + +<!-- Configure context functions --> +<!ENTITY Message "<function>Message</function>"> +<!ENTITY Result "<function>Result</function>"> +<!ENTITY CheckCHeader "<function>CheckCHeader</function>"> +<!ENTITY CheckCXXHeader "<function>CheckCXXHeader</function>"> +<!ENTITY CheckFunc "<function>CheckFunc</function>"> +<!ENTITY CheckHeader "<function>CheckHeader</function>"> +<!ENTITY CheckLib "<function>CheckLib</function>"> +<!ENTITY CheckLibWithHeader "<function>CheckLibWithHeader</function>"> +<!ENTITY CheckType "<function>CheckType</function>"> +<!ENTITY TryAction "<function>TryAction</function>"> +<!ENTITY TryBuild "<function>TryBuild</function>"> +<!ENTITY TryCompile "<function>TryCompile</function>"> +<!ENTITY TryLink "<function>TryLink</function>"> +<!ENTITY TryRun "<function>TryRun</function>"> + +<!-- Python functions --> +<!ENTITY str "<function>str</function>"> +<!ENTITY zipfile "<function>zipfile</function>"> + +<!-- Obsolete, but referenced in old documents. --> +<!ENTITY Cache "<function>Cache</function>"> + + + +<!-- + + Global variables. + +--> + +<!ENTITY ARGUMENTS "<varname>ARGUMENTS</varname>"> +<!ENTITY BUILD_TARGETS "<varname>BUILD_TARGETS</varname>"> +<!ENTITY COMMAND_LINE_TARGETS "<varname>COMMAND_LINE_TARGETS</varname>"> +<!ENTITY DEFAULT_TARGETS "<varname>DEFAULT_TARGETS</varname>"> + + + +<!-- + + Construction variables. + +--> + +<!ENTITY BUILDERMAP "<varname>BUILDERMAP</varname>"> +<!ENTITY BUILDERS "<varname>BUILDERS</varname>"> +<!ENTITY CC "<varname>CC</varname>"> +<!ENTITY CCFLAGS "<varname>CCFLAGS</varname>"> +<!ENTITY CCCOM "<varname>CCCOM</varname>"> +<!ENTITY COLOR "<varname>COLOR</varname>"> +<!ENTITY COLORS "<varname>COLORS</varname>"> +<!ENTITY CONFIG "<varname>CONFIG</varname>"> +<!ENTITY CPPDEFINES "<varname>CPPDEFINES</varname>"> +<!ENTITY ENV "<varname>ENV</varname>"> +<!ENTITY JAVACLASSDIR "<varname>JAVACLASSDIR</varname>"> +<!ENTITY LIBDIRPREFIX "<varname>LIBDIRPREFIX</varname>"> +<!ENTITY LIBDIRSUFFIX "<varname>LIBDIRSUFFIX</varname>"> +<!ENTITY LIBLINKPREFIX "<varname>LIBLINKPREFIX</varname>"> +<!ENTITY LIBLINKSUFFIX "<varname>LIBLINKSUFFIX</varname>"> +<!ENTITY LIBPATH "<varname>LIBPATH</varname>"> +<!ENTITY LIBS "<varname>LIBS</varname>"> +<!ENTITY LINK "<varname>LINK</varname>"> +<!ENTITY LINKCOM "<varname>LINKCOM</varname>"> +<!ENTITY LINKFLAGS "<varname>LINKFLAGS</varname>"> +<!ENTITY RELEASE "<varname>RELEASE</varname>"> +<!ENTITY RELEASE_BUILD "<varname>RELEASE_BUILD</varname>"> +<!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>"> +<!ENTITY SCANNERS "<varname>SCANNERS</varname>"> +<!ENTITY TARFLAGS "<varname>TARFLAGS</varname>"> +<!ENTITY TARSUFFIX "<varname>TARSUFFIX</varname>"> + + + +<!-- + + Environment variables. + +--> + +<!ENTITY PATH "<varname>PATH</varname>"> +<!ENTITY PYTHONPATH "<varname>PYTHONPATH</varname>"> +<!ENTITY SCONSFLAGS "<varname>SCONSFLAGS</varname>"> + + + +<!-- + + Function and method arguments. + +--> + +<!ENTITY allowed_values "<varname>allowed_values</varname>"> +<!ENTITY build_dir "<varname>build_dir</varname>"> +<!ENTITY map "<varname>map</varname>"> +<!ENTITY ignorecase "<varname>ignorecase</varname>"> +<!ENTITY options "<varname>options</varname>"> +<!ENTITY exports "<varname>exports</varname>"> +<!ENTITY source "<varname>source</varname>"> +<!ENTITY target "<varname>target</varname>"> + + + +<!-- + + Values of function and method arguments. + +--> + +<!ENTITY all "<literal>all</literal>"> +<!ENTITY none "<literal>none</literal>"> + + + +<!-- + + Builder and Scanner objects. + +--> + +<!ENTITY BuildDir "<function>BuildDir</function>"> +<!ENTITY CFile "<function>CFile</function>"> +<!ENTITY CXXFile "<function>CXXFile</function>"> +<!ENTITY DVI "<function>DVI</function>"> +<!ENTITY Jar "<function>Jar</function>"> +<!ENTITY Java "<function>Java</function>"> +<!ENTITY JavaH "<function>JavaH</function>"> +<!ENTITY Library "<function>Library</function>"> +<!ENTITY Object "<function>Object</function>"> +<!ENTITY PCH "<function>PCH</function>"> +<!ENTITY PDF "<function>PDF</function>"> +<!ENTITY PostScript "<function>PostScript</function>"> +<!ENTITY Program "<function>Program</function>"> +<!ENTITY RES "<function>RES</function>"> +<!ENTITY RMIC "<function>RMIC</function>"> +<!ENTITY SharedLibrary "<function>SharedLibrary</function>"> +<!ENTITY SharedObject "<function>SharedObject</function>"> +<!ENTITY StaticLibrary "<function>StaticLibrary</function>"> +<!ENTITY StaticObject "<function>StaticObject</function>"> +<!ENTITY Tar "<function>Tar</function>"> +<!ENTITY Zip "<function>Zip</function>"> + +<!-- Obsolete, but referenced in old documents. --> +<!ENTITY MakeBuilder "<function>Make</function>"> + + + +<!-- + + Terms. Define both singular and plural forms in various + case-sensitive combinations for use in titles, in-line, etc. + +--> + +<!ENTITY buildfunc "<literal>builder function</literal>"> +<!ENTITY builder_method "<literal>builder method</literal>"> + +<!ENTITY Configure_Contexts "<literal>Configure Contexts</literal>"> +<!ENTITY configure_context "<literal>configure context</literal>"> + +<!ENTITY ConsEnv "<literal>Construction Environment</literal>"> +<!ENTITY ConsEnvs "<literal>Construction Environments</literal>"> +<!ENTITY Consenv "<literal>Construction environment</literal>"> +<!ENTITY Consenvs "<literal>Construction environments</literal>"> +<!ENTITY consenv "<literal>construction environment</literal>"> +<!ENTITY consenvs "<literal>construction environments</literal>"> + +<!ENTITY ConsVar "<literal>Construction Variable</literal>"> +<!ENTITY ConsVars "<literal>Construction Variables</literal>"> +<!ENTITY Consvar "<literal>Construction variable</literal>"> +<!ENTITY Consvars "<literal>Construction variables</literal>"> +<!ENTITY consvar "<literal>construction variable</literal>"> +<!ENTITY consvars "<literal>construction variables</literal>"> + +<!ENTITY CPPPATH "<literal>CPPPATH</literal>"> + +<!ENTITY Dictionary "<literal>Dictionary</literal>"> + +<!ENTITY Emitter "<literal>Emitter</literal>"> +<!ENTITY emitter "<literal>emitter</literal>"> +<!ENTITY Generator "<literal>Generator</literal>"> +<!ENTITY generator "<literal>generator</literal>"> + +<!ENTITY Nodes "<literal>Nodes</literal>"> + +<!ENTITY signature "<literal>signature</literal>"> +<!ENTITY buildsignature "<literal>build signature</literal>"> + +<!ENTITY true "<literal>true</literal>"> +<!ENTITY false "<literal>false</literal>"> + +<!ENTITY typedef "<literal>typedef</literal>"> + +<!-- + + File and program names used in examples. + +--> + +<!ENTITY bar "<application>bar</application>"> +<!ENTITY common1_c "<filename>common1.c</filename>"> +<!ENTITY common2_c "<filename>common2.c</filename>"> +<!ENTITY custom_py "<filename>custom.py</filename>"> +<!ENTITY goodbye "<application>goodbye</application>"> +<!ENTITY goodbye_o "<filename>goodbye.o</filename>"> +<!ENTITY goodbye_obj "<filename>goodbye.obj</filename>"> +<!ENTITY file_dll "<filename>file.dll</filename>"> +<!ENTITY file_in "<filename>file.in</filename>"> +<!ENTITY file_lib "<filename>file.lib</filename>"> +<!ENTITY file_o "<filename>file.o</filename>"> +<!ENTITY file_obj "<filename>file.obj</filename>"> +<!ENTITY file_out "<filename>file.out</filename>"> +<!ENTITY foo "<application>foo</application>"> +<!ENTITY foo_o "<filename>foo.o</filename>"> +<!ENTITY foo_obj "<filename>foo.obj</filename>"> +<!ENTITY hello "<application>hello</application>"> +<!ENTITY hello_c "<filename>hello.c</filename>"> +<!ENTITY hello_exe "<filename>hello.exe</filename>"> +<!ENTITY hello_h "<filename>hello.h</filename>"> +<!ENTITY hello_o "<filename>hello.o</filename>"> +<!ENTITY hello_obj "<filename>hello.obj</filename>"> +<!ENTITY libfile_a "<filename>libfile_a</filename>"> +<!ENTITY libfile_so "<filename>libfile_so</filename>"> +<!ENTITY new_hello "<application>new_hello</application>"> +<!ENTITY new_hello_exe "<application>new_hello.exe</application>"> +<!ENTITY prog "<filename>prog</filename>"> +<!ENTITY prog1 "<filename>prog1</filename>"> +<!ENTITY prog2 "<filename>prog2</filename>"> +<!ENTITY prog_c "<filename>prog.c</filename>"> +<!ENTITY prog_exe "<filename>prog.exe</filename>"> +<!ENTITY stdio_h "<filename>stdio.h</filename>"> + +<!-- + + Punctuation. + +--> + +<!ENTITY plus "<literal>+</literal>"> +<!ENTITY hash "<literal>#</literal>"> + +<!-- + + Mailing lists + +--> + +<!ENTITY scons-announce "<literal>announce@scons.tigris.org</literal>"> +<!ENTITY scons-devel "<literal>dev@scons.tigris.org</literal>"> +<!ENTITY scons-users "<literal>users@scons.tigris.org</literal>"> diff --git a/doc/python10/sig.eps b/doc/python10/sig.eps new file mode 100644 index 0000000..26aabaa --- /dev/null +++ b/doc/python10/sig.eps @@ -0,0 +1,147 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: build/doc/python10/sig.fig +%%Creator: /usr/bin/fig2dev Version 3.2 Patchlevel 3d +%%CreationDate: Sun Jan 2 01:21:05 2005 +%%For: knight@casablanca.home.baldmt.com (Steven Knight) +%%BoundingBox: 0 0 308 128 +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +newpath 0 128 moveto 0 0 lineto 308 0 lineto 308 128 lineto closepath clip newpath +-71.3 288.7 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +% +% Fig objects follow +% +% Polyline +7.500 slw +n 1200 3000 m 2700 3000 l 2700 3600 l 1200 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +1950 3375 m +gs 1 -1 sc (Taskmaster) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 3300 4200 m 4500 4200 l 4500 4800 l 3300 4800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +3900 4575 m +gs 1 -1 sc (MD5) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 5100 4200 m 6300 4200 l 6300 4800 l 5100 4800 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +5700 4575 m +gs 1 -1 sc (TStamp) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 4200 3000 m 5400 3000 l 5400 3600 l 4200 3600 l + cp gs col0 s gr +/Times-Roman ff 240.00 scf sf +4800 3375 m +gs 1 -1 sc (Sig) dup sw pop 2 div neg 0 rm col0 sh gr +% Polyline +n 2700 3300 m 2775 3340 l 2850 3300 l 2775 3260 l + cp gs col0 s gr +% Polyline +n 4800 3600 m 4725 3750 l 4875 3750 l + cp gs col0 s gr +% Polyline +n 3900 4200 m 3900 3900 l 5700 3900 l + 5700 4200 l gs col0 s gr +% Polyline +n 4800 3750 m + 4800 3900 l gs col0 s gr +% Polyline +gs clippath +4215 3330 m 4215 3270 l 4064 3270 l 4184 3300 l 4064 3330 l cp +eoclip +n 2850 3300 m + 4200 3300 l gs col0 s gr gr + +% arrowhead +n 4064 3330 m 4184 3300 l 4064 3270 l 4064 3330 l cp gs 0.00 setgray ef gr col0 s +% Polyline + [60] 0 sd +n 1950 3000 m + 1950 2700 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 4800 3000 m + 4800 2700 l gs col0 s gr [] 0 sd +$F2psEnd +rs diff --git a/doc/python10/sig.jpg b/doc/python10/sig.jpg Binary files differnew file mode 100644 index 0000000..0c7e0df --- /dev/null +++ b/doc/python10/sig.jpg diff --git a/doc/scons.mod b/doc/scons.mod index 897262d..b8b64aa 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -130,6 +130,7 @@ <!ENTITY BoolOption "<function>BoolOption</function>"> <!ENTITY Build "<function>Build</function>"> <!ENTITY CacheDir "<function>CacheDir</function>"> +<!ENTITY Chmod "<function>Chmod</function>"> <!ENTITY Clean "<function>Clean</function>"> <!ENTITY Clone "<function>Clone</function>"> <!ENTITY Command "<function>Command</function>"> @@ -137,15 +138,19 @@ <!ENTITY Copy "<function>Copy</function>"> <!ENTITY Default "<function>Default</function>"> <!ENTITY DefaultRules "<function>DefaultRules</function>"> +<!ENTITY Delete "<function>Delete</function>"> <!ENTITY Depends "<function>Depends</function>"> <!ENTITY Dir "<function>Dir</function>"> +<!ENTITY Dump "<function>Dump</function>"> <!ENTITY Entry "<function>Entry</function>"> <!ENTITY EnumOption "<function>EnumOption</function>"> <!ENTITY Environment "<function>Environment</function>"> +<!ENTITY Execute "<function>Execute</function>"> <!ENTITY Export "<function>Export</function>"> <!ENTITY File "<function>File</function>"> <!ENTITY Finish "<function>Finish</function>"> <!ENTITY GenerateHelpText "<function>GenerateHelpText</function>"> +<!ENTITY GetOption "<function>GetOption</function>"> <!ENTITY Help "<function>Help</function>"> <!ENTITY Ignore "<function>Ignore</function>"> <!ENTITY Import "<function>Import</function>"> @@ -154,10 +159,13 @@ <!ENTITY Link "<function>Link</function>"> <!ENTITY ListOption "<function>ListOption</function>"> <!ENTITY Local "<function>Local</function>"> +<!ENTITY Mkdir "<function>Mkdir</function>"> <!ENTITY Module "<function>Module</function>"> +<!ENTITY Move "<function>Move</function>"> <!ENTITY Objects "<function>Objects</function>"> <!ENTITY Options "<function>Options</function>"> <!ENTITY PackageOption "<function>PackageOption</function>"> +<!ENTITY ParseConfig "<function>ParseConfig</function>"> <!ENTITY PathOption "<function>PathOption</function>"> <!ENTITY PathOption_PathAccept "<function>PathOption.PathAccept</function>"> <!ENTITY PathOption_PathExists "<function>PathOption.PathExists</function>"> @@ -178,6 +186,7 @@ <!ENTITY Split "<function>Split</function>"> <!ENTITY TargetSignatures "<function>TargetSignatures</function>"> <!ENTITY Task "<function>Task</function>"> +<!ENTITY Touch "<function>Touch</function>"> <!-- Environment methods --> <!ENTITY subst "<function>subst</function>"> @@ -198,6 +207,7 @@ <!ENTITY TryLink "<function>TryLink</function>"> <!ENTITY TryRun "<function>TryRun</function>"> + <!-- Python functions --> <!ENTITY str "<function>str</function>"> <!ENTITY zipfile "<function>zipfile</function>"> @@ -227,29 +237,12 @@ --> <!ENTITY BUILDERMAP "<varname>BUILDERMAP</varname>"> -<!ENTITY BUILDERS "<varname>BUILDERS</varname>"> -<!ENTITY CC "<varname>CC</varname>"> -<!ENTITY CCFLAGS "<varname>CCFLAGS</varname>"> -<!ENTITY CCCOM "<varname>CCCOM</varname>"> <!ENTITY COLOR "<varname>COLOR</varname>"> <!ENTITY COLORS "<varname>COLORS</varname>"> <!ENTITY CONFIG "<varname>CONFIG</varname>"> -<!ENTITY CPPDEFINES "<varname>CPPDEFINES</varname>"> -<!ENTITY ENV "<varname>ENV</varname>"> -<!ENTITY JAVACLASSDIR "<varname>JAVACLASSDIR</varname>"> -<!ENTITY LIBDIRPREFIX "<varname>LIBDIRPREFIX</varname>"> -<!ENTITY LIBDIRSUFFIX "<varname>LIBDIRSUFFIX</varname>"> -<!ENTITY LIBLINKPREFIX "<varname>LIBLINKPREFIX</varname>"> -<!ENTITY LIBLINKSUFFIX "<varname>LIBLINKSUFFIX</varname>"> -<!ENTITY LIBPATH "<varname>LIBPATH</varname>"> -<!ENTITY LIBS "<varname>LIBS</varname>"> -<!ENTITY LINK "<varname>LINK</varname>"> -<!ENTITY LINKCOM "<varname>LINKCOM</varname>"> -<!ENTITY LINKFLAGS "<varname>LINKFLAGS</varname>"> <!ENTITY RELEASE "<varname>RELEASE</varname>"> <!ENTITY RELEASE_BUILD "<varname>RELEASE_BUILD</varname>"> <!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>"> -<!ENTITY SCANNERS "<varname>SCANNERS</varname>"> <!ENTITY TARFLAGS "<varname>TARFLAGS</varname>"> <!ENTITY TARSUFFIX "<varname>TARSUFFIX</varname>"> @@ -361,6 +354,9 @@ <!ENTITY Emitter "<literal>Emitter</literal>"> <!ENTITY emitter "<literal>emitter</literal>"> + +<!ENTITY factory "<literal>factory</literal>"> + <!ENTITY Generator "<literal>Generator</literal>"> <!ENTITY generator "<literal>generator</literal>"> diff --git a/doc/user/ENV.in b/doc/user/ENV.in index b1edd81..56d5901 100644 --- a/doc/user/ENV.in +++ b/doc/user/ENV.in @@ -31,7 +31,7 @@ the same external environment that you used to execute &SCons;. Instead, it uses the dictionary - stored in the &ENV; construction variable + stored in the &cv-link-ENV; construction variable as the external environment for executing commands. @@ -62,7 +62,7 @@ If you want to execute any commands--compilers, linkers, etc.--that are not in these default locations, you need to set the &PATH; value - in the &ENV; dictionary + in the &cv-ENV; dictionary in your construction environment. </para> @@ -82,14 +82,14 @@ <para> - Assign a dictionary to the &ENV; + Assign a dictionary to the &cv-ENV; construction variable in this way completely resets the external environment so that the only variable that will be set when external commands are executed will be the &PATH; value. If you want to use the rest of - the values in &ENV; and only + the values in &cv-ENV; and only set the value of &PATH;, the most straightforward way is probably: @@ -146,7 +146,7 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/ENV.sgml b/doc/user/ENV.sgml index c2d7296..aa65ebd 100644 --- a/doc/user/ENV.sgml +++ b/doc/user/ENV.sgml @@ -31,7 +31,7 @@ the same external environment that you used to execute &SCons;. Instead, it uses the dictionary - stored in the &ENV; construction variable + stored in the &cv-link-ENV; construction variable as the external environment for executing commands. @@ -62,7 +62,7 @@ If you want to execute any commands--compilers, linkers, etc.--that are not in these default locations, you need to set the &PATH; value - in the &ENV; dictionary + in the &cv-ENV; dictionary in your construction environment. </para> @@ -82,14 +82,14 @@ <para> - Assign a dictionary to the &ENV; + Assign a dictionary to the &cv-ENV; construction variable in this way completely resets the external environment so that the only variable that will be set when external commands are executed will be the &PATH; value. If you want to use the rest of - the values in &ENV; and only + the values in &cv-ENV; and only set the value of &PATH;, the most straightforward way is probably: @@ -146,7 +146,7 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index e266393..3af2c9c 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -1,6 +1,7 @@ actions.sgml alias.sgml ant.sgml +builders.sgml builders-built-in.sgml builders-commands.sgml builders-writing.sgml @@ -15,6 +16,7 @@ ENV.sgml environments.sgml errors.sgml example.sgml +factories.sgml help.sgml hierarchy.sgml install.sgml @@ -24,8 +26,10 @@ less-simple.sgml main.sgml make.sgml nodes.sgml +parseconfig.sgml precious.sgml preface.sgml +python.sgml repositories.sgml run.sgml scanners.sgml @@ -34,8 +38,10 @@ separate.sgml simple.sgml sourcecode.sgml tasks.sgml +tools.sgml troubleshoot.sgml variants.sgml +variables.sgml SCons-win32-install-1.jpg SCons-win32-install-2.jpg SCons-win32-install-3.jpg diff --git a/doc/user/alias.in b/doc/user/alias.in index d2344a2..686c004 100644 --- a/doc/user/alias.in +++ b/doc/user/alias.in @@ -50,7 +50,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> <para> @@ -95,8 +95,8 @@ </para> <scons_output example="ex2" os="posix"> - <command>scons -Q install-bin</command> - <command>scons -Q install-lib</command> - <command>scons -Q -c __ROOT__/</command> - <command>scons -Q install</command> + <scons_output_command>scons -Q install-bin</scons_output_command> + <scons_output_command>scons -Q install-lib</scons_output_command> + <scons_output_command>scons -Q -c __ROOT__/</scons_output_command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> diff --git a/doc/user/build-install.in b/doc/user/build-install.in index 0f63bd9..763c13e 100644 --- a/doc/user/build-install.in +++ b/doc/user/build-install.in @@ -78,6 +78,12 @@ </para> + <!-- + Robert P.J. Day has suggested using "python -V", + but that's not supported in 1.5.2, so we're going + to leave this as is for now. + --> + <screen> $ <userinput>python</userinput> Python 2.2.2 (#1, Feb 24 2003, 19:13:11) @@ -156,6 +162,7 @@ &SCons; comes in RPM (Red Hat Package Manager) format, pre-built and ready to install on Red Hat Linux, + Fedora Core, or any other Linux distribution that uses RPM. Your distribution may already have an &SCons; RPM built specifically for it; @@ -406,36 +413,6 @@ </para> - <section> - <title>Building and Installing &SCons; Without Administrative Privileges</title> - - <para> - - If you don't have the right privileges to install &SCons; - in a system location, - you can install it in a location of your choosing - by specifying the <literal>--prefix=</literal> option: - - </para> - - <screen> - # <userinput>python setup.py install --prefix=$HOME</userinput> - </screen> - - <para> - - This would install &SCons; in appropriate locations - relative to the user's <literal>$HOME</literal> directory, - the <application>scons</application> script in - <filename>$HOME/bin</filename> - and the build engine in - <filename>$HOME/lib/scons</filename>. - You may, of course, specify any other location you prefer. - - </para> - - </section> - <!-- <section> @@ -487,11 +464,6 @@ or <filename>C:\Python2.2\scons-__VERSION__</filename> directory, for example. - You can also specify <option>--prefix=</option>, - in which case <filename>setup.py</filename> - will install the build engine - in a version-specific directory - relative to the specified prefix. </para> @@ -512,6 +484,82 @@ </section> + <section> + <title>Installing &SCons; in Other Locations</title> + + <para> + + You can install &SCons; in locations other than + the default by specifying the <option>--prefix=</option> option: + + </para> + + <screen> + # <userinput>python setup.py install --prefix=/opt/scons</userinput> + </screen> + + <para> + + This would + install the <application>scons</application> script in + <filename>/opt/scons/bin</filename> + and the build engine in + <filename>/opt/scons/lib/scons</filename>, + + </para> + + <para> + + Note that you can specify both the <option>--prefix=</option> + and the <option>--version-lib</option> options + at the same type, + in which case <filename>setup.py</filename> + will install the build engine + in a version-specific directory + relative to the specified prefix. + Adding <option>--version-lib</option> to the + above example would install the build engine in + <filename>/opt/scons/lib/scons-__VERSION__</filename>. + + </para> + + </section> + + <section> + <title>Building and Installing &SCons; Without Administrative Privileges</title> + + <para> + + If you don't have the right privileges to install &SCons; + in a system location, + simply use the <literal>--prefix=</literal> option + to install it in a location of your choosing. + For example, + to install &SCons; in appropriate locations + relative to the user's <literal>$HOME</literal> directory, + the <application>scons</application> script in + <filename>$HOME/bin</filename> + and the build engine in + <filename>$HOME/lib/scons</filename>, + simply type: + + </para> + + <screen> + $ <userinput>python setup.py install --prefix=$HOME</userinput> + </screen> + + <para> + + You may, of course, specify any other location you prefer, + and may use the <option>--version-lib</option> option + if you would like to install version-specific directories + relative to the specified prefix. + + </para> + + </section> + </section> <!-- diff --git a/doc/user/build-install.sgml b/doc/user/build-install.sgml index 0f63bd9..763c13e 100644 --- a/doc/user/build-install.sgml +++ b/doc/user/build-install.sgml @@ -78,6 +78,12 @@ </para> + <!-- + Robert P.J. Day has suggested using "python -V", + but that's not supported in 1.5.2, so we're going + to leave this as is for now. + --> + <screen> $ <userinput>python</userinput> Python 2.2.2 (#1, Feb 24 2003, 19:13:11) @@ -156,6 +162,7 @@ &SCons; comes in RPM (Red Hat Package Manager) format, pre-built and ready to install on Red Hat Linux, + Fedora Core, or any other Linux distribution that uses RPM. Your distribution may already have an &SCons; RPM built specifically for it; @@ -406,36 +413,6 @@ </para> - <section> - <title>Building and Installing &SCons; Without Administrative Privileges</title> - - <para> - - If you don't have the right privileges to install &SCons; - in a system location, - you can install it in a location of your choosing - by specifying the <literal>--prefix=</literal> option: - - </para> - - <screen> - # <userinput>python setup.py install --prefix=$HOME</userinput> - </screen> - - <para> - - This would install &SCons; in appropriate locations - relative to the user's <literal>$HOME</literal> directory, - the <application>scons</application> script in - <filename>$HOME/bin</filename> - and the build engine in - <filename>$HOME/lib/scons</filename>. - You may, of course, specify any other location you prefer. - - </para> - - </section> - <!-- <section> @@ -487,11 +464,6 @@ or <filename>C:\Python2.2\scons-__VERSION__</filename> directory, for example. - You can also specify <option>--prefix=</option>, - in which case <filename>setup.py</filename> - will install the build engine - in a version-specific directory - relative to the specified prefix. </para> @@ -512,6 +484,82 @@ </section> + <section> + <title>Installing &SCons; in Other Locations</title> + + <para> + + You can install &SCons; in locations other than + the default by specifying the <option>--prefix=</option> option: + + </para> + + <screen> + # <userinput>python setup.py install --prefix=/opt/scons</userinput> + </screen> + + <para> + + This would + install the <application>scons</application> script in + <filename>/opt/scons/bin</filename> + and the build engine in + <filename>/opt/scons/lib/scons</filename>, + + </para> + + <para> + + Note that you can specify both the <option>--prefix=</option> + and the <option>--version-lib</option> options + at the same type, + in which case <filename>setup.py</filename> + will install the build engine + in a version-specific directory + relative to the specified prefix. + Adding <option>--version-lib</option> to the + above example would install the build engine in + <filename>/opt/scons/lib/scons-__VERSION__</filename>. + + </para> + + </section> + + <section> + <title>Building and Installing &SCons; Without Administrative Privileges</title> + + <para> + + If you don't have the right privileges to install &SCons; + in a system location, + simply use the <literal>--prefix=</literal> option + to install it in a location of your choosing. + For example, + to install &SCons; in appropriate locations + relative to the user's <literal>$HOME</literal> directory, + the <application>scons</application> script in + <filename>$HOME/bin</filename> + and the build engine in + <filename>$HOME/lib/scons</filename>, + simply type: + + </para> + + <screen> + $ <userinput>python setup.py install --prefix=$HOME</userinput> + </screen> + + <para> + + You may, of course, specify any other location you prefer, + and may use the <option>--version-lib</option> option + if you would like to install version-specific directories + relative to the specified prefix. + + </para> + + </section> + </section> <!-- diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in index 1c7ed9f..8b0f16f 100644 --- a/doc/user/builders-built-in.in +++ b/doc/user/builders-built-in.in @@ -44,7 +44,7 @@ <para> - As we've seen, the &Program; Builder + As we've seen, the &b-link-Program; Builder is used to build an executable program. The &source; argument is one or more source-code files or object files, @@ -70,9 +70,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $PROGPREFIX + &cv-link-PROGPREFIX; and - $PROGSUFFIX + &cv-link-PROGSUFFIX; construction variables will be appended appropriately. For example: @@ -119,9 +119,9 @@ Two construction variables control what libraries will be linked with the resulting program. - The &LIBS; variable is a list of the names of + The &cv-link-LIBS; variable is a list of the names of libraries that will be linked into any programs, - and the &LIBPATH; variables is a list of + and the &cv-link-LIBPATH; variables is a list of directories that will be searched for the specified libraries. &SCons; will construct the right command-line @@ -151,7 +151,7 @@ </para> <scons_output example="libs" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -161,14 +161,14 @@ </para> <scons_output example="libs" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> - The &LIBS; construction variable + The &cv-LIBS; construction variable is turned into command line options - by appending the &LIBLINKPREFIX; and &LIBLINKSUFFIX; + by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -176,9 +176,9 @@ <para> - The &LIBPATH; construction variable + The &cv-LIBPATH; construction variable is turned into command line options - by appending the &LIBDIRPREFIX; and &LIBDIRSUFFIX; + by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -187,9 +187,9 @@ <para> Other relevant construction variables - include those used by the &Object; + include those used by the &b-link-Object; builders to affect how the - source files specified as input to the &Program; + source files specified as input to the &t-Program; builders are turned into object files; see the next section. @@ -198,10 +198,10 @@ <para> The command line used to control how a program is linked - is specified by the &LINKCOM; construction variable. + is specified by the &cv-link-LINKCOM; construction variable. By default, it uses the - &LINK; construction variable - and the &LINKFLAGS; construction variable. + &cv-link-LINK; construction variable + and the &cv-link-LINKFLAGS; construction variable. </para> @@ -224,7 +224,7 @@ <para> - The &StaticObject; Builder + The &b-link-StaticObject; Builder is used to build an object file suitable for static linking into a program, or for inclusion in a static library. @@ -251,9 +251,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $OBJPREFIX + &cv-link-OBJPREFIX; and - $OBJSUFFIX + &cv-link-OBJSUFFIX; construction variables will be appended appropriately. For example: @@ -303,7 +303,7 @@ <para> - The &SharedObject; Builder + The &b-link-SharedObject; Builder is used to build an object file suitable for shared linking into a program, or for inclusion in a shared library. @@ -330,9 +330,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHOBJPREFIX + &cv-link-SHOBJPREFIX; and - $SHOBJSUFFIX + &cv-link-SHOBJSUFFIX; construction variables will be appended appropriately. For example: @@ -382,7 +382,7 @@ <para> - The &Object; Builder is a synonym for &StaticObject; + The &b-link-Object; Builder is a synonym for &b-link-StaticObject; and is completely equivalent. </para> @@ -406,7 +406,7 @@ <para> - The &StaticLibrary; Builder + The &b-link-StaticLibrary; Builder is used to create a library suitable for static linking into a program. The &source; argument is one or more @@ -425,9 +425,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $LIBPREFIX + &cv-link-LIBPREFIX; and - $LIBSUFFIX + &cv-link-LIBSUFFIX; construction variables will be appended appropriately. For example: @@ -480,7 +480,7 @@ <para> - The &SharedLibrary; Builder + The &b-link-SharedLibrary; Builder is used to create a shared library suitable for linking with a program. The &source; argument is one or more @@ -499,9 +499,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHLIBPREFIX + &cv-link-SHLIBPREFIX; and - $SHLIBSUFFIX + &cv-link-SHLIBSUFFIX; construction variables will be appended appropriately. For example: @@ -554,7 +554,7 @@ <para> - The &Library; Builder is a synonym for &StaticLibrary; + The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; and is completely equivalent. </para> @@ -715,7 +715,7 @@ <para> - The &Tar; Builder object uses the &tar; + The &b-link-Tar; Builder object uses the &tar; utility to create archives of files and/or directory trees: @@ -739,7 +739,7 @@ </scons_example> <scons_output example="ex1" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -748,11 +748,11 @@ is to create a compressed archive using the <option>-z</option> option. This is easily handled by specifying - the value of the &TARFLAGS; variable + the value of the &cv-link-TARFLAGS; variable when you create the construction environment. Note, however, that the <option>-c</option> used to to instruct &tar; to create the archive - is part of the default value of &TARFLAGS;, + is part of the default value of &cv-TARFLAGS;, so you need to set it both options: </para> @@ -768,13 +768,13 @@ </scons_example> <scons_output example="ex2" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> you may also wish to set the value of the - &TARSUFFIX; construction variable + &cv-link-TARSUFFIX; construction variable to your desired suffix for compress &tar; archives, so that &SCons; can append it to the target file name without your having to specify it explicitly: @@ -793,7 +793,7 @@ </scons_example> <scons_output example="ex3" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> </section> @@ -803,7 +803,7 @@ <para> - The &Zip; Builder object creates archives of files + The &b-link-Zip; Builder object creates archives of files and/or directory trees in the ZIP file format. Python versions 1.6 or later contain an internal &zipfile; module @@ -835,7 +835,7 @@ </para> <scons_output example="ex4" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -870,7 +870,7 @@ <para> - The &Java; builder takes one or more input + The &b-link-Java; builder takes one or more input <filename>.java</filename> files and turns them into one or more <filename>.class</filename> files diff --git a/doc/user/builders-built-in.sgml b/doc/user/builders-built-in.sgml index 767e1d2..84877a3 100644 --- a/doc/user/builders-built-in.sgml +++ b/doc/user/builders-built-in.sgml @@ -44,7 +44,7 @@ <para> - As we've seen, the &Program; Builder + As we've seen, the &b-link-Program; Builder is used to build an executable program. The &source; argument is one or more source-code files or object files, @@ -70,9 +70,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $PROGPREFIX + &cv-link-PROGPREFIX; and - $PROGSUFFIX + &cv-link-PROGSUFFIX; construction variables will be appended appropriately. For example: @@ -119,9 +119,9 @@ Two construction variables control what libraries will be linked with the resulting program. - The &LIBS; variable is a list of the names of + The &cv-link-LIBS; variable is a list of the names of libraries that will be linked into any programs, - and the &LIBPATH; variables is a list of + and the &cv-link-LIBPATH; variables is a list of directories that will be searched for the specified libraries. &SCons; will construct the right command-line @@ -164,9 +164,9 @@ <para> - The &LIBS; construction variable + The &cv-LIBS; construction variable is turned into command line options - by appending the &LIBLINKPREFIX; and &LIBLINKSUFFIX; + by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -174,9 +174,9 @@ <para> - The &LIBPATH; construction variable + The &cv-LIBPATH; construction variable is turned into command line options - by appending the &LIBDIRPREFIX; and &LIBDIRSUFFIX; + by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -185,9 +185,9 @@ <para> Other relevant construction variables - include those used by the &Object; + include those used by the &b-link-Object; builders to affect how the - source files specified as input to the &Program; + source files specified as input to the &t-Program; builders are turned into object files; see the next section. @@ -196,10 +196,10 @@ <para> The command line used to control how a program is linked - is specified by the &LINKCOM; construction variable. + is specified by the &cv-link-LINKCOM; construction variable. By default, it uses the - &LINK; construction variable - and the &LINKFLAGS; construction variable. + &cv-link-LINK; construction variable + and the &cv-link-LINKFLAGS; construction variable. </para> @@ -222,7 +222,7 @@ <para> - The &StaticObject; Builder + The &b-link-StaticObject; Builder is used to build an object file suitable for static linking into a program, or for inclusion in a static library. @@ -249,9 +249,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $OBJPREFIX + &cv-link-OBJPREFIX; and - $OBJSUFFIX + &cv-link-OBJSUFFIX; construction variables will be appended appropriately. For example: @@ -301,7 +301,7 @@ <para> - The &SharedObject; Builder + The &b-link-SharedObject; Builder is used to build an object file suitable for shared linking into a program, or for inclusion in a shared library. @@ -328,9 +328,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHOBJPREFIX + &cv-link-SHOBJPREFIX; and - $SHOBJSUFFIX + &cv-link-SHOBJSUFFIX; construction variables will be appended appropriately. For example: @@ -380,7 +380,7 @@ <para> - The &Object; Builder is a synonym for &StaticObject; + The &b-link-Object; Builder is a synonym for &b-link-StaticObject; and is completely equivalent. </para> @@ -404,7 +404,7 @@ <para> - The &StaticLibrary; Builder + The &b-link-StaticLibrary; Builder is used to create a library suitable for static linking into a program. The &source; argument is one or more @@ -423,9 +423,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $LIBPREFIX + &cv-link-LIBPREFIX; and - $LIBSUFFIX + &cv-link-LIBSUFFIX; construction variables will be appended appropriately. For example: @@ -478,7 +478,7 @@ <para> - The &SharedLibrary; Builder + The &b-link-SharedLibrary; Builder is used to create a shared library suitable for linking with a program. The &source; argument is one or more @@ -497,9 +497,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHLIBPREFIX + &cv-link-SHLIBPREFIX; and - $SHLIBSUFFIX + &cv-link-SHLIBSUFFIX; construction variables will be appended appropriately. For example: @@ -552,7 +552,7 @@ <para> - The &Library; Builder is a synonym for &StaticLibrary; + The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; and is completely equivalent. </para> @@ -713,7 +713,7 @@ <para> - The &Tar; Builder object uses the &tar; + The &b-link-Tar; Builder object uses the &tar; utility to create archives of files and/or directory trees: @@ -737,11 +737,11 @@ is to create a compressed archive using the <option>-z</option> option. This is easily handled by specifying - the value of the &TARFLAGS; variable + the value of the &cv-link-TARFLAGS; variable when you create the construction environment. Note, however, that the <option>-c</option> used to to instruct &tar; to create the archive - is part of the default value of &TARFLAGS;, + is part of the default value of &cv-TARFLAGS;, so you need to set it both options: </para> @@ -759,7 +759,7 @@ <para> you may also wish to set the value of the - &TARSUFFIX; construction variable + &cv-link-TARSUFFIX; construction variable to your desired suffix for compress &tar; archives, so that &SCons; can append it to the target file name without your having to specify it explicitly: @@ -784,7 +784,7 @@ <para> - The &Zip; Builder object creates archives of files + The &b-link-Zip; Builder object creates archives of files and/or directory trees in the ZIP file format. Python versions 1.6 or later contain an internal &zipfile; module @@ -844,7 +844,7 @@ <para> - The &Java; builder takes one or more input + The &b-link-Java; builder takes one or more input <filename>.java</filename> files and turns them into one or more <filename>.class</filename> files diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in index f22fbd0..13a5c56 100644 --- a/doc/user/builders-commands.in +++ b/doc/user/builders-commands.in @@ -63,7 +63,7 @@ for a specific action to be executed to build a specific file or files. This looks a lot like the other builders - (like &Program;, &Object;, etc.), + (like &b-link-Program;, &b-link-Object;, etc.), but takes as an additional argument the command to be executed to build the file: @@ -80,14 +80,14 @@ </scons_example> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> This is often more convenient than creating a &Builder; object - and adding it to the &BUILDERS; variable + and adding it to the &cv-link-BUILDERS; variable of a &consenv; </para> @@ -112,5 +112,5 @@ </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> diff --git a/doc/user/builders-commands.sgml b/doc/user/builders-commands.sgml index bef6ded..d2b990a 100644 --- a/doc/user/builders-commands.sgml +++ b/doc/user/builders-commands.sgml @@ -63,7 +63,7 @@ for a specific action to be executed to build a specific file or files. This looks a lot like the other builders - (like &Program;, &Object;, etc.), + (like &b-link-Program;, &b-link-Object;, etc.), but takes as an additional argument the command to be executed to build the file: @@ -76,14 +76,14 @@ <screen> % <userinput>scons -Q</userinput> - sed 's/x/y/' < foo.in > foo.out + sed 's/x/y/' < foo.in > foo.out </screen> <para> This is often more convenient than creating a &Builder; object - and adding it to the &BUILDERS; variable + and adding it to the &cv-link-BUILDERS; variable of a &consenv; </para> diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index afd862b..ebfef5d 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -151,9 +151,9 @@ This functionality could be invoked as in the following example: until it's attached to a &consenv; so that we can call it to arrange for files to be built. - This is done through the &BUILDERS; + This is done through the &cv-link-BUILDERS; &consvar; in an environment. - The &BUILDERS; variable is a Python dictionary + The &cv-BUILDERS; variable is a Python dictionary that maps the names by which you want to call various &Builder; objects to the objects themselves. For example, if we want to call the @@ -202,17 +202,17 @@ This functionality could be invoked as in the following example: </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> - Note, however, that the default &BUILDERS; + Note, however, that the default &cv-BUILDERS; variable in a &consenv; comes with a default set of &Builder; objects already defined: - &Program;, &Library;, etc. - And when we explicitly set the &BUILDERS; variable + &b-link-Program;, &b-link-Library;, etc. + And when we explicitly set the &cv-BUILDERS; variable when we create the &consenv;, the default &Builder;s are no longer part of the environment: @@ -235,14 +235,14 @@ This functionality could be invoked as in the following example: </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> To be able use both our own defined &Builder; objects and the default &Builder; objects in the same &consenv;, - you can either add to the &BUILDERS; variable + you can either add to the &cv-BUILDERS; variable using the &Append; function: </para> @@ -279,7 +279,7 @@ This functionality could be invoked as in the following example: <para> Or you can explicitly set the appropriately-named - key in the &BUILDERS; dictionary: + key in the &cv-BUILDERS; dictionary: </para> @@ -296,12 +296,12 @@ This functionality could be invoked as in the following example: Either way, the same &consenv; can then use both the newly-defined <function>Foo</function> &Builder; - and the default &Program; &Builder;: + and the default &b-link-Program; &Builder;: </para> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -358,7 +358,7 @@ This functionality could be invoked as in the following example: </sconstruct> <scons_output example="ex4"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -499,7 +499,7 @@ This functionality could be invoked as in the following example: </para> <scons_output example="ex5"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -651,7 +651,7 @@ This functionality could be invoked as in the following example: </sconstruct> <scons_output example="ex6"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -716,7 +716,7 @@ This functionality could be invoked as in the following example: </sconstruct> <scons_output example="ex7"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <programlisting> @@ -761,7 +761,7 @@ This functionality could be invoked as in the following example: </scons_example> <scons_output example="ex8"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml index 9b211e2..9085c0e 100644 --- a/doc/user/builders-writing.sgml +++ b/doc/user/builders-writing.sgml @@ -151,9 +151,9 @@ This functionality could be invoked as in the following example: until it's attached to a &consenv; so that we can call it to arrange for files to be built. - This is done through the &BUILDERS; + This is done through the &cv-link-BUILDERS; &consvar; in an environment. - The &BUILDERS; variable is a Python dictionary + The &cv-BUILDERS; variable is a Python dictionary that maps the names by which you want to call various &Builder; objects to the objects themselves. For example, if we want to call the @@ -189,17 +189,17 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo + foobuild < file.input > file.foo </screen> <para> - Note, however, that the default &BUILDERS; + Note, however, that the default &cv-BUILDERS; variable in a &consenv; comes with a default set of &Builder; objects already defined: - &Program;, &Library;, etc. - And when we explicitly set the &BUILDERS; variable + &b-link-Program;, &b-link-Library;, etc. + And when we explicitly set the &cv-BUILDERS; variable when we create the &consenv;, the default &Builder;s are no longer part of the environment: @@ -215,7 +215,7 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - AttributeError: SConsEnvironment instance has no attribute 'Program': + AttributeError: 'SConsEnvironment' object has no attribute 'Program': File "SConstruct", line 4: env.Program('hello.c') </screen> @@ -224,7 +224,7 @@ This functionality could be invoked as in the following example: To be able use both our own defined &Builder; objects and the default &Builder; objects in the same &consenv;, - you can either add to the &BUILDERS; variable + you can either add to the &cv-BUILDERS; variable using the &Append; function: </para> @@ -242,7 +242,7 @@ This functionality could be invoked as in the following example: <para> Or you can explicitly set the appropriately-named - key in the &BUILDERS; dictionary: + key in the &cv-BUILDERS; dictionary: </para> @@ -259,13 +259,13 @@ This functionality could be invoked as in the following example: Either way, the same &consenv; can then use both the newly-defined <function>Foo</function> &Builder; - and the default &Program; &Builder;: + and the default &b-link-Program; &Builder;: </para> <screen> % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo + foobuild < file.input > file.foo cc -c -o hello.o hello.c cc -o hello hello.o </screen> @@ -305,8 +305,8 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - foobuild < file1.input > file1.foo - foobuild < file2.input > file2.foo + foobuild < file1.input > file1.foo + foobuild < file2.input > file2.foo </screen> <para> @@ -578,7 +578,7 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo + foobuild < file.input > file.foo </screen> <para> @@ -665,7 +665,7 @@ This functionality could be invoked as in the following example: </scons_example> <scons_output example="ex8"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/builders.in b/doc/user/builders.in new file mode 100644 index 0000000..2bc139d --- /dev/null +++ b/doc/user/builders.in @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<!-- +<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<refentry id="Command"> + +<refmeta> +<refentrytitle>Command</refentrytitle> +</refmeta> + +<methodsynopsis> + <methodname>env.Command</methodname> + <methodparam>foo</methodparam> + <methodparam>bar</methodparam> +</methodsynopsis> + +</refentry> +--> + +<para> + +This appendix contains descriptions of all of the +Builders that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&builders-gen; + +</variablelist> diff --git a/doc/user/builders.sgml b/doc/user/builders.sgml new file mode 100644 index 0000000..2bc139d --- /dev/null +++ b/doc/user/builders.sgml @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<!-- +<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<refentry id="Command"> + +<refmeta> +<refentrytitle>Command</refentrytitle> +</refmeta> + +<methodsynopsis> + <methodname>env.Command</methodname> + <methodparam>foo</methodparam> + <methodparam>bar</methodparam> +</methodsynopsis> + +</refentry> +--> + +<para> + +This appendix contains descriptions of all of the +Builders that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&builders-gen; + +</variablelist> diff --git a/doc/user/caching.in b/doc/user/caching.in index 552f3c1..0195c43 100644 --- a/doc/user/caching.in +++ b/doc/user/caching.in @@ -93,9 +93,9 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -129,9 +129,9 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q --cache-show</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q --cache-show</scons_output_command> </scons_output> <para> @@ -176,11 +176,11 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q --cache-disable</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q --cache-disable</scons_output_command> </scons_output> </section> @@ -217,12 +217,12 @@ </para> <scons_output example="ex1"> - <command>scons -Q --cache-disable</command> - <command>scons -Q -c</command> - <command>scons -Q --cache-disable</command> - <command>scons -Q --cache-force</command> - <command>scons -Q -c</command> - <command>scons -Q</command> + <scons_output_command>scons -Q --cache-disable</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q --cache-disable</scons_output_command> + <scons_output_command>scons -Q --cache-force</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/command-line.in b/doc/user/command-line.in index f23755f..b444d30 100644 --- a/doc/user/command-line.in +++ b/doc/user/command-line.in @@ -78,9 +78,9 @@ </scons_example> <scons_output example="SCONSFLAGS"> - <command>scons</command> - <command>export SCONSFLAGS="-Q"</command> - <command environment="SCONSFLAGS=-Q">scons</command> + <scons_output_command>scons</scons_output_command> + <scons_output_command>export SCONSFLAGS="-Q"</scons_output_command> + <scons_output_command environment="SCONSFLAGS=-Q">scons</scons_output_command> </scons_output> <para> @@ -147,8 +147,8 @@ </para> <scons_output example="COMMAND_LINE_TARGETS"> - <command>scons -Q</command> - <command>scons -Q bar</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q bar</scons_output_command> </scons_output> <para> @@ -209,9 +209,9 @@ </para> <scons_output example="Default1"> - <command>scons -Q</command> - <command>scons -Q</command> - <command>scons -Q goodbye</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q goodbye</scons_output_command> </scons_output> <para> @@ -226,7 +226,7 @@ </para> <scons_output example="Default1"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -285,8 +285,8 @@ </para> <scons_output example="Default2"> - <command>scons -Q</command> - <command>scons -Q .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -327,9 +327,9 @@ </para> <scons_output example="Default3"> - <command>scons -Q</command> - <command>scons -Q</command> - <command>scons -Q .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -363,8 +363,8 @@ </para> <scons_output example="Default4"> - <command>scons -Q</command> - <command>scons -Q .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <section> @@ -408,7 +408,7 @@ </para> <scons_output example="DEFAULT_TARGETS_1"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -444,7 +444,7 @@ </para> <scons_output example="DEFAULT_TARGETS_2"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -537,9 +537,9 @@ </para> <scons_output example="BUILD_TARGETS_1"> - <command>scons -Q</command> - <command>scons -Q prog2</command> - <command>scons -Q -c .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q prog2</scons_output_command> + <scons_output_command>scons -Q -c .</scons_output_command> </scons_output> </section> @@ -587,7 +587,7 @@ <para> - The following code sets the &CCFLAGS; construction + The following code sets the &cv-link-CCFLAGS; construction variable in response to the <varname>debug</varname> flag being set in the &ARGUMENTS; dictionary: @@ -616,10 +616,10 @@ </para> <scons_output example="ARGUMENTS"> - <command>scons -Q debug=0</command> - <command>scons -Q debug=0</command> - <command>scons -Q debug=1</command> - <command>scons -Q debug=1</command> + <scons_output_command>scons -Q debug=0</scons_output_command> + <scons_output_command>scons -Q debug=0</scons_output_command> + <scons_output_command>scons -Q debug=1</scons_output_command> + <scons_output_command>scons -Q debug=1</scons_output_command> </scons_output> <para> @@ -668,7 +668,7 @@ to pass the value to the C compiler. Here's how you might do that by setting the appropriate value in a dictionary for the - &CPPDEFINES; construction variable: + &cv-link-CPPDEFINES; construction variable: </para> @@ -718,7 +718,7 @@ </para> <scons_output example="Options1"> - <command>scons -Q RELEASE=1</command> + <scons_output_command>scons -Q RELEASE=1</scons_output_command> </scons_output> </section> @@ -763,7 +763,7 @@ </para> <scons_output example="Options_Help"> - <command>scons -Q -h</command> + <scons_output_command>scons -Q -h</scons_output_command> </scons_output> <para> @@ -835,7 +835,7 @@ </para> <scons_output example="Options_custom_py_1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -872,7 +872,7 @@ </para> <scons_output example="Options_custom_py_2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -940,11 +940,11 @@ </para> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=yes foo.o</command> + <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command> </scons_output> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=t foo.o</command> + <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command> </scons_output> <para> @@ -969,11 +969,11 @@ </para> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=no foo.o</command> + <scons_output_command>scons -Q RELEASE=no foo.o</scons_output_command> </scons_output> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=f foo.o</command> + <scons_output_command>scons -Q RELEASE=f foo.o</scons_output_command> </scons_output> <para> @@ -996,7 +996,7 @@ </para> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=bad_value foo.o</command> + <scons_output_command>scons -Q RELEASE=bad_value foo.o</scons_output_command> </scons_output> </section> @@ -1043,9 +1043,9 @@ </para> <scons_output example="EnumOption"> - <command>scons -Q COLOR=red foo.o</command> - <command>scons -Q COLOR=blue foo.o</command> - <command>scons -Q COLOR=green foo.o</command> + <scons_output_command>scons -Q COLOR=red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=blue foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command> </scons_output> <para> @@ -1058,7 +1058,7 @@ </para> <scons_output example="EnumOption"> - <command>scons -Q COLOR=magenta foo.o</command> + <scons_output_command>scons -Q COLOR=magenta foo.o</scons_output_command> </scons_output> <para> @@ -1101,7 +1101,7 @@ </para> <scons_output example="EnumOption_map"> - <command>scons -Q COLOR=navy foo.o</command> + <scons_output_command>scons -Q COLOR=navy foo.o</scons_output_command> </scons_output> <para> @@ -1115,9 +1115,9 @@ </para> <scons_output example="EnumOption"> - <command>scons -Q COLOR=Red foo.o</command> - <command>scons -Q COLOR=BLUE foo.o</command> - <command>scons -Q COLOR=nAvY foo.o</command> + <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command> </scons_output> <para> @@ -1153,10 +1153,10 @@ </para> <scons_output example="EnumOption_ic1"> - <command>scons -Q COLOR=Red foo.o</command> - <command>scons -Q COLOR=BLUE foo.o</command> - <command>scons -Q COLOR=nAvY foo.o</command> - <command>scons -Q COLOR=green foo.o</command> + <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command> </scons_output> <para> @@ -1198,9 +1198,9 @@ </para> <scons_output example="EnumOption_ic2"> - <command>scons -Q COLOR=Red foo.o</command> - <command>scons -Q COLOR=nAvY foo.o</command> - <command>scons -Q COLOR=GREEN foo.o</command> + <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=GREEN foo.o</scons_output_command> </scons_output> </section> @@ -1243,8 +1243,8 @@ </para> <scons_output example="ListOption"> - <command>scons -Q COLORS=red,blue foo.o</command> - <command>scons -Q COLORS=blue,green,red foo.o</command> + <scons_output_command>scons -Q COLORS=red,blue foo.o</scons_output_command> + <scons_output_command>scons -Q COLORS=blue,green,red foo.o</scons_output_command> </scons_output> <para> @@ -1258,8 +1258,8 @@ </para> <scons_output example="ListOption"> - <command>scons -Q COLORS=all foo.o</command> - <command>scons -Q COLORS=none foo.o</command> + <scons_output_command>scons -Q COLORS=all foo.o</scons_output_command> + <scons_output_command>scons -Q COLORS=none foo.o</scons_output_command> </scons_output> <para> @@ -1270,7 +1270,7 @@ </para> <scons_output example="ListOption"> - <command>scons -Q COLORS=magenta foo.o</command> + <scons_output_command>scons -Q COLORS=magenta foo.o</scons_output_command> </scons_output> </section> @@ -1320,8 +1320,8 @@ </para> <scons_output example="PathOption"> - <command>scons -Q foo.o</command> - <command>scons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o</command> + <scons_output_command>scons -Q foo.o</scons_output_command> + <scons_output_command>scons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o</scons_output_command> </scons_output> <para> @@ -1333,7 +1333,7 @@ </para> <scons_output example="PathOption"> - <command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</command> + <scons_output_command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</scons_output_command> </scons_output> <para> @@ -1500,10 +1500,10 @@ </para> <scons_output example="PackageOption"> - <command>scons -Q foo.o</command> - <command>scons -Q PACKAGE=__ROOT__/usr/local/location foo.o</command> - <command>scons -Q PACKAGE=yes foo.o</command> - <command>scons -Q PACKAGE=no foo.o</command> + <scons_output_command>scons -Q foo.o</scons_output_command> + <scons_output_command>scons -Q PACKAGE=__ROOT__/usr/local/location foo.o</scons_output_command> + <scons_output_command>scons -Q PACKAGE=yes foo.o</scons_output_command> + <scons_output_command>scons -Q PACKAGE=no foo.o</scons_output_command> </scons_output> </section> diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml index 70658e0..565d9f8 100644 --- a/doc/user/command-line.sgml +++ b/doc/user/command-line.sgml @@ -568,7 +568,7 @@ <para> - The following code sets the &CCFLAGS; construction + The following code sets the &cv-link-CCFLAGS; construction variable in response to the <varname>debug</varname> flag being set in the &ARGUMENTS; dictionary: @@ -650,7 +650,7 @@ to pass the value to the C compiler. Here's how you might do that by setting the appropriate value in a dictionary for the - &CPPDEFINES; construction variable: + &cv-link-CPPDEFINES; construction variable: </para> diff --git a/doc/user/depends.in b/doc/user/depends.in index ab422b6..0262924 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -67,8 +67,8 @@ operating system on which the build is performed (as reported by C<uname </scons_example> <scons_output example="ex1" os="posix"> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -83,8 +83,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -132,9 +132,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command>touch hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>touch hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -154,9 +154,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -209,9 +209,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex2" os="posix"> - <command>scons -Q hello</command> - <command>touch hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>touch hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> </section> @@ -252,9 +252,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -339,9 +339,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex3" os="posix"> - <command>scons -Q hello</command> - <command output=" [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -364,7 +364,7 @@ operating system on which the build is performed (as reported by C<uname </section> <section> - <title>Implicit Dependencies: The &CPPPATH; Construction Variable</title> + <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> @@ -415,7 +415,7 @@ operating system on which the build is performed (as reported by C<uname <para> - The &CPPPATH; value + The &cv-CPPPATH; value tells &SCons; to look in the current directory (<literal>'.'</literal>) for any files included by C source files @@ -425,17 +425,17 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex4" os="posix"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> First, notice that &SCons; added the <literal>-I.</literal> argument - from the &CPPPATH; variable + from the &cv-CPPPATH; variable so that the compilation would find the &hello_h; file in the local directory. @@ -462,8 +462,8 @@ operating system on which the build is performed (as reported by C<uname <para> - Like the &LIBPATH; variable, - the &CPPPATH; variable + Like the &cv-LIBPATH; variable, + the &cv-CPPPATH; variable may be a list of directories, or a string separated by the system-specific path separate character @@ -490,7 +490,7 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex5" os="posix"> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -500,7 +500,7 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex5" os="win32"> - <command>scons -Q hello.exe</command> + <scons_output_command>scons -Q hello.exe</scons_output_command> </scons_output> </section> @@ -554,8 +554,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1"> - <command>scons -Q --implicit-cache hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q --implicit-cache hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -610,8 +610,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1"> - <command>scons -Q --implicit-deps-changed hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q --implicit-deps-changed hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -645,8 +645,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1"> - <command>scons -Q --implicit-deps-unchanged hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q --implicit-deps-unchanged hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -699,10 +699,10 @@ operating system on which the build is performed (as reported by C<uname <!-- <scons_output example="ignore"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX </scons_output> --> diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml index b372885..3d74025 100644 --- a/doc/user/depends.sgml +++ b/doc/user/depends.sgml @@ -375,7 +375,7 @@ operating system on which the build is performed (as reported by C<uname </section> <section> - <title>Implicit Dependencies: The &CPPPATH; Construction Variable</title> + <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> @@ -422,7 +422,7 @@ operating system on which the build is performed (as reported by C<uname <para> - The &CPPPATH; value + The &cv-CPPPATH; value tells &SCons; to look in the current directory (<literal>'.'</literal>) for any files included by C source files @@ -448,7 +448,7 @@ operating system on which the build is performed (as reported by C<uname First, notice that &SCons; added the <literal>-I.</literal> argument - from the &CPPPATH; variable + from the &cv-CPPPATH; variable so that the compilation would find the &hello_h; file in the local directory. @@ -475,8 +475,8 @@ operating system on which the build is performed (as reported by C<uname <para> - Like the &LIBPATH; variable, - the &CPPPATH; variable + Like the &cv-LIBPATH; variable, + the &cv-CPPPATH; variable may be a list of directories, or a string separated by the system-specific path separate character @@ -711,10 +711,10 @@ operating system on which the build is performed (as reported by C<uname <!-- <scons_output example="ignore"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX </scons_output> --> diff --git a/doc/user/environments.in b/doc/user/environments.in index 47a3c44..586242c 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -468,7 +468,8 @@ environment undisturbed. and further specifies that the <literal>-O2</literal> (optimization level two) flag should be used when compiling the object file. - In other words, the explicit initializations of &CC; and &CCFLAGS; + In other words, the explicit initializations of + &cv-link-CC; and &cv-link-CCFLAGS; override the default values in the newly-created construction environment. So a run from this example would look like: @@ -476,7 +477,7 @@ environment undisturbed. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <section> @@ -514,7 +515,7 @@ environment undisturbed. </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -522,7 +523,7 @@ environment undisturbed. We can even use multiple construction environments to build multiple versions of a single program. If you do this by simply trying to use the - &Program; builder with both environments, though, + &b-link-Program; builder with both environments, though, like this: </para> @@ -548,17 +549,17 @@ environment undisturbed. </para> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> - This is because the two &Program; calls have + This is because the two &b-Program; calls have each implicitly told &SCons; to generate an object file named <filename>foo.o</filename>, - one with a &CCFLAGS; value of + one with a &cv-link-CCFLAGS; value of <literal>-O2</literal> - and one with a &CCFLAGS; value of + and one with a &cv-link-CCFLAGS; value of <literal>-g</literal>. &SCons; can't just decide that one of them should take precedence over the other, @@ -568,7 +569,7 @@ environment undisturbed. that each environment compile <filename>foo.c</filename> to a separately-named object file - using the &Object; call, like so: + using the &b-link-Object; builder, like so: </para> @@ -590,12 +591,12 @@ environment undisturbed. <para> - Notice that each call to the &Object; builder + Notice that each call to the &b-Object; builder returns a value, an internal &SCons; object that represents the object file that will be built. We then use that object - as input to the &Program; builder. + as input to the &b-Program; builder. This avoids having to specify explicitly the object file name in multiple places, and makes for a compact, readable @@ -605,7 +606,7 @@ environment undisturbed. </para> <scons_output example="ex4"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -633,10 +634,10 @@ environment undisturbed. to create three versions of a program, one optimized, one debug, and one with neither. We could do this by creating a "base" construction environment - that sets &CC; to &gcc;, + that sets &cv-link-CC; to &gcc;, and then creating two copies, - one which sets &CCFLAGS; for optimization - and the other which sets &CCFLAGS; for debugging: + one which sets &cv-link-CCFLAGS; for optimization + and the other which sets &cv-CCFLAGS; for debugging: </para> @@ -666,7 +667,7 @@ environment undisturbed. </para> <scons_output example="ex5"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -693,12 +694,12 @@ environment undisturbed. This example &SConstruct; file doesn't build anything, but because it's actually a Python script, - it will print the value of &CC; for us: + it will print the value of &cv-link-CC; for us: </para> <scons_output example="ex6"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -729,7 +730,7 @@ environment undisturbed. </para> <scons_output example="ex6b" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -739,7 +740,7 @@ environment undisturbed. </para> <scons_output example="ex6b" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -775,7 +776,7 @@ environment undisturbed. the example from the previous section that used <literal>env['CC']</literal> - to fetch the value of &CC; + to fetch the value of &cv-link-CC; could also be written as: </para> @@ -794,7 +795,7 @@ environment undisturbed. re-expanded until there are no expansions left in the string. So a simple fetch of a value like - <varname>$CCCOM</varname>: + &cv-link-CCCOM;: </para> @@ -805,7 +806,7 @@ environment undisturbed. <para> - Will print the unexpanded value of &CCCOM;, + Will print the unexpanded value of &cv-CCCOM;, showing us the construction variables that still need to be expanded: @@ -848,7 +849,7 @@ environment undisturbed. (Note that because we're not expanding this in the context of building something there are no target or source files - for <varname>$TARGET</varname> and <varname>$SOURCES</varname> to expand. + for &cv-link-TARGET; and &cv-link-SOURCES; to expand. </para> @@ -895,7 +896,7 @@ environment undisturbed. </para> <scons_output example="Replace1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -923,7 +924,7 @@ environment undisturbed. </para> <scons_output example="Replace-nonexistent"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -972,14 +973,14 @@ environment undisturbed. </para> <scons_output example="Replace2"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> Because the replacement occurs while the &SConscript; files are being read, - the <literal>$CCFLAGS</literal> + the &cv-link-CCFLAGS; variable has already been set to <literal>-DDEFINE2</literal> by the time the &foo_o; target is built, @@ -1021,7 +1022,7 @@ environment undisturbed. </para> <scons_output example="ex8"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -1046,7 +1047,7 @@ environment undisturbed. </para> <scons_output example="Append-nonexistent"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -1081,7 +1082,7 @@ environment undisturbed. </para> <scons_output example="ex9"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -1106,7 +1107,7 @@ environment undisturbed. </para> <scons_output example="Prepend-nonexistent"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml index 1ff2fb3..14be5af 100644 --- a/doc/user/environments.sgml +++ b/doc/user/environments.sgml @@ -463,7 +463,8 @@ environment undisturbed. and further specifies that the <literal>-O2</literal> (optimization level two) flag should be used when compiling the object file. - In other words, the explicit initializations of &CC; and &CCFLAGS; + In other words, the explicit initializations of + &cv-link-CC; and &cv-link-CCFLAGS; override the default values in the newly-created construction environment. So a run from this example would look like: @@ -515,7 +516,7 @@ environment undisturbed. We can even use multiple construction environments to build multiple versions of a single program. If you do this by simply trying to use the - &Program; builder with both environments, though, + &b-link-Program; builder with both environments, though, like this: </para> @@ -544,12 +545,12 @@ environment undisturbed. <para> - This is because the two &Program; calls have + This is because the two &b-Program; calls have each implicitly told &SCons; to generate an object file named <filename>foo.o</filename>, - one with a &CCFLAGS; value of + one with a &cv-link-CCFLAGS; value of <literal>-O2</literal> - and one with a &CCFLAGS; value of + and one with a &cv-link-CCFLAGS; value of <literal>-g</literal>. &SCons; can't just decide that one of them should take precedence over the other, @@ -559,7 +560,7 @@ environment undisturbed. that each environment compile <filename>foo.c</filename> to a separately-named object file - using the &Object; call, like so: + using the &b-link-Object; builder, like so: </para> @@ -576,12 +577,12 @@ environment undisturbed. <para> - Notice that each call to the &Object; builder + Notice that each call to the &b-Object; builder returns a value, an internal &SCons; object that represents the object file that will be built. We then use that object - as input to the &Program; builder. + as input to the &b-Program; builder. This avoids having to specify explicitly the object file name in multiple places, and makes for a compact, readable @@ -623,10 +624,10 @@ environment undisturbed. to create three versions of a program, one optimized, one debug, and one with neither. We could do this by creating a "base" construction environment - that sets &CC; to &gcc;, + that sets &cv-link-CC; to &gcc;, and then creating two copies, - one which sets &CCFLAGS; for optimization - and the other which sets &CCFLAGS; for debugging: + one which sets &cv-link-CCFLAGS; for optimization + and the other which sets &cv-CCFLAGS; for debugging: </para> @@ -682,7 +683,7 @@ environment undisturbed. This example &SConstruct; file doesn't build anything, but because it's actually a Python script, - it will print the value of &CC; for us: + it will print the value of &cv-link-CC; for us: </para> @@ -772,7 +773,7 @@ environment undisturbed. the example from the previous section that used <literal>env['CC']</literal> - to fetch the value of &CC; + to fetch the value of &cv-link-CC; could also be written as: </para> @@ -791,7 +792,7 @@ environment undisturbed. re-expanded until there are no expansions left in the string. So a simple fetch of a value like - <varname>$CCCOM</varname>: + &cv-link-CCCOM;: </para> @@ -802,7 +803,7 @@ environment undisturbed. <para> - Will print the unexpanded value of &CCCOM;, + Will print the unexpanded value of &cv-CCCOM;, showing us the construction variables that still need to be expanded: @@ -845,7 +846,7 @@ environment undisturbed. (Note that because we're not expanding this in the context of building something there are no target or source files - for <varname>$TARGET</varname> and <varname>$SOURCES</varname> to expand. + for &cv-link-TARGET; and &cv-link-SOURCES; to expand. </para> @@ -975,7 +976,7 @@ environment undisturbed. Because the replacement occurs while the &SConscript; files are being read, - the <literal>$CCFLAGS</literal> + the &cv-link-CCFLAGS; variable has already been set to <literal>-DDEFINE2</literal> by the time the &foo_o; target is built, diff --git a/doc/user/factories.in b/doc/user/factories.in new file mode 100644 index 0000000..95145d8 --- /dev/null +++ b/doc/user/factories.in @@ -0,0 +1,470 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + &SCons; provides a number of platform-independent functions, + called <literal>factories</literal>, + that perform common file system manipulations + like copying, moving or deleting files and directories, + or making directories. + These functions are <literal>factories</literal> + because they don't perform the action + at the time they're called, + they each return an &Action; object + that can be executed at the appropriate time. + + </para> + + <section> + <title>Copying Files or Directories: The &Copy; Factory</title> + + <para> + + Suppose you want to arrange to make a copy of a file, + and the &Install; builder isn't appropriate + because it may make a hard link on POSIX systems. + One way would be to use the &Copy; action factory + in conjunction with the &Command; builder: + + </para> + + <scons_example name="Copy1"> + <file name="SConstruct" printme="1"> + Command("file.out", "file.in", Copy("$TARGET", "$SOURCE")) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Notice that the action returned by the &Copy; factory + will expand the &cv-TARGET; and &cv-SOURCE; strings + at the time &file_out; is built, + and that the order of the arguments + is the same as that of a builder itself--that is, + target first, followed by source: + + </para> + + <scons_output example="Copy1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + You can, of course, name a file explicitly + instead of using &cv-TARGET; or &cv-SOURCE;: + + </para> + + <scons_example name="Copy2"> + <file name="SConstruct" printme="1"> + Command("file.out", [], Copy("$TARGET", "file.in")) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Which executes as: + + </para> + + <scons_output example="Copy2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + The usefulness of the &Copy; factory + becomes more apparent when + you use it in a list of actions + passed to the &Command; builder. + For example, suppose you needed to run a + file through a utility that only modifies files in-place, + and can't "pipe" input to output. + One solution is to copy the source file + to a temporary file name, + run the utility, + and then copy the modified temporary file to the target, + which the &Copy; factory makes extremely easy: + + </para> + + <scons_example name="Copy3"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + The output then looks like: + + </para> + + <scons_output example="Copy3"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Deleting Files or Directories: The &Delete; Factory</title> + + <para> + + If you need to delete a file, + then the &Delete; factory + can be used in much the same way as + the &Copy; factory. + For example, if we want to make sure that + the temporary file + in our last example doesn't exist before + we copy to it, + we could add &Delete; to the beginning + of the command list: + + </para> + + <scons_example name="Delete1"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Delete("tempfile"), + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + When then executes as follows: + + </para> + + <scons_output example="Delete1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + Of course, like all of these &Action; factories, + the &Delete factory also expands + &cv-TARGET; and &cv-SOURCE; variables appropriately. + For example: + + </para> + + <scons_example name="Delete2"> + <file name="SConstruct" printme="1"> + Command("file.out", "file.in", + [ + Delete("$TARGET"), + Copy("$TARGET", "$SOURCE") + ]) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Executes as: + + </para> + + <scons_output example="Delete2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + (Note, however, that you typically don't need to + call the &Delete; factory explicitly in this way; + by default, &SCons; deletes its target(s) + for you before executing any action. + + </para> + + </section> + + <section> + <title>Moving (Renaming) Files or Directories: The &Move; Factory</title> + + <para> + + The &Move; factory + allows you to rename a file or directory. + For example, if we don't want to copy the temporary file, + we could: + + </para> + + <scons_example name="Move"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + Which would execute as: + + </para> + + <scons_output example="Move"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Updating the Modification Time of a File: The &Touch; Factory</title> + + <para> + + If you just need to update the + recorded modification time for a file, + use the &Touch; factory: + + </para> + + <scons_example name="Touch"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + Which executes as: + + </para> + + <scons_output example="Touch"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Creating a Directory: The &Mkdir; Factory</title> + + <para> + + If you need to create a directory, + use the &Mkdir; factory. + For example, if we need to process + a file in a temporary directory + in which the processing tool + will create other files that we don't care about, + you could: + + </para> + + <scons_example name="Mkdir"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Delete("tempdir"), + Mkdir("tempdir"), + Copy("tempdir/${SOURCE.file}", "$SOURCE"), + "process tempdir", + Move("$TARGET", "tempdir/output_file"), + Delete("tempdir"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="process" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + Which executes as: + + </para> + + <scons_output example="Mkdir"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Changing File or Directory Permissions: The &Chmod; Factory</title> + + <para> + + To change permissions on a file or directory, + use the &Chmod; factory. + The permission argument uses POSIX-style + permission bits and should typically + be expressed as an octal, + not decimal, number: + + </para> + + <scons_example name="Chmod"> + <file name="SConstruct" printme="1"> + Command("file.out", "file.in", + [ + Copy("$TARGET", "$SOURCE"), + Chmod("$TARGET", 0755), + ]) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Which executes: + + </para> + + <scons_output example="Chmod"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Executing an action immediately: the &Execute; Function</title> + + <para> + + We've been showing you how to use &Action; factories + in the &Command; function. + You can also execute an &Action; returned by a factory + (or actually, any &Action;) + at the time the &SConscript; file is read + by wrapping it up in the &Execute; function. + For example, if we need to make sure that + a directory exists before we build any targets, + + + </para> + + <scons_example name="Execute"> + <file name="SConstruct" printme="1"> + Execute(Mkdir('__ROOT__/tmp/my_temp_directory')) + </file> + </scons_example> + + <para> + + Notice that this will + create the directory while + the &SConscript; file is being read: + + </para> + + <scons_output example="Execute"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + If you're familiar with Python, + you may wonder why you would want to use this + instead of just calling the native Python + <function>os.mkdir()</function> function. + The advantage here is that the &Mkdir; + action will behave appropriately if the user + specifies the &SCons; <option>-n</option> or + <option>-q</option> options--that is, + it will print the action but not actually + make the directory when <option>-n</option> is specified, + or make the directory but not print the action + when <option>-q</option> is specified. + + </para> + + </section> diff --git a/doc/user/factories.sgml b/doc/user/factories.sgml new file mode 100644 index 0000000..b145ff2 --- /dev/null +++ b/doc/user/factories.sgml @@ -0,0 +1,427 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + &SCons; provides a number of platform-independent functions, + called <literal>factories</literal>, + that perform common file system manipulations + like copying, moving or deleting files and directories, + or making directories. + These functions are <literal>factories</literal> + because they don't perform the action + at the time they're called, + they each return an &Action; object + that can be executed at the appropriate time. + + </para> + + <section> + <title>Copying Files or Directories: The &Copy; Factory</title> + + <para> + + Suppose you want to arrange to make a copy of a file, + and the &Install; builder isn't appropriate + because it may make a hard link on POSIX systems. + One way would be to use the &Copy; action factory + in conjunction with the &Command; builder: + + </para> + + <programlisting> + Command("file.out", "file.in", Copy("$TARGET", "$SOURCE")) + </programlisting> + + <para> + + Notice that the action returned by the &Copy; factory + will expand the &cv-TARGET; and &cv-SOURCE; strings + at the time &file_out; is built, + and that the order of the arguments + is the same as that of a builder itself--that is, + target first, followed by source: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("file.out", "file.in") + </screen> + + <para> + + You can, of course, name a file explicitly + instead of using &cv-TARGET; or &cv-SOURCE;: + + </para> + + <programlisting> + Command("file.out", [], Copy("$TARGET", "file.in")) + </programlisting> + + <para> + + Which executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("file.out", "file.in") + </screen> + + <para> + + The usefulness of the &Copy; factory + becomes more apparent when + you use it in a list of actions + passed to the &Command; builder. + For example, suppose you needed to run a + file through a utility that only modifies files in-place, + and can't "pipe" input to output. + One solution is to copy the source file + to a temporary file name, + run the utility, + and then copy the modified temporary file to the target, + which the &Copy; factory makes extremely easy: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + The output then looks like: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("tempfile", "file.in") + modify tempfile + Copy("file.out", "tempfile") + </screen> + + </section> + + <section> + <title>Deleting Files or Directories: The &Delete; Factory</title> + + <para> + + If you need to delete a file, + then the &Delete; factory + can be used in much the same way as + the &Copy; factory. + For example, if we want to make sure that + the temporary file + in our last example doesn't exist before + we copy to it, + we could add &Delete; to the beginning + of the command list: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Delete("tempfile"), + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + When then executes as follows: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Delete("tempfile") + Copy("tempfile", "file.in") + modify tempfile + Copy("file.out", "tempfile") + </screen> + + <para> + + Of course, like all of these &Action; factories, + the &Delete; factory also expands + &cv-TARGET; and &cv-SOURCE; variables appropriately. + For example: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Delete("$TARGET"), + Copy("$TARGET", "$SOURCE") + ]) + </programlisting> + + <para> + + Executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Delete("file.out") + Copy("file.out", "file.in") + </screen> + + <para> + + (Note, however, that you typically don't need to + call the &Delete; factory explicitly in this way; + by default, &SCons; deletes its target(s) + for you before executing any action. + + </para> + + </section> + + <section> + <title>Moving (Renaming) Files or Directories: The &Move; Factory</title> + + <para> + + The &Move; factory + allows you to rename a file or directory. + For example, if we don't want to copy the temporary file, + we could: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + Which would execute as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("tempfile", "file.in") + modify tempfile + Move("file.out", "tempfile") + </screen> + + </section> + + <section> + <title>Updating the Modification Time of a File: The &Touch; Factory</title> + + <para> + + If you just need to update the + recorded modification time for a file, + use the &Touch; factory: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + Which executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("tempfile", "file.in") + modify tempfile + Move("file.out", "tempfile") + </screen> + + </section> + + <section> + <title>Creating a Directory: The &Mkdir; Factory</title> + + <para> + + If you need to create a directory, + use the &Mkdir; factory. + For example, if we need to process + a file in a temporary directory + in which the processing tool + will create other files that we don't care about, + you could: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Delete("tempdir"), + Mkdir("tempdir"), + Copy("tempdir/${SOURCE.file}", "$SOURCE"), + "process tempdir", + Move("$TARGET", "tempdir/output_file"), + Delete("tempdir"), + ]) + </programlisting> + + <para> + + Which executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Delete("tempdir") + Mkdir("tempdir") + Copy("tempdir/file.in", "file.in") + process tempdir + Move("file.out", "tempdir/output_file") + scons: *** [file.out] No such file or directory + </screen> + + </section> + + <section> + <title>Changing File or Directory Permissions: The &Chmod; Factory</title> + + <para> + + To change permissions on a file or directory, + use the &Chmod; factory. + The permission argument uses POSIX-style + permission bits and should typically + be expressed as an octal, + not decimal, number: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("$TARGET", "$SOURCE"), + Chmod("$TARGET", 0755), + ]) + </programlisting> + + <para> + + Which executes: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("file.out", "file.in") + Chmod("file.out", 0755) + </screen> + + </section> + + <section> + <title>Executing an action immediately: the &Execute; Function</title> + + <para> + + We've been showing you how to use &Action; factories + in the &Command; function. + You can also execute an &Action; returned by a factory + (or actually, any &Action;) + at the time the &SConscript; file is read + by wrapping it up in the &Execute; function. + For example, if we need to make sure that + a directory exists before we build any targets, + + + </para> + + <programlisting> + Execute(Mkdir('/tmp/my_temp_directory')) + </programlisting> + + <para> + + Notice that this will + create the directory while + the &SConscript; file is being read: + + </para> + + <screen> + % <userinput>scons</userinput> + scons: Reading SConscript files ... + Mkdir("/tmp/my_temp_directory") + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + If you're familiar with Python, + you may wonder why you would want to use this + instead of just calling the native Python + <function>os.mkdir()</function> function. + The advantage here is that the &Mkdir; + action will behave appropriately if the user + specifies the &SCons; <option>-n</option> or + <option>-q</option> options--that is, + it will print the action but not actually + make the directory when <option>-n</option> is specified, + or make the directory but not print the action + when <option>-q</option> is specified. + + </para> + + </section> diff --git a/doc/user/help.in b/doc/user/help.in index d4b2caa..4356d18 100644 --- a/doc/user/help.in +++ b/doc/user/help.in @@ -61,7 +61,66 @@ </para> <scons_output example="ex1"> - <command>scons -h</command> + <scons_output_command>scons -h</scons_output_command> + </scons_output> + + <para> + + The &SConscript; files may contain + multiple calls to the &Help; function, + in which case the specified text(s) + will be concatenated when displayed. + This allows you to split up the + help text across multiple &SConscript; files. + In this situation, the order in + which the &SConscript; files are called + will determine the order in which the &Help; functions are called, + which will determine the order in which + the various bits of text will get concatenated. + + </para> + + <para> + + Another use would be to make the help text conditional + on some variable. + For example, suppose you only want to display + a line about building a Windows-only + version of a program when actually + run on Windows. + The following &SConstruct; file: + + </para> + + <scons_example name="ex2"> + <file name="SConstruct" printme="1"> + env = Environment() + + Help("\nType: 'scons program' to build the production program.\n") + + if env['PLATFORM'] == 'win32': + Help("\nType: 'scons windebug' to build the Windows debug version.\n") + </file> + </scons_example> + + <para> + + Will display the completely help text on Windows: + + </para> + + <scons_output example="ex2" os="win32"> + <scons_output_command>scons -h</scons_output_command> + </scons_output> + + <para> + + But only show the relevant option on a Linux or UNIX system: + + </para> + + <scons_output example="ex2" os="posix"> + <scons_output_command>scons -h</scons_output_command> </scons_output> <para> diff --git a/doc/user/help.sgml b/doc/user/help.sgml index 9db5bf0..ca44a40 100644 --- a/doc/user/help.sgml +++ b/doc/user/help.sgml @@ -71,6 +71,77 @@ <para> + The &SConscript; files may contain + multiple calls to the &Help; function, + in which case the specified text(s) + will be concatenated when displayed. + This allows you to split up the + help text across multiple &SConscript; files. + In this situation, the order in + which the &SConscript; files are called + will determine the order in which the &Help; functions are called, + which will determine the order in which + the various bits of text will get concatenated. + + </para> + + <para> + + Another use would be to make the help text conditional + on some variable. + For example, suppose you only want to display + a line about building a Windows-only + version of a program when actually + run on Windows. + The following &SConstruct; file: + + </para> + + <programlisting> + env = Environment() + + Help("\nType: 'scons program' to build the production program.\n") + + if env['PLATFORM'] == 'win32': + Help("\nType: 'scons windebug' to build the Windows debug version.\n") + </programlisting> + + <para> + + Will display the completely help text on Windows: + + </para> + + <screen> + C:\><userinput>scons -h</userinput> + scons: Reading SConscript files ... + scons: done reading SConscript files. + + Type: 'scons program' to build the production program. + + Type: 'scons windebug' to build the Windows debug version. + + Use scons -H for help about command-line options. + </screen> + + <para> + + But only show the relevant option on a Linux or UNIX system: + + </para> + + <screen> + % <userinput>scons -h</userinput> + scons: Reading SConscript files ... + scons: done reading SConscript files. + + Type: 'scons program' to build the production program. + + Use scons -H for help about command-line options. + </screen> + + <para> + If there is no &Help; text in the &SConstruct; or &SConscript; files, &SCons; will revert to displaying its diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index 0c4563d..355aca3 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -340,7 +340,7 @@ make no difference to the build. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -411,7 +411,7 @@ make no difference to the build. </para> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -462,7 +462,7 @@ make no difference to the build. </para> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -767,7 +767,7 @@ make no difference to the build. </para> <scons_output example="Return"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/install.in b/doc/user/install.in index dfbb822..ac9510f 100644 --- a/doc/user/install.in +++ b/doc/user/install.in @@ -62,8 +62,8 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q __ROOT__/usr/bin</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q __ROOT__/usr/bin</scons_output_command> </scons_output> <para> @@ -101,8 +101,8 @@ </para> <scons_output example="ex2"> - <command>scons -Q</command> - <command>scons -Q install</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> <section> @@ -155,7 +155,7 @@ </para> <scons_output example="ex3"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> </section> @@ -194,7 +194,7 @@ </para> <scons_output example="ex4"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> </section> @@ -241,7 +241,7 @@ </para> <scons_output example="ex5"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> </section> diff --git a/doc/user/java.in b/doc/user/java.in index 66b9c86..9768dab 100644 --- a/doc/user/java.in +++ b/doc/user/java.in @@ -38,7 +38,7 @@ </para> <section> - <title>Building Java Class Files: the &Java; Builder</title> + <title>Building Java Class Files: the &b-Java; Builder</title> <para> @@ -49,7 +49,7 @@ to turn them into one or more <filename>.class</filename> files. In &SCons;, you do this - by giving the &Java; Builder + by giving the &b-link-Java; Builder a target directory in which to put the <filename>.class</filename> files, and a source directory that contains @@ -99,7 +99,7 @@ </para> <scons_output example="java"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -191,8 +191,8 @@ </para> <scons_output example="java-classes"> - <command>scons -Q</command> - <command>scons -Q classes</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q classes</scons_output_command> </scons_output> <para> @@ -215,25 +215,25 @@ </para> <scons_output example="java-classes"> - <command>scons -Q</command> - <command>scons -Q -c classes</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c classes</scons_output_command> </scons_output> </section> <section> - <title>Building Java Archive (<filename>.jar</filename>) Files: the &Jar; Builder</title> + <title>Building Java Archive (<filename>.jar</filename>) Files: the &b-Jar; Builder</title> <para> After building the class files, it's common to collect them into a Java archive (<filename>.jar</filename>) file, - which you do by calling the &Jar; Builder method. + which you do by calling the &b-link-Jar; Builder method. If you want to just collect all of the class files within a subdirectory, you can just specify that subdirectory - as the &Jar; source: + as the &b-Jar; source: </para> @@ -281,7 +281,7 @@ </para> <scons_output example="jar1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -291,13 +291,13 @@ for multiple programs in one location, and only archive some of them in each <filename>.jar</filename> file, - you can pass the &Jar; builder a + you can pass the &b-Jar; builder a list of files as its source. It's extremely simple to create multiple <filename>.jar</filename> files this way, using the lists of target class files created - by calls to the &Java; builder - as sources to the various &Jar; calls: + by calls to the &b-link-Java; builder + as sources to the various &b-Jar; calls: </para> @@ -357,19 +357,19 @@ </para> <scons_output example="jar2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> <section> - <title>Building C Header and Stub Files: the &JavaH; Builder</title> + <title>Building C Header and Stub Files: the &b-JavaH; Builder</title> <para> You can generate C header and source files for implementing native methods, - by using the &JavaH; Builder. + by using the &b-link-JavaH; Builder. There are several ways of using the &JavaH Builder. One typical invocation might look like: @@ -412,7 +412,7 @@ <para> The source is a list of class files generated by the - call to the &Java; Builder, + call to the &b-link-Java; Builder, and the target is the output directory in which we want the C header files placed. The target @@ -422,7 +422,7 @@ </para> <scons_output example="javah"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -447,15 +447,15 @@ Although it's more convenient to use the list of class files returned by - the &Java; Builder - as the source of a call to the &JavaH; Builder, + the &b-Java; Builder + as the source of a call to the &b-JavaH; Builder, you <emphasis>can</emphasis> specify the list of class files by hand, if you prefer. If you do, you need to set the - &JAVACLASSDIR; construction variable - when calling &JavaH;: + &cv-link-JAVACLASSDIR; construction variable + when calling &b-JavaH;: </para> @@ -498,14 +498,14 @@ <para> - The &JAVACLASSDIR; value then + The &cv-JAVACLASSDIR; value then gets converted into the <option>-classpath</option> when &SCons; runs &javah;: </para> <scons_output example="JAVACLASSDIR"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -513,7 +513,7 @@ Lastly, if you don't want a separate header file generated for each source file, you can specify an explicit File Node - as the target of the &JavaH; Builder: + as the target of the &b-JavaH; Builder: </para> @@ -554,7 +554,7 @@ <para> Because &SCons; assumes by default - that the target of the &JavaH; builder is a directory, + that the target of the &b-JavaH; builder is a directory, you need to use the &File; function to make sure that &SCons; doesn't create a directory named <filename>native.h</filename>. @@ -565,20 +565,20 @@ </para> <scons_output example="javah_file"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> <section> - <title>Building RMI Stub and Skeleton Class Files: the &RMIC; Builder</title> + <title>Building RMI Stub and Skeleton Class Files: the &b-RMIC; Builder</title> <para> You can generate Remote Method Invocation stubs - by using the &RMIC; Builder. + by using the &b-link-RMIC; Builder. The source is a list of directories, - typically returned by a call to the &Java; Builder, + typically returned by a call to the &b-link-Java; Builder, and the target is an output directory where the <filename>_Stub.class</filename> and <filename>_Skel.class</filename> files will @@ -613,7 +613,7 @@ <para> - As it did with the &JavaH; Builder, + As it did with the &b-link-JavaH; Builder, &SCons; remembers the class directory and passes it as the <option>-classpath</option> option to &rmic: @@ -621,7 +621,7 @@ </para> <scons_output example="RMIC"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/java.sgml b/doc/user/java.sgml index e3eee53..1876916 100644 --- a/doc/user/java.sgml +++ b/doc/user/java.sgml @@ -38,7 +38,7 @@ </para> <section> - <title>Building Java Class Files: the &Java; Builder</title> + <title>Building Java Class Files: the &b-Java; Builder</title> <para> @@ -49,7 +49,7 @@ to turn them into one or more <filename>.class</filename> files. In &SCons;, you do this - by giving the &Java; Builder + by giving the &b-link-Java; Builder a target directory in which to put the <filename>.class</filename> files, and a source directory that contains @@ -158,18 +158,18 @@ </section> <section> - <title>Building Java Archive (<filename>.jar</filename>) Files: the &Jar; Builder</title> + <title>Building Java Archive (<filename>.jar</filename>) Files: the &b-Jar; Builder</title> <para> After building the class files, it's common to collect them into a Java archive (<filename>.jar</filename>) file, - which you do by calling the &Jar; Builder method. + which you do by calling the &b-link-Jar; Builder method. If you want to just collect all of the class files within a subdirectory, you can just specify that subdirectory - as the &Jar; source: + as the &b-Jar; source: </para> @@ -200,13 +200,13 @@ for multiple programs in one location, and only archive some of them in each <filename>.jar</filename> file, - you can pass the &Jar; builder a + you can pass the &b-Jar; builder a list of files as its source. It's extremely simple to create multiple <filename>.jar</filename> files this way, using the lists of target class files created - by calls to the &Java; builder - as sources to the various &Jar; calls: + by calls to the &b-link-Java; builder + as sources to the various &b-Jar; calls: </para> @@ -238,13 +238,13 @@ </section> <section> - <title>Building C Header and Stub Files: the &JavaH; Builder</title> + <title>Building C Header and Stub Files: the &b-JavaH; Builder</title> <para> You can generate C header and source files for implementing native methods, - by using the &JavaH; Builder. + by using the &b-link-JavaH; Builder. There are several ways of using the &JavaH; Builder. One typical invocation might look like: @@ -258,7 +258,7 @@ <para> The source is a list of class files generated by the - call to the &Java; Builder, + call to the &b-link-Java; Builder, and the target is the output directory in which we want the C header files placed. The target @@ -295,15 +295,15 @@ Although it's more convenient to use the list of class files returned by - the &Java; Builder - as the source of a call to the &JavaH; Builder, + the &b-Java; Builder + as the source of a call to the &b-JavaH; Builder, you <emphasis>can</emphasis> specify the list of class files by hand, if you prefer. If you do, you need to set the - &JAVACLASSDIR; construction variable - when calling &JavaH;: + &cv-link-JAVACLASSDIR; construction variable + when calling &b-JavaH;: </para> @@ -317,7 +317,7 @@ <para> - The &JAVACLASSDIR; value then + The &cv-JAVACLASSDIR; value then gets converted into the <option>-classpath</option> when &SCons; runs &javah;: @@ -334,7 +334,7 @@ Lastly, if you don't want a separate header file generated for each source file, you can specify an explicit File Node - as the target of the &JavaH; Builder: + as the target of the &b-JavaH; Builder: </para> @@ -346,7 +346,7 @@ <para> Because &SCons; assumes by default - that the target of the &JavaH; builder is a directory, + that the target of the &b-JavaH; builder is a directory, you need to use the &File; function to make sure that &SCons; doesn't create a directory named <filename>native.h</filename>. @@ -365,14 +365,14 @@ </section> <section> - <title>Building RMI Stub and Skeleton Class Files: the &RMIC; Builder</title> + <title>Building RMI Stub and Skeleton Class Files: the &b-RMIC; Builder</title> <para> You can generate Remote Method Invocation stubs - by using the &RMIC; Builder. + by using the &b-link-RMIC; Builder. The source is a list of directories, - typically returned by a call to the &Java; Builder, + typically returned by a call to the &b-link-Java; Builder, and the target is an output directory where the <filename>_Stub.class</filename> and <filename>_Skel.class</filename> files will @@ -387,7 +387,7 @@ <para> - As it did with the &JavaH; Builder, + As it did with the &b-link-JavaH; Builder, &SCons; remembers the class directory and passes it as the <option>-classpath</option> option to &rmic;: diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in index c0dafb1..ccc59b6 100644 --- a/doc/user/less-simple.in +++ b/doc/user/less-simple.in @@ -40,7 +40,7 @@ <para> - You've seen that when you call the &Program; builder method, + You've seen that when you call the &b-link-Program; builder method, it builds the resulting program with the same base name as the source file. That is, the following call to build an @@ -91,7 +91,7 @@ </para> <scons_output example="target" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -102,7 +102,7 @@ </para> <scons_output example="target" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -146,7 +146,7 @@ </para> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -193,7 +193,7 @@ </para> <scons_output example="ex3" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -203,7 +203,7 @@ </para> <scons_output example="ex3" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -220,7 +220,7 @@ </para> <sconstruct> - Program('hello', ['file1.c', 'file2']) + Program('hello', ['file1.c', 'file2.c']) </sconstruct> <para> @@ -351,13 +351,13 @@ <para> Putting the call to the &Split; function - inside the <function>Program</function> call + inside the &b-Program; call can also be a little unwieldy. A more readable alternative is to assign the output from the &Split; call to a variable name, and then use the variable when calling the - <function>Program</function> function: + &b-Program; function: </para> @@ -451,7 +451,7 @@ In order to compile multiple programs within the same &SConstruct; file, - simply call the <function>Program</function> method + simply call the &Program; method multiple times, once for each program you need to build: @@ -480,7 +480,7 @@ </para> <scons_output example="ex4"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -555,7 +555,7 @@ </para> <scons_output example="ex5"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/less-simple.sgml b/doc/user/less-simple.sgml index d3a6edc..1aa993d 100644 --- a/doc/user/less-simple.sgml +++ b/doc/user/less-simple.sgml @@ -40,7 +40,7 @@ <para> - You've seen that when you call the &Program; builder method, + You've seen that when you call the &b-link-Program; builder method, it builds the resulting program with the same base name as the source file. That is, the following call to build an @@ -209,7 +209,7 @@ </para> <programlisting> - Program('hello', ['file1.c', 'file2']) + Program('hello', ['file1.c', 'file2.c']) </programlisting> <para> @@ -340,13 +340,13 @@ <para> Putting the call to the &Split; function - inside the <function>Program</function> call + inside the &b-Program; call can also be a little unwieldy. A more readable alternative is to assign the output from the &Split; call to a variable name, and then use the variable when calling the - <function>Program</function> function: + &b-Program; function: </para> @@ -440,7 +440,7 @@ In order to compile multiple programs within the same &SConstruct; file, - simply call the <function>Program</function> method + simply call the &Program; method multiple times, once for each program you need to build: diff --git a/doc/user/libraries.in b/doc/user/libraries.in index 542cd13..e5368d1 100644 --- a/doc/user/libraries.in +++ b/doc/user/libraries.in @@ -37,8 +37,8 @@ <para> - You build your own libraries by specifying &Library; - instead of &Program;: + You build your own libraries by specifying &b-link-Library; + instead of &b-link-Program;: </para> @@ -67,7 +67,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -78,7 +78,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -94,14 +94,14 @@ </para> <section> - <title>Building Static Libraries Explicitly: the &StaticLibrary; Builder</title> + <title>Building Static Libraries Explicitly: the &b-StaticLibrary; Builder</title> <para> - The &Library; function builds a traditional static library. + The &b-link-Library; function builds a traditional static library. If you want to be explicit about the type of library being built, - you can use the synonym &StaticLibrary; function - instead of &Library: + you can use the synonym &b-link-StaticLibrary; function + instead of &b-Library: </para> @@ -114,20 +114,20 @@ <para> There is no functional difference between the - &StaticLibrary; and &Library; functions. + &b-link-StaticLibrary; and &b-Library; functions. </para> </section> <section> - <title>Building Shared (DLL) Libraries: the &SharedLibrary; Builder</title> + <title>Building Shared (DLL) Libraries: the &b-SharedLibrary; Builder</title> <para> If you want to build a shared library (on POSIX systems) or a DLL file (on Windows systems), - you use the &SharedLibrary; function: + you use the &b-link-SharedLibrary; function: </para> @@ -153,7 +153,7 @@ </para> <scons_output example="SharedLibrary" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -163,7 +163,7 @@ </para> <scons_output example="SharedLibrary" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -188,10 +188,10 @@ Usually, you build a library because you want to link it with one or more programs. You link libraries with a program by specifying - the libraries in the &LIBS; construction variable, + the libraries in the &cv-link-LIBS; construction variable, and by specifying the directory in which the library will be found in the - &LIBPATH; construction variable: + &cv-link-LIBPATH; construction variable: </para> @@ -231,7 +231,7 @@ </para> <scons_output example="ex2" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -242,7 +242,7 @@ </para> <scons_output example="ex2" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -288,7 +288,7 @@ </section> <section> - <title>Finding Libraries: the &LIBPATH; Construction Variable</title> + <title>Finding Libraries: the &cv-LIBPATH; Construction Variable</title> <para> @@ -296,8 +296,8 @@ certain system-defined directories for libraries. &SCons; knows how to look for libraries in directories that you specify with the - &LIBPATH; construction variable. - &LIBPATH; consists of a list of + &cv-link-LIBPATH; construction variable. + &cv-LIBPATH; consists of a list of directory names, like so: </para> @@ -356,7 +356,7 @@ </para> <scons_output example="ex3" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -367,7 +367,7 @@ </para> <scons_output example="ex3" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml index 8e25c9a..aab3045 100644 --- a/doc/user/libraries.sgml +++ b/doc/user/libraries.sgml @@ -37,8 +37,8 @@ <para> - You build your own libraries by specifying &Library; - instead of &Program;: + You build your own libraries by specifying &b-link-Library; + instead of &b-link-Program;: </para> @@ -92,14 +92,14 @@ </para> <section> - <title>Building Static Libraries Explicitly: the &StaticLibrary; Builder</title> + <title>Building Static Libraries Explicitly: the &b-StaticLibrary; Builder</title> <para> - The &Library; function builds a traditional static library. + The &b-link-Library; function builds a traditional static library. If you want to be explicit about the type of library being built, - you can use the synonym &StaticLibrary; function - instead of &Library;: + you can use the synonym &b-link-StaticLibrary; function + instead of &b-Library: </para> @@ -110,20 +110,20 @@ <para> There is no functional difference between the - &StaticLibrary; and &Library; functions. + &b-link-StaticLibrary; and &b-Library; functions. </para> </section> <section> - <title>Building Shared (DLL) Libraries: the &SharedLibrary; Builder</title> + <title>Building Shared (DLL) Libraries: the &b-SharedLibrary; Builder</title> <para> If you want to build a shared library (on POSIX systems) or a DLL file (on Windows systems), - you use the &SharedLibrary; function: + you use the &b-link-SharedLibrary; function: </para> @@ -157,6 +157,7 @@ cl /nologo /c f2.c /Fof2.obj cl /nologo /c f3.c /Fof3.obj link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj + RegServerFunc(target, source, env) </screen> <para> @@ -181,10 +182,10 @@ Usually, you build a library because you want to link it with one or more programs. You link libraries with a program by specifying - the libraries in the &LIBS; construction variable, + the libraries in the &cv-link-LIBS; construction variable, and by specifying the directory in which the library will be found in the - &LIBPATH; construction variable: + &cv-link-LIBPATH; construction variable: </para> @@ -280,7 +281,7 @@ </section> <section> - <title>Finding Libraries: the &LIBPATH; Construction Variable</title> + <title>Finding Libraries: the &cv-LIBPATH; Construction Variable</title> <para> @@ -288,8 +289,8 @@ certain system-defined directories for libraries. &SCons; knows how to look for libraries in directories that you specify with the - &LIBPATH; construction variable. - &LIBPATH; consists of a list of + &cv-link-LIBPATH; construction variable. + &cv-LIBPATH; consists of a list of directory names, like so: </para> diff --git a/doc/user/main.in b/doc/user/main.in index 3e0e047..a720915 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -32,10 +32,20 @@ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; + <!ENTITY % builders-mod SYSTEM "builders.mod"> + %builders-mod; + + <!ENTITY % tools-mod SYSTEM "tools.mod"> + %tools-mod; + + <!ENTITY % variables-mod SYSTEM "variables.mod"> + %variables-mod; + <!ENTITY actions SYSTEM "actions.sgml"> <!ENTITY alias SYSTEM "alias.sgml"> <!ENTITY ant SYSTEM "ant.sgml"> <!ENTITY build-install SYSTEM "build-install.sgml"> + <!ENTITY builders SYSTEM "builders.sgml"> <!ENTITY builders-built-in SYSTEM "builders-built-in.sgml"> <!ENTITY builders-commands SYSTEM "builders-commands.sgml"> <!ENTITY builders-writing SYSTEM "builders-writing.sgml"> @@ -48,6 +58,7 @@ <!ENTITY environments SYSTEM "environments.sgml"> <!ENTITY errors SYSTEM "errors.sgml"> <!ENTITY example SYSTEM "example.sgml"> + <!ENTITY factories SYSTEM "factories.sgml"> <!ENTITY help SYSTEM "help.sgml"> <!ENTITY hierarchy SYSTEM "hierarchy.sgml"> <!ENTITY java SYSTEM "java.sgml"> @@ -56,8 +67,10 @@ <!ENTITY libraries SYSTEM "libraries.sgml"> <!ENTITY make SYSTEM "make.sgml"> <!ENTITY nodes SYSTEM "nodes.sgml"> + <!ENTITY parseconfig SYSTEM "parseconfig.sgml"> <!ENTITY precious SYSTEM "precious.sgml"> <!ENTITY preface SYSTEM "preface.sgml"> + <!ENTITY python SYSTEM "python.sgml"> <!ENTITY repositories SYSTEM "repositories.sgml"> <!ENTITY run SYSTEM "run.sgml"> <!ENTITY scanners SYSTEM "scanners.sgml"> @@ -66,9 +79,15 @@ <!ENTITY simple SYSTEM "simple.sgml"> <!ENTITY sourcecode SYSTEM "sourcecode.sgml"> <!ENTITY tasks SYSTEM "tasks.sgml"> + <!ENTITY tools SYSTEM "tools.sgml"> <!ENTITY troubleshoot SYSTEM "troubleshoot.sgml"> + <!ENTITY variables SYSTEM "variables.sgml"> <!ENTITY variants SYSTEM "variants.sgml"> + <!ENTITY builders-gen SYSTEM "builders.gen"> + <!ENTITY tools-gen SYSTEM "tools.gen"> + <!ENTITY variables-gen SYSTEM "variables.gen"> + ]> <book> @@ -137,6 +156,15 @@ &environments; </chapter> + <!-- + + <chapter id="chap-parseconfig"> + <title>Finding Installed Library Information: the &ParseConfig; Function</title> + &parseconfig; + </chapter> + + --> + <chapter id="chap-ENV"> <title>Controlling the External Environment Used to Execute Build Commands</title> &ENV_file; @@ -157,6 +185,11 @@ &install; </chapter> + <chapter id="chap-factories"> + <title>Platform-Independent File System Manipulation</title> + &factories; + </chapter> + <chapter id="chap-precious"> <title>Preventing Removal of Targets: the &Precious; Function</title> &precious; @@ -273,6 +306,21 @@ Tools() --> + <appendix id="app-variables"> + <title>Construction Variables</title> + &variables; + </appendix> + + <appendix id="app-builders"> + <title>Builders</title> + &builders; + </appendix> + + <appendix id="app-tools"> + <title>Tools</title> + &tools; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; @@ -280,6 +328,11 @@ <!-- + <appendix id="app-python"> + <title>Python Overview</title> + &example; + </appendix> + <appendix id="app-example"> <title>Complex &SCons; Example</title> &example; diff --git a/doc/user/main.sgml b/doc/user/main.sgml index 3e0e047..a720915 100644 --- a/doc/user/main.sgml +++ b/doc/user/main.sgml @@ -32,10 +32,20 @@ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; + <!ENTITY % builders-mod SYSTEM "builders.mod"> + %builders-mod; + + <!ENTITY % tools-mod SYSTEM "tools.mod"> + %tools-mod; + + <!ENTITY % variables-mod SYSTEM "variables.mod"> + %variables-mod; + <!ENTITY actions SYSTEM "actions.sgml"> <!ENTITY alias SYSTEM "alias.sgml"> <!ENTITY ant SYSTEM "ant.sgml"> <!ENTITY build-install SYSTEM "build-install.sgml"> + <!ENTITY builders SYSTEM "builders.sgml"> <!ENTITY builders-built-in SYSTEM "builders-built-in.sgml"> <!ENTITY builders-commands SYSTEM "builders-commands.sgml"> <!ENTITY builders-writing SYSTEM "builders-writing.sgml"> @@ -48,6 +58,7 @@ <!ENTITY environments SYSTEM "environments.sgml"> <!ENTITY errors SYSTEM "errors.sgml"> <!ENTITY example SYSTEM "example.sgml"> + <!ENTITY factories SYSTEM "factories.sgml"> <!ENTITY help SYSTEM "help.sgml"> <!ENTITY hierarchy SYSTEM "hierarchy.sgml"> <!ENTITY java SYSTEM "java.sgml"> @@ -56,8 +67,10 @@ <!ENTITY libraries SYSTEM "libraries.sgml"> <!ENTITY make SYSTEM "make.sgml"> <!ENTITY nodes SYSTEM "nodes.sgml"> + <!ENTITY parseconfig SYSTEM "parseconfig.sgml"> <!ENTITY precious SYSTEM "precious.sgml"> <!ENTITY preface SYSTEM "preface.sgml"> + <!ENTITY python SYSTEM "python.sgml"> <!ENTITY repositories SYSTEM "repositories.sgml"> <!ENTITY run SYSTEM "run.sgml"> <!ENTITY scanners SYSTEM "scanners.sgml"> @@ -66,9 +79,15 @@ <!ENTITY simple SYSTEM "simple.sgml"> <!ENTITY sourcecode SYSTEM "sourcecode.sgml"> <!ENTITY tasks SYSTEM "tasks.sgml"> + <!ENTITY tools SYSTEM "tools.sgml"> <!ENTITY troubleshoot SYSTEM "troubleshoot.sgml"> + <!ENTITY variables SYSTEM "variables.sgml"> <!ENTITY variants SYSTEM "variants.sgml"> + <!ENTITY builders-gen SYSTEM "builders.gen"> + <!ENTITY tools-gen SYSTEM "tools.gen"> + <!ENTITY variables-gen SYSTEM "variables.gen"> + ]> <book> @@ -137,6 +156,15 @@ &environments; </chapter> + <!-- + + <chapter id="chap-parseconfig"> + <title>Finding Installed Library Information: the &ParseConfig; Function</title> + &parseconfig; + </chapter> + + --> + <chapter id="chap-ENV"> <title>Controlling the External Environment Used to Execute Build Commands</title> &ENV_file; @@ -157,6 +185,11 @@ &install; </chapter> + <chapter id="chap-factories"> + <title>Platform-Independent File System Manipulation</title> + &factories; + </chapter> + <chapter id="chap-precious"> <title>Preventing Removal of Targets: the &Precious; Function</title> &precious; @@ -273,6 +306,21 @@ Tools() --> + <appendix id="app-variables"> + <title>Construction Variables</title> + &variables; + </appendix> + + <appendix id="app-builders"> + <title>Builders</title> + &builders; + </appendix> + + <appendix id="app-tools"> + <title>Tools</title> + &tools; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; @@ -280,6 +328,11 @@ <!-- + <appendix id="app-python"> + <title>Python Overview</title> + &example; + </appendix> + <appendix id="app-example"> <title>Complex &SCons; Example</title> &example; diff --git a/doc/user/nodes.in b/doc/user/nodes.in index fd9846a..a5d05dc 100644 --- a/doc/user/nodes.in +++ b/doc/user/nodes.in @@ -52,7 +52,7 @@ For example, suppose that we want to build the two object files that make up a program with different options. - This would mean calling the &Object; + This would mean calling the &b-link-Object; builder once for each object file, specifying the desired options: @@ -67,7 +67,7 @@ One way to combine these object files into the resulting program - would be to call the &Program; + would be to call the &b-link-Program; builder with the names of the object files listed as sources: @@ -94,9 +94,9 @@ <para> A better solution is to assign the lists of targets - returned by the calls to the &Object; builder to variables, + returned by the calls to the &b-Object; builder to variables, which we can then concatenate in our - call to the &Program; builder: + call to the &b-Program; builder: </para> @@ -122,7 +122,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -132,7 +132,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -254,7 +254,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -264,7 +264,7 @@ </para> <scons_output example="print" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -311,7 +311,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -347,7 +347,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/nodes.sgml b/doc/user/nodes.sgml index 8e24f14..b6bcb89 100644 --- a/doc/user/nodes.sgml +++ b/doc/user/nodes.sgml @@ -52,7 +52,7 @@ For example, suppose that we want to build the two object files that make up a program with different options. - This would mean calling the &Object; + This would mean calling the &b-link-Object; builder once for each object file, specifying the desired options: @@ -67,7 +67,7 @@ One way to combine these object files into the resulting program - would be to call the &Program; + would be to call the &b-link-Program; builder with the names of the object files listed as sources: @@ -94,9 +94,9 @@ <para> A better solution is to assign the lists of targets - returned by the calls to the &Object; builder to variables, + returned by the calls to the &b-Object; builder to variables, which we can then concatenate in our - call to the &Program; builder: + call to the &b-Program; builder: </para> @@ -351,7 +351,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/parseconfig.in b/doc/user/parseconfig.in new file mode 100644 index 0000000..d3f563c --- /dev/null +++ b/doc/user/parseconfig.in @@ -0,0 +1,81 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + Configuring the right options to build programs to work with the + libraries--especially shared libraries--installed on a POSIX system + can be very complicated. + Various utilies with names that end in <filename>config</filename> + can return command-line options for the + GNU Compiler Collection + + </para> + + <para> + + &SCons; construction environments have a &ParseConfig; method + that executes a utility and configures + the appropriate construction variables + in the environment + based on the command-line options + returned by the specified command. + + </para> + + </para> + + <scons_example name="ParseConfig1"> + <file name="SConstruct" printme="1"> + env = Environment() + env.ParseConfig("pkg-config") + </file> + <file name="f1.c"> + int f1() { } + </file> + <file name="f2.c"> + int f2() { } + </file> + <file name="f3.c"> + int f3() { } + </file> + </scons_example> + + <para> + + &SCons; will execute the specified command string + and XXX + + </para> + + <scons_output example="ParseConfig1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + XXX + + </para> diff --git a/doc/user/parseconfig.sgml b/doc/user/parseconfig.sgml new file mode 100644 index 0000000..067ef37 --- /dev/null +++ b/doc/user/parseconfig.sgml @@ -0,0 +1,72 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + Configuring the right options to build programs to work with the + libraries--especially shared libraries--installed on a POSIX system + can be very complicated. + Various utilies with names that end in <filename>config</filename> + can return command-line options for the + GNU Compiler Collection + + </para> + + <para> + + &SCons; construction environments have a &ParseConfig; method + that executes a utility and configures + the appropriate construction variables + in the environment + based on the command-line options + returned by the specified command. + + </para> + + </para> + + <programlisting> + env = Environment() + env.ParseConfig("pkg-config") + </programlisting> + + <para> + + &SCons; will execute the specified command string + and XXX + + </para> + + <screen> + % <userinput>scons -Q</userinput> + scons: `.' is up to date. + Must specify package names on the command line + </screen> + + <para> + + XXX + + </para> diff --git a/doc/user/precious.in b/doc/user/precious.in index fb32f2b..f5e000b 100644 --- a/doc/user/precious.in +++ b/doc/user/precious.in @@ -79,7 +79,7 @@ which the C<AfterBuild> method is called. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/preface.in b/doc/user/preface.in index 190dad1..9d0323e 100644 --- a/doc/user/preface.in +++ b/doc/user/preface.in @@ -228,7 +228,8 @@ One word of warning as you read through this Guide: Like too much Open Source software out there, - the &SCons; documentation lags the available features. + the &SCons; documentation isn't always + kept up-to-date with the available features. In other words, there's a lot that &SCons; can do that isn't yet covered in this User's Guide. diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml index dfececd..47dbd98 100644 --- a/doc/user/preface.sgml +++ b/doc/user/preface.sgml @@ -228,7 +228,8 @@ One word of warning as you read through this Guide: Like too much Open Source software out there, - the &SCons; documentation lags the available features. + the &SCons; documentation isn't always + kept up-to-date with the available features. In other words, there's a lot that &SCons; can do that isn't yet covered in this User's Guide. diff --git a/doc/user/python.in b/doc/user/python.in new file mode 100644 index 0000000..e2a7cdd --- /dev/null +++ b/doc/user/python.in @@ -0,0 +1,154 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <!-- + + <section> + <title>Python Overview</title> + + <para> + + This section will provide a brief overview of + the Python programming language. + Skip this section if you are already familiar with Python + (or you're really intent on diving into &SCons; + and just picking up things as you go). + + </para> + + <para> + + Python has a lot of good + documentation freely available on-line + to help you get started. + The standard tutorial is available at XXX. + + + </para> + + <para> + + Python is very easy to pick up. + + </para> + + <para> + + Python variables must be assigned to before they can be referenced. + + </para> + + <para> + + Assignment is like most programming languages: + + x = 1 + 2 + z = 3 * x + + </para> + + <para> + + Function calls look like most language function calls: + + a = f(g) + + </para> + + <para> + + Define functions like so: + + def func(arg1, arg2): + return arg1 * arg 2 + + The number of parameters + + </para> + + <para> + + Strings can be enclosed in single quotes or double quotes, + backslashes are used to escape characters, + triple-quote syntax lets you include quotes and newlines, + raw strings begin with 'r'. + + </para> + + <para> + + Lists are enclosed in square brackets, + list items are separated by commas. + List references use square brackets and integer index values, + slice notation lets you select, delete or replace a range. + + </para> + + <para> + + Dictionaries (hashes) are enclosed in curly brackets, + : separates keys from values, + , separates items. + Dictionary values are referenced using square brackets. + + </para> + + <para> + + Access class attributes (including methods) using a '.'. + + </para> + + <para> + + if: statements look like + + elif: statements look like + + else: statements look like + + </para> + + <para> + + for: statements look like + + while: statements look like + + break statements look like + + continue statements look like + + </para> + + <para> + + pass + + </para> + + </section> + + --> diff --git a/doc/user/python.sgml b/doc/user/python.sgml new file mode 100644 index 0000000..e2a7cdd --- /dev/null +++ b/doc/user/python.sgml @@ -0,0 +1,154 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <!-- + + <section> + <title>Python Overview</title> + + <para> + + This section will provide a brief overview of + the Python programming language. + Skip this section if you are already familiar with Python + (or you're really intent on diving into &SCons; + and just picking up things as you go). + + </para> + + <para> + + Python has a lot of good + documentation freely available on-line + to help you get started. + The standard tutorial is available at XXX. + + + </para> + + <para> + + Python is very easy to pick up. + + </para> + + <para> + + Python variables must be assigned to before they can be referenced. + + </para> + + <para> + + Assignment is like most programming languages: + + x = 1 + 2 + z = 3 * x + + </para> + + <para> + + Function calls look like most language function calls: + + a = f(g) + + </para> + + <para> + + Define functions like so: + + def func(arg1, arg2): + return arg1 * arg 2 + + The number of parameters + + </para> + + <para> + + Strings can be enclosed in single quotes or double quotes, + backslashes are used to escape characters, + triple-quote syntax lets you include quotes and newlines, + raw strings begin with 'r'. + + </para> + + <para> + + Lists are enclosed in square brackets, + list items are separated by commas. + List references use square brackets and integer index values, + slice notation lets you select, delete or replace a range. + + </para> + + <para> + + Dictionaries (hashes) are enclosed in curly brackets, + : separates keys from values, + , separates items. + Dictionary values are referenced using square brackets. + + </para> + + <para> + + Access class attributes (including methods) using a '.'. + + </para> + + <para> + + if: statements look like + + elif: statements look like + + else: statements look like + + </para> + + <para> + + for: statements look like + + while: statements look like + + break statements look like + + continue statements look like + + </para> + + <para> + + pass + + </para> + + </section> + + --> diff --git a/doc/user/repositories.in b/doc/user/repositories.in index 79d9a75..d2c9236 100644 --- a/doc/user/repositories.in +++ b/doc/user/repositories.in @@ -240,7 +240,7 @@ subdirectories under the repository tree. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -264,7 +264,7 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> gcc -c /usr/repository1/hello.c -o hello.o gcc -o hello hello.o </scons_output> @@ -289,7 +289,7 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -376,8 +376,8 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex4"> - <command>cd /usr/repository1</command> - <command>scons -Q</command> + <scons_output_command>cd /usr/repository1</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -402,9 +402,9 @@ subdirectories under the repository tree. <!-- <scons_output example="ex4"> - <command>cd $HOME/build</command> - <command>edit hello.c</command> - <command>scons -Q -Y __ROOT__/usr/repository1</command> + <scons_output_command>cd $HOME/build</scons_output_command> + <scons_output_command>edit hello.c</scons_output_command> + <scons_output_command>scons -Q -Y __ROOT__/usr/repository1</scons_output_command> </scons_output> --> <screen> diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml index e728bc4..0392853 100644 --- a/doc/user/repositories.sgml +++ b/doc/user/repositories.sgml @@ -374,9 +374,9 @@ subdirectories under the repository tree. <!-- <scons_output example="ex4"> - <command>cd $HOME/build</command> - <command>edit hello.c</command> - <command>scons -Q -Y __ROOT__/usr/repository1</command> + <scons_output_command>cd $HOME/build</scons_output_command> + <scons_output_command>edit hello.c</scons_output_command> + <scons_output_command>scons -Q -Y __ROOT__/usr/repository1</scons_output_command> </scons_output> --> <screen> diff --git a/doc/user/scanners.in b/doc/user/scanners.in index 946c058..a0029ef 100644 --- a/doc/user/scanners.in +++ b/doc/user/scanners.in @@ -228,7 +228,7 @@ over the file scanning rather than being called for each input line: A list of directories that form the search path for included files for this scanner. - This is how &SCons; handles the &CPPPATH; and &LIBPATH; + This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH; variables. </para> @@ -257,7 +257,7 @@ over the file scanning rather than being called for each input line: which typically takes an <literal>skeys</literal> argument to associate the type of file suffix with this scanner. The Scanner object must then be associated with the - &SCANNERS; construction variable of a construction environment, + &cv-link-SCANNERS; construction variable of a construction environment, typically by using the &Append; method: </para> @@ -320,10 +320,10 @@ over the file scanning rather than being called for each input line: </para> <scons_output example="scan"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</command> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml index 4632369..b4756c5 100644 --- a/doc/user/scanners.sgml +++ b/doc/user/scanners.sgml @@ -228,7 +228,7 @@ over the file scanning rather than being called for each input line: A list of directories that form the search path for included files for this scanner. - This is how &SCons; handles the &CPPPATH; and &LIBPATH; + This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH; variables. </para> @@ -257,7 +257,7 @@ over the file scanning rather than being called for each input line: which typically takes an <literal>skeys</literal> argument to associate the type of file suffix with this scanner. The Scanner object must then be associated with the - &SCANNERS; construction variable of a construction environment, + &cv-link-SCANNERS; construction variable of a construction environment, typically by using the &Append; method: </para> @@ -306,10 +306,10 @@ over the file scanning rather than being called for each input line: </para> <scons_output example="scan"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</command> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/sconf.in b/doc/user/sconf.in index 525b0fc..14c10b7 100644 --- a/doc/user/sconf.in +++ b/doc/user/sconf.in @@ -67,6 +67,28 @@ <para> + &SCons; provides a number of basic checks, + as well as a mechanism for adding your own custom checks. + + </para> + + <para> + + Note that &SCons; uses its own dependency + mechanism to determine when a check + needs to be run--that is, + &SCons; does not run the checks + every time it is invoked, + but caches the values returned by previous checks + and uses the cached values unless something has changed. + This saves a tremendous amount + of developer time while working on + cross-platform build issues. + + </para> + + <para> + The next sections describe the basic checks that &SCons; supports, as well as how to add your own custom checks. @@ -229,14 +251,14 @@ </para> - <programlisting> + <sconstruct> env = Environment() conf = Configure(env) if not conf.CheckType('off_t', '#include &lt;sys/types.h&gt;\n'): print 'Did not find off_t typedef, assuming int' conf.env.Append(CCFLAGS = '-Doff_t=int') env = conf.Finish() - </programlisting> + </sconstruct> </section> @@ -259,7 +281,7 @@ </para> - <programlisting> + <sconstruct> mylib_test_source_file = """ #include &lt;mylib.h&gt; int main(int argc, char **argv) @@ -274,7 +296,7 @@ result = context.TryLink(mylib_test_source_file, '.c') context.Result(result) return result - </programlisting> + </sconstruct> <para> @@ -336,7 +358,7 @@ </para> - <programlisting> + <sconstruct> mylib_test_source_file = """ #include &lt;mylib.h&gt; int main(int argc, char **argv) @@ -361,7 +383,7 @@ # We would then add actual calls like Program() to build # something using the "env" construction environment. - </programlisting> + </sconstruct> <para> @@ -396,3 +418,54 @@ </screen> </section> + + <section> + <title>Not Configuring When Cleaning Targets</title> + + <para> + + Using multi-platform configuration + as described in the previous sections + will run the configuration commands + even when invoking + <userinput>scons -c</userinput> + to clean targets: + + </para> + + <screen> + % <userinput>scons -Q -c</userinput> + Checking for MyLibrary... ok + Removed foo.o + Removed foo + </screen> + + <para> + + Although running the platform checks + when removing targets doesn't hurt anything, + it's usually unnecessary. + You can avoid this by using the + &GetOption(); method to + check whether the <option>-c</option> (clean) + option has been invoked on the command line: + + </para> + + <sconstruct> + env = Environment() + if not env.GetOption('clean'): + conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) + if not conf.CheckMyLibrary(): + print 'MyLibrary is not installed!' + Exit(1) + env = conf.Finish() + </sconstruct> + + <screen> + % <userinput>scons -Q -c</userinput> + Removed foo.o + Removed foo + </screen> + + </section> diff --git a/doc/user/sconf.sgml b/doc/user/sconf.sgml index 2e2a698..997c97d 100644 --- a/doc/user/sconf.sgml +++ b/doc/user/sconf.sgml @@ -67,6 +67,28 @@ <para> + &SCons; provides a number of basic checks, + as well as a mechanism for adding your own custom checks. + + </para> + + <para> + + Note that &SCons; uses its own dependency + mechanism to determine when a check + needs to be run--that is, + &SCons; does not run the checks + every time it is invoked, + but caches the values returned by previous checks + and uses the cached values unless something has changed. + This saves a tremendous amount + of developer time while working on + cross-platform build issues. + + </para> + + <para> + The next sections describe the basic checks that &SCons; supports, as well as how to add your own custom checks. @@ -396,3 +418,54 @@ </screen> </section> + + <section> + <title>Not Configuring When Cleaning Targets</title> + + <para> + + Using multi-platform configuration + as described in the previous sections + will run the configuration commands + even when invoking + <userinput>scons -c</userinput> + to clean targets: + + </para> + + <screen> + % <userinput>scons -Q -c</userinput> + Checking for MyLibrary... ok + Removed foo.o + Removed foo + </screen> + + <para> + + Although running the platform checks + when removing targets doesn't hurt anything, + it's usually unnecessary. + You can avoid this by using the + &GetOption;(); method to + check whether the <option>-c</option> (clean) + option has been invoked on the command line: + + </para> + + <programlisting> + env = Environment() + if not env.GetOption('clean'): + conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) + if not conf.CheckMyLibrary(): + print 'MyLibrary is not installed!' + Exit(1) + env = conf.Finish() + </programlisting> + + <screen> + % <userinput>scons -Q -c</userinput> + Removed foo.o + Removed foo + </screen> + + </section> diff --git a/doc/user/separate.in b/doc/user/separate.in index d613f42..6d497a2 100644 --- a/doc/user/separate.in +++ b/doc/user/separate.in @@ -160,9 +160,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="ex1"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> <para> @@ -357,9 +357,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="ex_builddir"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> <para> @@ -388,9 +388,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="ex_duplicate_0"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> </section> @@ -439,9 +439,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="example_builddir_sconscript"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> <para> diff --git a/doc/user/simple.in b/doc/user/simple.in index 4ac6d33..57fdd3a 100644 --- a/doc/user/simple.in +++ b/doc/user/simple.in @@ -77,7 +77,7 @@ and the input file from which you want it built (the <filename>hello.c</filename> file). - &Program; is a &builder_method;, + &b-link-Program; is a <firstterm>builder_method</firstterm>, a Python call that tells &SCons; that you want to build an executable program. @@ -92,7 +92,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -103,7 +103,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -147,10 +147,10 @@ <para> - The &Program; builder method is only one of + The &b-link-Program; builder method is only one of many builder methods that &SCons; provides to build different types of files. - Another is the &Object; builder method, + Another is the &b-link-Object; builder method, which tells &SCons; to build an object file from the specified source file: @@ -173,7 +173,7 @@ </para> <scons_output example="Object" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -184,7 +184,7 @@ </para> <scons_output example="Object" os="win32"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> </section> @@ -195,8 +195,8 @@ <para> &SCons; also makes building with Java extremely easy. - Unlike the &Program; and &Object; builder methods, - however, the &Java; builder method + Unlike the &b-link-Program; and &b-link-Object; builder methods, + however, the &b-link-Java; builder method requires that you specify the name of a destination directory in which you want the class files placed, @@ -231,7 +231,7 @@ </para> <scons_output example="java" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -272,8 +272,8 @@ </scons_example> <scons_output example="clean" os="posix"> - <command>scons</command> - <command>scons -c</command> + <scons_output_command>scons</scons_output_command> + <scons_output_command>scons -c</scons_output_command> </scons_output> <para> @@ -283,8 +283,8 @@ </para> <scons_output example="clean" os="win32"> - <command>scons</command> - <command>scons -c</command> + <scons_output_command>scons</scons_output_command> + <scons_output_command>scons -c</scons_output_command> </scons_output> <para> @@ -378,7 +378,7 @@ which to do things. </para> </footnote> - In other words, when you call the &Program; builder + In other words, when you call the &b-link-Program; builder (or any other builder method), you're not telling &SCons; to build the program at the instant the builder method is called. @@ -396,7 +396,7 @@ <para> &SCons; reflects this distinction between - <emphasis>calling a builder method like</emphasis> &Program;> + <emphasis>calling a builder method like</emphasis> &b-Program;> and <emphasis>actually building the program</emphasis> by printing the status messages that indicate when it's "just reading" the &SConstruct; file, @@ -415,7 +415,7 @@ Python has a <literal>print</literal> statement that prints a string of characters to the screen. If we put <literal>print</literal> statements around - our calls to the &Program; builder method: + our calls to the &b-Program; builder method: </para> @@ -447,7 +447,7 @@ </para> <scons_output example="declarative" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -475,7 +475,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -501,7 +501,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml index b925d04..fc68d17 100644 --- a/doc/user/simple.sgml +++ b/doc/user/simple.sgml @@ -72,7 +72,7 @@ and the input file from which you want it built (the <filename>hello.c</filename> file). - &Program; is a &builder_method;, + &b-link-Program; is a <firstterm>builder_method</firstterm>, a Python call that tells &SCons; that you want to build an executable program. @@ -154,10 +154,10 @@ <para> - The &Program; builder method is only one of + The &b-link-Program; builder method is only one of many builder methods that &SCons; provides to build different types of files. - Another is the &Object; builder method, + Another is the &b-link-Object; builder method, which tells &SCons; to build an object file from the specified source file: @@ -207,8 +207,8 @@ <para> &SCons; also makes building with Java extremely easy. - Unlike the &Program; and &Object; builder methods, - however, the &Java; builder method + Unlike the &b-link-Program; and &b-link-Object; builder methods, + however, the &b-link-Java; builder method requires that you specify the name of a destination directory in which you want the class files placed, @@ -401,7 +401,7 @@ which to do things. </para> </footnote> - In other words, when you call the &Program; builder + In other words, when you call the &b-link-Program; builder (or any other builder method), you're not telling &SCons; to build the program at the instant the builder method is called. @@ -419,7 +419,7 @@ <para> &SCons; reflects this distinction between - <emphasis>calling a builder method like</emphasis> &Program;> + <emphasis>calling a builder method like</emphasis> &b-Program;> and <emphasis>actually building the program</emphasis> by printing the status messages that indicate when it's "just reading" the &SConstruct; file, @@ -438,7 +438,7 @@ Python has a <literal>print</literal> statement that prints a string of characters to the screen. If we put <literal>print</literal> statements around - our calls to the &Program; builder method: + our calls to the &b-Program; builder method: </para> diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in index c40c512..04c76d0 100644 --- a/doc/user/sourcecode.in +++ b/doc/user/sourcecode.in @@ -54,7 +54,7 @@ </scons_example> <scons_output example="ex_bitkeeper"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -77,7 +77,7 @@ </scons_example> <scons_output example="ex_cvs"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -103,7 +103,7 @@ </scons_example> <scons_output example="ex_rcs"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -129,7 +129,7 @@ </scons_example> <scons_output example="ex_sccs"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -154,7 +154,7 @@ </scons_example> <scons_output example="ex_subversion"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/sourcecode.sgml b/doc/user/sourcecode.sgml index daa9ad7..6ea0b21 100644 --- a/doc/user/sourcecode.sgml +++ b/doc/user/sourcecode.sgml @@ -153,7 +153,7 @@ </scons_example> <scons_output example="ex_subversion"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/tools.in b/doc/user/tools.in new file mode 100644 index 0000000..8eaa35e --- /dev/null +++ b/doc/user/tools.in @@ -0,0 +1,38 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +Tools that are +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&tools-gen; + +</variablelist> diff --git a/doc/user/tools.sgml b/doc/user/tools.sgml new file mode 100644 index 0000000..8eaa35e --- /dev/null +++ b/doc/user/tools.sgml @@ -0,0 +1,38 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +Tools that are +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&tools-gen; + +</variablelist> diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in index e5c008d..206e50e 100644 --- a/doc/user/troubleshoot.in +++ b/doc/user/troubleshoot.in @@ -77,9 +77,9 @@ </para> <scons_output example="explain1" os="posix"> - <command>scons -Q</command> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -100,7 +100,7 @@ </para> <scons_output example="explain1" os="posix"> - <command>scons -Q --debug=explain</command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> </scons_output> <para> @@ -145,9 +145,9 @@ </scons_example> <scons_output example="explain2" os="posix"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF file2.c]">edit file2.c</command> - <command>scons -Q --debug=explain</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF file2.c]">edit file2.c</scons_output_command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> </scons_output> <para> @@ -188,9 +188,121 @@ </scons_example> <scons_output example="explain3" os="posix"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q --debug=explain</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> + </scons_output> + + </section> + + <section> + <title>What's in That Construction Environment? the &Dump; Method</title> + + <para> + + When you create a construction environment, + &SCons; populates it + with construction variables that are set up + for various compilers, linkers and utilities + that it finds on your system. + Although this is usually helpful and what you want, + it might be frustrating if &SCons; + doesn't set certain variables that you + expect to be sit. + In situations like this, + it's sometimes helpful to use the + construction environment &Dump; method + to print all or some of + the construction variables. + Note that the &Dump; method + <emphasis>returns</emphasis> + the representation of the variables + in the environment + for you to print (or otherwise manipulate): + + </para> + + <scons_example name="Dump"> + <file name="SConstruct" print="1"> + env = Environment() + print env.Dump() + </file> + </scons_example> + + <para> + + On a POSIX system with gcc installed, + this might generate: + + </para> + + <scons_output example="Dump" os="posix" tools="gcc"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + On a Windows system with Visual C++ + the output might look like: + + </para> + + <scons_output example="Dump" os="win32" tools="msvc"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + The construction environments in these examples have + actually been restricted to just gcc and Visual C++, + respectively. + In a real-life situation, + the construction environments will + likely contain a great many more variables. + + </para> + + <para> + + To make it easier to see just what you're + interested in, + the &Dump; method allows you to + specify a specific constrcution variable + that you want to disply. + For example, + it's not unusual to want to verify + the external environment used to execute build commands, + to make sure that the PATH and other + environment variables are set up the way they should be. + You can do this as follows: + + </para> + + <scons_example name="Dump_ENV"> + <file name="SConstruct" print="1"> + env = Environment() + print env.Dump('ENV') + </file> + </scons_example> + + <para> + + Which might display the following when executed on a POSIX system: + + </para> + + <scons_output example="Dump_ENV" os="posix"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + And the following when executed on a Windows system: + + </para> + + <scons_output example="Dump_ENV" os="win32"> + <scons_output_command>scons</scons_output_command> </scons_output> </section> diff --git a/doc/user/troubleshoot.sgml b/doc/user/troubleshoot.sgml index aee2aee..5cd1c9e 100644 --- a/doc/user/troubleshoot.sgml +++ b/doc/user/troubleshoot.sgml @@ -185,3 +185,276 @@ </screen> </section> + + <section> + <title>What's in That Construction Environment? the &Dump; Method</title> + + <para> + + When you create a construction environment, + &SCons; populates it + with construction variables that are set up + for various compilers, linkers and utilities + that it finds on your system. + Although this is usually helpful and what you want, + it might be frustrating if &SCons; + doesn't set certain variables that you + expect to be sit. + In situations like this, + it's sometimes helpful to use the + construction environment &Dump; method + to print all or some of + the construction variables. + Note that the &Dump; method + <emphasis>returns</emphasis> + the representation of the variables + in the environment + for you to print (or otherwise manipulate): + + </para> + + + + <para> + + On a POSIX system with gcc installed, + this might generate: + + </para> + + <screen> + % <userinput>scons</userinput> + scons: Reading SConscript files ... + { 'BUILDERS': {}, + 'CPPSUFFIXES': [ '.c', + '.C', + '.cxx', + '.cpp', + '.c++', + '.cc', + '.h', + '.H', + '.hxx', + '.hpp', + '.hh', + '.F', + '.fpp', + '.FPP', + '.S', + '.spp', + '.SPP'], + 'DSUFFIXES': ['.d'], + 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x829dcb4>, + 'ENV': {'PATH': '/usr/local/bin:/bin:/usr/bin'}, + 'ESCAPE': <function escape at 0x837d2a4>, + 'File': <SCons.Defaults.Variable_Method_Caller instance at 0x829e0fc>, + 'IDLSUFFIXES': ['.idl', '.IDL'], + 'INSTALL': <function copyFunc at 0x829db9c>, + 'LIBPREFIX': 'lib', + 'LIBPREFIXES': '$LIBPREFIX', + 'LIBSUFFIX': '.a', + 'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'], + 'OBJPREFIX': '', + 'OBJSUFFIX': '.o', + 'PDFPREFIX': '', + 'PDFSUFFIX': '.pdf', + 'PLATFORM': 'posix', + 'PROGPREFIX': '', + 'PROGSUFFIX': '', + 'PSPAWN': <function piped_env_spawn at 0x837d384>, + 'PSPREFIX': '', + 'PSSUFFIX': '.ps', + 'RDirs': <SCons.Defaults.Variable_Method_Caller instance at 0x829e46c>, + 'SCANNERS': [], + 'SHELL': 'sh', + 'SHLIBPREFIX': '$LIBPREFIX', + 'SHLIBSUFFIX': '.so', + 'SHOBJPREFIX': '$OBJPREFIX', + 'SHOBJSUFFIX': '$OBJSUFFIX', + 'SPAWN': <function spawnvpe_spawn at 0x8377fdc>, + 'TEMPFILE': <class SCons.Defaults.NullCmdGenerator at 0x829ddec>, + 'TOOLS': [], + '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', + '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', + '__RPATH': '$_RPATH', + '_concat': <function _concat at 0x829dc0c>, + '_defines': <function _defines at 0x829dc7c>, + '_stripixes': <function _stripixes at 0x829dc44>} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + On a Windows system with Visual C++ + the output might look like: + + </para> + + <screen> + C:\><userinput>scons</userinput> + scons: Reading SConscript files ... + { 'BUILDERS': {'Object': <SCons.Memoize.MultiStepBuilder object at 0x83493e4>, 'SharedObject': <SCons.Memoize.MultiStepBuilder object at 0x8349fec>, 'StaticObject': <SCons.Memoize.MultiStepBuilder object at 0x83493e4>, 'PCH': <SCons.Memoize.BuilderBase object at 0x83418cc>, 'RES': <SCons.Memoize.BuilderBase object at 0x8367cec>}, + 'CC': 'cl', + 'CCCOM': <SCons.Memoize.FunctionAction object at 0x8340454>, + 'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS', + 'CCFLAGS': ['/nologo'], + 'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'], + 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], + 'CFILESUFFIX': '.c', + 'CPPDEFPREFIX': '/D', + 'CPPDEFSUFFIX': '', + 'CPPSUFFIXES': [ '.c', + '.C', + '.cxx', + '.cpp', + '.c++', + '.cc', + '.h', + '.H', + '.hxx', + '.hpp', + '.hh', + '.F', + '.fpp', + '.FPP', + '.S', + '.spp', + '.SPP'], + 'CXX': '$CC', + 'CXXCOM': '$CXX $CXXFLAGS $CCCOMFLAGS', + 'CXXFILESUFFIX': '.cc', + 'CXXFLAGS': ['$CCFLAGS', '$(', '/TP', '$)'], + 'DSUFFIXES': ['.d'], + 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x829dcb4>, + 'ENV': { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include', + 'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib', + 'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin', + 'PATHEXT': '.COM;.EXE;.BAT;.CMD'}, + 'ESCAPE': <function <lambda> at 0x82339ec>, + 'File': <SCons.Defaults.Variable_Method_Caller instance at 0x829e0fc>, + 'IDLSUFFIXES': ['.idl', '.IDL'], + 'INCPREFIX': '/I', + 'INCSUFFIX': '', + 'INSTALL': <function copyFunc at 0x829db9c>, + 'LIBPREFIX': '', + 'LIBPREFIXES': ['$LIBPREFIX'], + 'LIBSUFFIX': '.lib', + 'LIBSUFFIXES': ['$LIBSUFFIX'], + 'MAXLINELENGTH': 2048, + 'MSVS': {'VERSION': '6.0', 'VERSIONS': ['6.0']}, + 'MSVS_VERSION': '6.0', + 'OBJPREFIX': '', + 'OBJSUFFIX': '.obj', + 'PCHCOM': '$CXX $CXXFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo${TARGETS[1]} /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS', + 'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'], + 'PDFPREFIX': '', + 'PDFSUFFIX': '.pdf', + 'PLATFORM': 'win32', + 'PROGPREFIX': '', + 'PROGSUFFIX': '.exe', + 'PSPAWN': <function piped_spawn at 0x8372bc4>, + 'PSPREFIX': '', + 'PSSUFFIX': '.ps', + 'RC': 'rc', + 'RCCOM': '$RC $_CPPDEFFLAGS $_CPPINCFLAGS $RCFLAGS /fo$TARGET $SOURCES', + 'RCFLAGS': [], + 'RDirs': <SCons.Defaults.Variable_Method_Caller instance at 0x829e46c>, + 'SCANNERS': [], + 'SHCC': '$CC', + 'SHCCCOM': <SCons.Memoize.FunctionAction object at 0x83494bc>, + 'SHCCFLAGS': ['$CCFLAGS'], + 'SHCXX': '$CXX', + 'SHCXXCOM': '$SHCXX $SHCXXFLAGS $CCCOMFLAGS', + 'SHCXXFLAGS': ['$CXXFLAGS'], + 'SHELL': None, + 'SHLIBPREFIX': '', + 'SHLIBSUFFIX': '.dll', + 'SHOBJPREFIX': '$OBJPREFIX', + 'SHOBJSUFFIX': '$OBJSUFFIX', + 'SPAWN': <function spawn at 0x8374c34>, + 'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1, + 'TEMPFILE': <class SCons.Platform.win32.TempFileMunge at 0x835edc4>, + 'TOOLS': ['msvc'], + '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', + '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', + '_concat': <function _concat at 0x829dc0c>, + '_defines': <function _defines at 0x829dc7c>, + '_stripixes': <function _stripixes at 0x829dc44>} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + The construction environments in these examples have + actually been restricted to just gcc and Visual C++, + respectively. + In a real-life situation, + the construction environments will + likely contain a great many more variables. + + </para> + + <para> + + To make it easier to see just what you're + interested in, + the &Dump; method allows you to + specify a specific constrcution variable + that you want to disply. + For example, + it's not unusual to want to verify + the external environment used to execute build commands, + to make sure that the PATH and other + environment variables are set up the way they should be. + You can do this as follows: + + </para> + + + + <para> + + Which might display the following when executed on a POSIX system: + + </para> + + <screen> + % <userinput>scons</userinput> + scons: Reading SConscript files ... + {'PATH': '/usr/local/bin:/bin:/usr/bin'} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + And the following when executed on a Windows system: + + </para> + + <screen> + C:\><userinput>scons</userinput> + scons: Reading SConscript files ... + { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include', + 'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib', + 'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin', + 'PATHEXT': '.COM;.EXE;.BAT;.CMD'} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + </section> diff --git a/doc/user/variables.in b/doc/user/variables.in new file mode 100644 index 0000000..7009996 --- /dev/null +++ b/doc/user/variables.in @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +construction variables that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. +Whether or not setting a construction variable +in a construction environment +will actually have an effect depends on +whether any of the Tools and/or Builders +that use the variable have been +included in the construction environment. + +</para> + +<para> + +In this appendix, we have +appended the initial <envar>$</envar> +(dollar sign) to the beginning of each +variable name when it appears in the text, +but left off the dollar sign +in the left-hand column +where the name appears for each entry. + +</para> + +<variablelist> + +&variables-gen; + +</variablelist> diff --git a/doc/user/variables.sgml b/doc/user/variables.sgml new file mode 100644 index 0000000..7009996 --- /dev/null +++ b/doc/user/variables.sgml @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +construction variables that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. +Whether or not setting a construction variable +in a construction environment +will actually have an effect depends on +whether any of the Tools and/or Builders +that use the variable have been +included in the construction environment. + +</para> + +<para> + +In this appendix, we have +appended the initial <envar>$</envar> +(dollar sign) to the beginning of each +variable name when it appears in the text, +but left off the dollar sign +in the left-hand column +where the name appears for each entry. + +</para> + +<variablelist> + +&variables-gen; + +</variablelist> diff --git a/doc/user/variants.in b/doc/user/variants.in index 82d938b..2bdc394 100644 --- a/doc/user/variants.in +++ b/doc/user/variants.in @@ -49,7 +49,8 @@ is pretty smart about rebuilding things when you change options. <para> - The &BuildDir; function now gives us everything + The &build_dir; keyword argument of + the &SConscript; function provides everything we need to show how easy it is to create variant builds using &SCons;. Suppose, for example, that we want to @@ -79,11 +80,6 @@ is pretty smart about rebuilding things when you change options. Export('env') env.SConscript('src/SConscript', build_dir='build/$PLATFORM') - - # - #BuildDir("#build/$PLATFORM", 'src') - #SConscript("build/$PLATFORM/hello/SConscript") - #SConscript("build/$PLATFORM/world/SConscript") </file> <directory name="src"></directory> <directory name="src/hello"></directory> @@ -125,7 +121,7 @@ is pretty smart about rebuilding things when you change options. </para> <scons_output example="ex_variants" os="posix"> - <command>scons -Q OS=linux</command> + <scons_output_command>scons -Q OS=linux</scons_output_command> </scons_output> <para> @@ -135,7 +131,7 @@ is pretty smart about rebuilding things when you change options. </para> <scons_output example="ex_variants" os="win32"> - <command>scons -Q OS=windows</command> + <scons_output_command>scons -Q OS=windows</scons_output_command> </scons_output> <!-- @@ -149,7 +145,7 @@ is pretty smart about rebuilding things when you change options. </scons_example> <scons_output example="ex_var2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml index 0ef7d1f..57d96e0 100644 --- a/doc/user/variants.sgml +++ b/doc/user/variants.sgml @@ -49,7 +49,8 @@ is pretty smart about rebuilding things when you change options. <para> - The &BuildDir; function now gives us everything + The &build_dir; keyword argument of + the &SConscript; function provides everything we need to show how easy it is to create variant builds using &SCons;. Suppose, for example, that we want to @@ -78,11 +79,6 @@ is pretty smart about rebuilding things when you change options. Export('env') env.SConscript('src/SConscript', build_dir='build/$PLATFORM') - - # - #BuildDir("#build/$PLATFORM", 'src') - #SConscript("build/$PLATFORM/hello/SConscript") - #SConscript("build/$PLATFORM/world/SConscript") </programlisting> <para> @@ -132,7 +128,7 @@ is pretty smart about rebuilding things when you change options. </scons_example> <scons_output example="ex_var2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/src/CHANGES.txt b/src/CHANGES.txt index 2dbb6bf..3acb1cc 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -15,6 +15,8 @@ RELEASE 0.97 - XXX - Fix Java parsing to avoid erroneously identifying a new array of class instances as an anonymous inner class. + - Fix a typo in the man page description of PathIsDirCreate. + From Chad Austin: - Allow Help() to be called multiple times, appending to the help @@ -207,6 +209,14 @@ RELEASE 0.97 - XXX a source_scanner keyword argument to Command() that can be set to DirScanner to get this behavior. + - Documentation changes: Explain that $CXXFLAGS contains $CCFLAGS + by default. Fix a bad target_factory example in the man page. + Add appendices to the User's Guide to cover the available Tools, + Builders and construction variables. Comment out the build of + the old Python 10 paper, which doesn't build on all systems and + is old enough at this point that it probably isn't worth the + effort to make it do so. + From Wayne Lee: - Avoid "maximum recursion limit" errors when removing $(-$) pairs @@ -294,6 +304,9 @@ RELEASE 0.97 - XXX - Supply a better error message when a construction variable expansion has an unknown attribute. + - Documentation changes: Update the man page to describe use of + filenames or Nodes in $LIBS. + From Chris Pawling: - Have the linkloc tool use $MSVS_VERSION to select the Microsoft @@ -419,6 +432,11 @@ RELEASE 0.97 - XXX - Add a PathAccept validator to the list of new canned PathOption validators. + From Jeff Squyres: + + - Documentation changes: Use $CPPDEFINES instead of $CCFLAGS in man + page examples. + From Levi Stephen: - Allow $JARCHDIR to be expanded to other construction variables. diff --git a/src/engine/MANIFEST-xml.in b/src/engine/MANIFEST-xml.in new file mode 100644 index 0000000..d8082c7 --- /dev/null +++ b/src/engine/MANIFEST-xml.in @@ -0,0 +1,86 @@ +SCons/Action.xml +SCons/Defaults.xml +SCons/Environment.xml +SCons/Platform/__init__.xml +SCons/Platform/posix.xml +SCons/Platform/win32.xml +SCons/Tool/386asm.xml +SCons/Tool/aixcc.xml +SCons/Tool/aixc++.xml +SCons/Tool/aixf77.xml +SCons/Tool/aixlink.xml +SCons/Tool/applelink.xml +SCons/Tool/ar.xml +SCons/Tool/as.xml +SCons/Tool/bcc32.xml +SCons/Tool/BitKeeper.xml +SCons/Tool/cc.xml +SCons/Tool/cvf.xml +SCons/Tool/CVS.xml +SCons/Tool/c++.xml +SCons/Tool/default.xml +SCons/Tool/dmd.xml +SCons/Tool/dvipdf.xml +SCons/Tool/dvips.xml +SCons/Tool/f77.xml +SCons/Tool/f90.xml +SCons/Tool/f95.xml +SCons/Tool/fortran.xml +SCons/Tool/g77.xml +SCons/Tool/gas.xml +SCons/Tool/gcc.xml +SCons/Tool/gnulink.xml +SCons/Tool/gs.xml +SCons/Tool/g++.xml +SCons/Tool/hpcc.xml +SCons/Tool/hpc++.xml +SCons/Tool/hplink.xml +SCons/Tool/icc.xml +SCons/Tool/icl.xml +SCons/Tool/ifl.xml +SCons/Tool/ifort.xml +SCons/Tool/ilink32.xml +SCons/Tool/ilink.xml +SCons/Tool/__init__.xml +SCons/Tool/intelc.xml +SCons/Tool/jar.xml +SCons/Tool/javac.xml +SCons/Tool/javah.xml +SCons/Tool/latex.xml +SCons/Tool/lex.xml +SCons/Tool/linkloc.xml +SCons/Tool/link.xml +SCons/Tool/m4.xml +SCons/Tool/masm.xml +SCons/Tool/midl.xml +SCons/Tool/mingw.xml +SCons/Tool/mslib.xml +SCons/Tool/mslink.xml +SCons/Tool/msvc.xml +SCons/Tool/msvs.xml +SCons/Tool/mwcc.xml +SCons/Tool/mwld.xml +SCons/Tool/nasm.xml +SCons/Tool/pdflatex.xml +SCons/Tool/pdftex.xml +SCons/Tool/Perforce.xml +SCons/Tool/qt.xml +SCons/Tool/RCS.xml +SCons/Tool/rmic.xml +SCons/Tool/rpcgen.xml +SCons/Tool/SCCS.xml +SCons/Tool/sgiar.xml +SCons/Tool/sgicc.xml +SCons/Tool/sgic++.xml +SCons/Tool/sgilink.xml +SCons/Tool/Subversion.xml +SCons/Tool/sunar.xml +SCons/Tool/suncc.xml +SCons/Tool/sunc++.xml +SCons/Tool/sunlink.xml +SCons/Tool/swig.xml +SCons/Tool/tar.xml +SCons/Tool/tex.xml +SCons/Tool/tlib.xml +SCons/Tool/yacc.xml +SCons/Tool/zip.xml diff --git a/src/engine/SCons/Action.xml b/src/engine/SCons/Action.xml new file mode 100644 index 0000000..c225318 --- /dev/null +++ b/src/engine/SCons/Action.xml @@ -0,0 +1,67 @@ +<!-- __COPYRIGHT__ --> +<cvar name="PRINT_CMD_LINE_FUNC"> +<summary> +A Python function used to print the command lines as they are executed +(assuming command printing is not disabled by the +<option>-q</option> +or +<option>-s</option> +options or their equivalents). +The function should take four arguments: +<varname>s</varname>, +the command being executed (a string), +<varname>target</varname>, +the target being built (file node, list, or string name(s)), +<varname>source</varname>, +the source(s) used (file node, list, or string name(s)), and +<varname>env</varname>, +the environment being used. + +The function must do the printing itself. The default implementation, +used if this variable is not set or is None, is: +<example> +def print_cmd_line(s, target, source, env): + sys.stdout.write(s + "\n") +</example> + +Here's an example of a more interesting function: + +<example> +def print_cmd_line(s, target, source, env): + sys.stdout.write("Building %s -> %s...\n" % + (' and '.join([str(x) for x in source]), + ' and '.join([str(x) for x in target]))) +env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line) +env.Program('foo', 'foo.c') +</example> + +This just prints "Building <varname>targetname</varname> from <varname>sourcename</varname>..." instead +of the actual commands. +Such a function could also log the actual commands to a log file, +for example. +</summary> +</cvar> + +<cvar name="SPAWN"> +<summary> +A command interpreter function that will be called to execute command line +strings. The function must expect the following arguments: + +<example> +def spawn(shell, escape, cmd, args, env): +</example> + +<varname>sh</varname> +is a string naming the shell program to use. +<varname>escape</varname> +is a function that can be called to escape shell special characters in +the command line. +<varname>cmd</varname> +is the path to the command to be executed. +<varname>args</varname> +is the arguments to the command. +<varname>env</varname> +is a dictionary of the environment variables +in which the command should be executed. +</summary> +</cvar> diff --git a/src/engine/SCons/Defaults.py b/src/engine/SCons/Defaults.py index 8ade792..44d10fa 100644 --- a/src/engine/SCons/Defaults.py +++ b/src/engine/SCons/Defaults.py @@ -121,10 +121,6 @@ LinkAction = SCons.Action.Action("$LINKCOM", "$LINKCOMSTR") ShLinkAction = SCons.Action.Action("$SHLINKCOM", "$SHLINKCOMSTR") LdModuleLinkAction = SCons.Action.Action("$LDMODULECOM", "$LDMODULECOMSTR") -ArAction = SCons.Action.Action("$ARCOM", "$ARCOMSTR") - -LexAction = SCons.Action.Action("$LEXCOM", "$LEXCOMSTR") -YaccAction = SCons.Action.Action("$YACCCOM", "$YACCCOMSTR") def DVI(): """Common function to generate a DVI file Builder.""" diff --git a/src/engine/SCons/Defaults.xml b/src/engine/SCons/Defaults.xml new file mode 100644 index 0000000..8d90ce2 --- /dev/null +++ b/src/engine/SCons/Defaults.xml @@ -0,0 +1,471 @@ +<!-- __COPYRIGHT__ --> +<builder name="DVI"> +<summary> +Builds a <filename>.dvi</filename> file +from a <filename>.tex</filename>, +<filename>.ltx</filename> or <filename>.latex</filename> input file. +If the source file suffix is <filename>.tex</filename>, +&scons; +will examine the contents of the file; +if the string +<literal>\documentclass</literal> +or +<literal>\documentstyle</literal> +is found, the file is assumed to be a LaTeX file and +the target is built by invoking the &cv-LATEXCOM; command line; +otherwise, the &cv-TEXCOM; command line is used. +If the file is a LaTeX file, +the +&b-DVI; +builder method will also examine the contents +of the +<filename>.aux</filename> +file +and invoke the &cv-BIBTEX; command line +if the string +<literal>bibdata</literal> +is found, +and will examine the contents +<filename>.log</filename> +file and re-run the &cv-LATEXCOM; command +if the log file says it is necessary. + +The suffix <filename>.dvi</filename> +(hard-coded within TeX itself) +is automatically added to the target +if it is not already present. +Examples: + +<example> +# builds from aaa.tex +env.DVI(target = 'aaa.dvi', source = 'aaa.tex') +# builds bbb.dvi +env.DVI(target = 'bbb', source = 'bbb.ltx') +# builds from ccc.latex +env.DVI(target = 'ccc.dvi', source = 'ccc.latex') +</example> +</summary> +</builder> + +<builder name="PDF"> +<summary> +Builds a <filename>.pdf</filename> file +from a <filename>.dvi</filename> input file +(or, by extension, a <filename>.tex</filename>, +<filename>.ltx</filename>, +or +<filename>.latex</filename> input file). +The suffix specified by the &cv-PDFSUFFIX; construction variable +(<filename>.pdf</filename> by default) +is added automatically to the target +if it is not already present. Example: + +<example> +# builds from aaa.tex +env.PDF(target = 'aaa.pdf', source = 'aaa.tex') +# builds bbb.pdf from bbb.dvi +env.PDF(target = 'bbb', source = 'bbb.dvi') +</example> +</summary> +</builder> + +<cvar name ="_concat"> +<summary> +A function used to produce variables like &cv-_CPPINCFLAGS;. It takes +four or five +arguments: a prefix to concatenate onto each element, a list of +elements, a suffix to concatenate onto each element, an environment +for variable interpolation, and an optional function that will be +called to transform the list before concatenation. + +<example> +env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)', +</example> +</summary> +</cvar> + +<cvar name="CPPDEFINES"> +<summary> +A platform independent specification of C preprocessor definitions. +The definitions will be added to command lines +through the automatically-generated +&cv-_CPPDEFFLAGS; construction variable (see below), +which is constructed according to +the type of value of &cv-CPPDEFINES;: + +If &cv-CPPDEFINES; is a string, +the values of the +&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; +construction variables +will be added to the beginning and end. + +<example> +# Will add -Dxyz to POSIX compiler command lines, +# and /Dxyz to Microsoft Visual C++ command lines. +env = Environment(CPPDEFINES='xyz') +</example> + +If &cv-CPPDEFINES; is a list, +the values of the +&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; +construction variables +will be appended to the beginning and end +of each element in the list. +If any element is a list or tuple, +then the first item is the name being +defined and the second item is its value: + +<example> +# Will add -DB=2 -DA to POSIX compiler command lines, +# and /DB=2 /DA to Microsoft Visual C++ command lines. +env = Environment(CPPDEFINES=[('B', 2), 'A']) +</example> + +If &cv-CPPDEFINES; is a dictionary, +the values of the +&cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; +construction variables +will be appended to the beginning and end +of each item from the dictionary. +The key of each dictionary item +is a name being defined +to the dictionary item's corresponding value; +if the value is +<literal>None</literal>, +then the name is defined without an explicit value. +Note that the resulting flags are sorted by keyword +to ensure that the order of the options on the +command line is consistent each time +&scons; is run. + +<example> +# Will add -DA -DB=2 to POSIX compiler command lines, +# and /DA /DB=2 to Microsoft Visual C++ command lines. +env = Environment(CPPDEFINES={'B':2, 'A':None}) +</example> +</summary> +</cvar> + +<cvar name="_CPPDEFFLAGS"> +<summary> +An automatically-generated construction variable +containing the C preprocessor command-line options +to define values. +The value of &cv-_CPPDEFFLAGS; is created +by appending &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; +to the beginning and end +of each directory in &cv-CPPDEFINES;. +</summary> +</cvar> + +<cvar name="CPPDEFPREFIX"> +<summary> +The prefix used to specify preprocessor definitions +on the C compiler command line. +This will be appended to the beginning of each definition +in the &cv-CPPDEFINES; construction variable +when the &cv-_CPPDEFFLAGS; variable is automatically generated. +</summary> +</cvar> + +<cvar name="CPPDEFSUFFIX"> +<summary> +The suffix used to specify preprocessor definitions +on the C compiler command line. +This will be appended to the end of each definition +in the &cv-CPPDEFINES; construction variable +when the &cv-_CPPDEFFLAGS; variable is automatically generated. +</summary> +</cvar> + +<cvar name="_CPPINCFLAGS"> +<summary> +An automatically-generated construction variable +containing the C preprocessor command-line options +for specifying directories to be searched for include files. +The value of &cv-_CPPINCFLAGS; is created +by appending &cv-INCPREFIX; and &cv-INCSUFFIX; +to the beginning and end +of each directory in &cv-CPPPATH;. +</summary> +</cvar> + +<cvar name="CPPPATH"> +<summary> +The list of directories that the C preprocessor will search for include +directories. The C/C++ implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in CCFLAGS or CXXFLAGS because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in CPPPATH will be looked-up relative to the SConscript +directory when they are used in a command. To force +&scons; +to look-up a directory relative to the root of the source tree use #: + +<example> +env = Environment(CPPPATH='#/include') +</example> + +The directory look-up can also be forced using the +&Dir;() +function: + +<example> +include = Dir('include') +env = Environment(CPPPATH=include) +</example> + +The directory list will be added to command lines +through the automatically-generated +&cv-_CPPINCFLAGS; +construction variable, +which is constructed by +appending the values of the +&cv-INCPREFIX; and &cv-INCSUFFIX; +construction variables +to the beginning and end +of each directory in &cv-CPPPATH;. +Any command lines you define that need +the CPPPATH directory list should +include &cv-_CPPINCFLAGS;: + +<example> +env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE") +</example> +</summary> +</cvar> + +<cvar name="DSUFFIXES"> +<summary> +The list of suffixes of files that will be scanned +for imported D package files. +The default list is: + +<example> +['.d'] +</example> +</summary> +</cvar> + +<cvar name="IDLSUFFIXES"> +<summary> +The list of suffixes of files that will be scanned +for IDL implicit dependencies +(#include or import lines). +The default list is: + +<example> +[".idl", ".IDL"] +</example> +</summary> +</cvar> + +<cvar name="INCPREFIX"> +<summary> +The prefix used to specify an include directory on the C compiler command +line. +This will be appended to the beginning of each directory +in the &cv-CPPPATH; and &cv-FORTRANPATH; construction variables +when the &cv-_CPPINCFLAGS; and &cv-_FORTRANINCFLAGS; +variables are automatically generated. +</summary> +</cvar> + +<cvar name="INCSUFFIX"> +<summary> +The suffix used to specify an include directory on the C compiler command +line. +This will be appended to the end of each directory +in the &cv-CPPPATH; and &cv-FORTRANPATH; construction variables +when the &cv-_CPPINCFLAGS; and &cv-_FORTRANINCFLAGS; +variables are automatically generated. +</summary> +</cvar> + +<cvar name="INSTALL"> +<summary> +A function to be called to install a file into a +destination file name. +The default function copies the file into the destination +(and sets the destination file's mode and permission bits +to match the source file's). +The function takes the following arguments: + +<example> +def install(dest, source, env): +</example> + +<varname>dest</varname> +is the path name of the destination file. +<varname>source</varname> +is the path name of the source file. +<varname>env</varname> +is the construction environment +(a dictionary of construction values) +in force for this file installation. +</summary> +</cvar> + +<cvar name="_LIBDIRFLAGS"> +<summary> +An automatically-generated construction variable +containing the linker command-line options +for specifying directories to be searched for library. +The value of &cv-_LIBDIRFLAGS; is created +by appending &cv-LIBDIRPREFIX; and &cv-LIBDIRSUFFIX; +to the beginning and end +of each directory in &cv-LIBPATH;. +</summary> +</cvar> + +<cvar name="LIBDIRPREFIX"> +<summary> +The prefix used to specify a library directory on the linker command line. +This will be appended to the beginning of each directory +in the &cv-LIBPATH; construction variable +when the &cv-_LIBDIRFLAGS; variable is automatically generated. +</summary> +</cvar> + +<cvar name="LIBDIRSUFFIX"> +<summary> +The suffix used to specify a library directory on the linker command line. +This will be appended to the end of each directory +in the &cv-LIBPATH; construction variable +when the &cv-_LIBDIRFLAGS; variable is automatically generated. +</summary> +</cvar> + +<cvar name="_LIBFLAGS"> +<summary> +An automatically-generated construction variable +containing the linker command-line options +for specifying libraries to be linked with the resulting target. +The value of &cv-_LIBFLAGS; is created +by appending &cv-LIBLINKPREFIX; and &cv-LIBLINKSUFFIX; +to the beginning and end +of each filename in &cv-LIBS;. +</summary> +</cvar> + +<cvar name="LIBLINKPREFIX"> +<summary> +The prefix used to specify a library to link on the linker command line. +This will be appended to the beginning of each library +in the &cv-LIBS; construction variable +when the &cv-_LIBFLAGS; variable is automatically generated. +</summary> +</cvar> + +<cvar name="LIBLINKSUFFIX"> +<summary> +The suffix used to specify a library to link on the linker command line. +This will be appended to the end of each library +in the &cv-LIBS; construction variable +when the &cv-_LIBFLAGS; variable is automatically generated. +</summary> +</cvar> + +<cvar name="LIBPATH"> +<summary> +The list of directories that will be searched for libraries. +The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in &cv-LINKFLAGS; or &cv-SHLINKFLAGS; +because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in LIBPATH will be looked-up relative to the SConscript +directory when they are used in a command. To force +&scons; +to look-up a directory relative to the root of the source tree use #: + +<example> +env = Environment(LIBPATH='#/libs') +</example> + +The directory look-up can also be forced using the +&Dir;() +function: + +<example> +libs = Dir('libs') +env = Environment(LIBPATH=libs) +</example> + +The directory list will be added to command lines +through the automatically-generated +&cv-_LIBDIRFLAGS; +construction variable, +which is constructed by +appending the values of the +&cv-LIBDIRPREFIX; and &cv-LIBDIRSUFFIX; +construction variables +to the beginning and end +of each directory in &cv-LIBPATH;. +Any command lines you define that need +the LIBPATH directory list should +include &cv-_LIBDIRFLAGS;: + +<example> +env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") +</example> +</summary> +</cvar> + +<cvar name="LIBS"> +<summary> +A list of one or more libraries +that will be linked with +any executable programs +created by this environment. + +The library list will be added to command lines +through the automatically-generated +&cv-_LIBFLAGS; +construction variable, +which is constructed by +appending the values of the +&cv-LIBLINKPREFIX; and &cv-LIBLINKSUFFIX; +construction variables +to the beginning and end +of each filename in &cv-LIBS;. +Any command lines you define that need +the LIBS library list should +include &cv-_LIBFLAGS;: + +<example> +env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE") +</example> + +If you add a +File +object to the +&cv-LIBS; +list, the name of that file will be added to +&cv-_LIBFLAGS;, +and thus the link line, as is, without +&cv-LIBLINKPREFIX; +or +&cv-LIBLINKSUFFIX;. +For example: + +<example> +env.Append(LIBS=File('/tmp/mylib.so')) +</example> + +In all cases, scons will add dependencies from the executable program to +all the libraries in this list. +</summary> +</cvar> + +<cvar name="PDFPREFIX"> +<summary> +The prefix used for PDF file names. +</summary> +</cvar> + +<cvar name="PDFSUFFIX"> +<summary> +The suffix used for PDF file names. +</summary> +</cvar> diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml new file mode 100644 index 0000000..d41cdaf --- /dev/null +++ b/src/engine/SCons/Environment.xml @@ -0,0 +1,157 @@ +<!-- __COPYRIGHT__ --> +<cvar name="BUILDERS"> +<summary> +A dictionary mapping the names of the builders +available through this environment +to underlying Builder objects. +Builders named +Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program +are available by default. +If you initialize this variable when an +Environment is created: + +<example> +env = Environment(BUILDERS = {'NewBuilder' : foo}) +</example> + +the default Builders will no longer be available. +To use a new Builder object in addition to the default Builders, +add your new Builder object like this: + +<example> +env = Environment() +env.Append(BUILDERS = {'NewBuilder' : foo}) +</example> + +or this: + +<example> +env = Environment() +env['BUILDERS]['NewBuilder'] = foo +</example> +</summary> +</cvar> + +<cvar name="Dir"> +<summary> +A function that converts a file name into a Dir instance relative to the +target being built. +</summary> +</cvar> + +<cvar name="ENV"> +<summary> +A dictionary of environment variables +to use when invoking commands. When +&cv-ENV; is used in a command all list +values will be joined using the path separator and any other non-string +values will simply be coerced to a string. +Note that, by default, +&scons; +does +<emphasis>not</emphasis> +propagate the environment in force when you +execute +&scons; +to the commands used to build target files. +This is so that builds will be guaranteed +repeatable regardless of the environment +variables set at the time +&scons; +is invoked. + +If you want to propagate your +environment variables +to the commands executed +to build target files, +you must do so explicitly: + +<example> +import os +env = Environment(ENV = os.environ) +</example> + +Note that you can choose only to propagate +certain environment variables. +A common example is +the system +<envar>PATH</envar> +environment variable, +so that +&scons; +uses the same utilities +as the invoking shell (or other process): + +<example> +import os +env = Environment(ENV = {'PATH' : os.environ['PATH']}) +</example> +</summary> +</cvar> + +<cvar name="File"> +<summary> +A function that converts a file name into a File instance relative to the +target being built. +</summary> +</cvar> + +<cvar name="RDirs"> +<summary> +A function that converts a file name into a list of Dir instances by +searching the repositories. +</summary> +</cvar> + +<cvar name="SCANNERS"> +<summary> +A list of the available implicit dependency scanners. +New file scanners may be added by +appending to this list, +although the more flexible approach +is to associate scanners +with a specific Builder. +See the sections "Builder Objects" +and "Scanner Objects," +below, for more information. +</summary> +</cvar> + +<cvar name="SOURCE"> +<summary> +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) +</summary> +</cvar> + +<cvar name="SOURCES"> +<summary> +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) +</summary> +</cvar> + +<cvar name="TARGET"> +<summary> +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) +</summary> +</cvar> + +<cvar name="TARGETS"> +<summary> +A reserved variable name +that may not be set or used in a construction environment. +(See "Variable Substitution," below.) +</summary> +</cvar> + +<cvar name="TOOLS"> +<summary> +A list of the names of the Tool specifications +that are part of this construction environment. +</summary> +</cvar> diff --git a/src/engine/SCons/Platform/__init__.xml b/src/engine/SCons/Platform/__init__.xml new file mode 100644 index 0000000..20ec83b --- /dev/null +++ b/src/engine/SCons/Platform/__init__.xml @@ -0,0 +1,118 @@ +<!-- __COPYRIGHT__ --> +<cvar name="ESCAPE"> +<summary> +A function that will be called to escape shell special characters in +command lines. The function should take one argument: the command line +string to escape; and should return the escaped command line. +</summary> +</cvar> + +<cvar name="LIBPREFIX"> +<summary> +The prefix used for (static) library file names. +A default value is set for each platform +(posix, win32, os2, etc.), +but the value is overridden by individual tools +(ar, mslib, sgiar, sunar, tlib, etc.) +to reflect the names of the libraries they create. +</summary> +</cvar> + +<cvar name="LIBPREFIXES"> +<summary> +An array of legal prefixes for library file names. +</summary> +</cvar> + +<cvar name="LIBSUFFIX"> +<summary> +The suffix used for (static) library file names. +A default value is set for each platform +(posix, win32, os2, etc.), +but the value is overridden by individual tools +(ar, mslib, sgiar, sunar, tlib, etc.) +to reflect the names of the libraries they create. +</summary> +</cvar> + +<cvar name="LIBSUFFIXES"> +<summary> +An array of legal suffixes for library file names. +</summary> +</cvar> + +<cvar name="OBJPREFIX"> +<summary> +The prefix used for (static) object file names. +</summary> +</cvar> + +<cvar name="OBJSUFFIX"> +<summary> +The suffix used for (static) object file names. +</summary> +</cvar> + +<cvar name="PLATFORM"> +<summary> +The name of the platform used to create the Environment. If no platform is +specified when the Environment is created, +&scons; +autodetects the platform. + +<example> +env = Environment(tools = []) +if env['PLATFORM'] == 'cygwin': + Tool('mingw')(env) +else: + Tool('msvc')(env) +</example> +</summary> +</cvar> + +<cvar name="PROGPREFIX"> +<summary> +The prefix used for executable file names. +</summary> +</cvar> + +<cvar name="PROGSUFFIX"> +<summary> +The suffix used for executable file names. +</summary> +</cvar> + +<cvar name="SHELL"> +<summary> +A string naming the shell program that will be passed to the +&cv-SPAWN; +function. +See the +&cv-SPAWN; +construction variable for more information. +</summary> +</cvar> + +<cvar name="SHLIBPREFIX"> +<summary> +The prefix used for shared library file names. +</summary> +</cvar> + +<cvar name="SHLIBSUFFIX"> +<summary> +The suffix used for shared library file names. +</summary> +</cvar> + +<cvar name="SHOBJPREFIX"> +<summary> +The prefix used for shared object file names. +</summary> +</cvar> + +<cvar name="SHOBJSUFFIX"> +<summary> +The suffix used for shared object file names. +</summary> +</cvar> diff --git a/src/engine/SCons/Platform/posix.xml b/src/engine/SCons/Platform/posix.xml new file mode 100644 index 0000000..1a53c72 --- /dev/null +++ b/src/engine/SCons/Platform/posix.xml @@ -0,0 +1,45 @@ +<!-- __COPYRIGHT__ --> +<cvar name="RPATH"> +<summary> +A list of paths to search for shared libraries when running programs. +Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink). +Ignored on platforms and toolchains that don't support it. +Note that the paths added to RPATH +are not transformed by +&scons; +in any way: if you want an absolute +path, you must make it absolute yourself. +</summary> +</cvar> + +<cvar name="_RPATH"> +<summary> +An automatically-generated construction variable +containing the rpath flags to be used when linking +a program with shared libraries. +The value of &cv-_RPATH; is created +by appending &cv-RPATHPREFIX; and &cv-RPATHSUFFIX; +to the beginning and end +of each directory in &cv-RPATH;. +</summary> +</cvar> + +<cvar name="RPATHPREFIX"> +<summary> +The prefix used to specify a directory to be searched for +shared libraries when running programs. +This will be appended to the beginning of each directory +in the &cv-RPATH; construction variable +when the &cv-_RPATH; variable is automatically generated. +</summary> +</cvar> + +<cvar name="RPATHSUFFIX"> +<summary> +The suffix used to specify a directory to be searched for +shared libraries when running programs. +This will be appended to the end of each directory +in the &cv-RPATH; construction variable +when the &cv-_RPATH; variable is automatically generated. +</summary> +</cvar> diff --git a/src/engine/SCons/Platform/win32.xml b/src/engine/SCons/Platform/win32.xml new file mode 100644 index 0000000..c893f0c --- /dev/null +++ b/src/engine/SCons/Platform/win32.xml @@ -0,0 +1,9 @@ +<!-- __COPYRIGHT__ --> +<cvar name="MAXLINELENGTH"> +<summary> +The maximum number of characters allowed on an external command line. +On Win32 systems, +link lines longer than this many characters +are linked via a temporary file name. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/386asm.xml b/src/engine/SCons/Tool/386asm.xml new file mode 100644 index 0000000..2a9d993 --- /dev/null +++ b/src/engine/SCons/Tool/386asm.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="386asm"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/BitKeeper.xml b/src/engine/SCons/Tool/BitKeeper.xml new file mode 100644 index 0000000..43841a0 --- /dev/null +++ b/src/engine/SCons/Tool/BitKeeper.xml @@ -0,0 +1,43 @@ +<!-- __COPYRIGHT__ --> +<tool name="BitKeeper"> +<summary> +XXX +</summary> +</tool> + +<cvar name="BITKEEPER"> +<summary> +The BitKeeper executable. +</summary> +</cvar> + +<cvar name="BITKEEPERCOM"> +<summary> +The command line for +fetching source files using BitKEeper. +</summary> +</cvar> + +<cvar name="BITKEEPERCOMSTR"> +<summary> +The string displayed when fetching +a source file using BitKeeper. +If this is not set, then &cv-BITKEEPERCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="BITKEEPERGET"> +<summary> +The command (&cv-BITKEEPER;) and subcommand +for fetching source files using BitKeeper. +</summary> +</cvar> + +<cvar name="BITKEEPERGETFLAGS"> +<summary> +Options that are passed to the BitKeeper +<command>get</command> +subcommand. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/CVS.xml b/src/engine/SCons/Tool/CVS.xml new file mode 100644 index 0000000..9a07294 --- /dev/null +++ b/src/engine/SCons/Tool/CVS.xml @@ -0,0 +1,51 @@ +<!-- __COPYRIGHT__ --> +<tool name="CVS"> +<summary> +XXX +</summary> +</tool> + +<cvar name="CVS"> +<summary> +The CVS executable. +</summary> +</cvar> + +<cvar name="CVSCOFLAGS"> +<summary> +Options that are passed to the CVS checkout subcommand. +</summary> +</cvar> + +<cvar name="CVSCOM"> +<summary> +The command line used to +fetch source files from a CVS repository. +</summary> +</cvar> + +<cvar name="CVSCOMSTR"> +<summary> +The string displayed when fetching +a source file from a CVS repository. +If this is not set, then &cv-CVSCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="CVSFLAGS"> +<summary> +General options that are passed to CVS. +By default, this is set to +<literal>-d $CVSREPOSITORY</literal> +to specify from where the files must be fetched. +</summary> +</cvar> + +<cvar name="CVSREPOSITORY"> +<summary> +The path to the CVS repository. +This is referenced in the default +&cv-CVSFLAGS; value. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/Perforce.xml b/src/engine/SCons/Tool/Perforce.xml new file mode 100644 index 0000000..247330e --- /dev/null +++ b/src/engine/SCons/Tool/Perforce.xml @@ -0,0 +1,33 @@ +<!-- __COPYRIGHT__ --> +<tool name="Perforce"> +<summary> +XXX +</summary> +</tool> + +<cvar name="P4"> +<summary> +The Perforce executable. +</summary> +</cvar> + +<cvar name="P4COM"> +<summary> +The command line used to +fetch source files from Perforce. +</summary> +</cvar> + +<cvar name="P4COMSTR"> +<summary> +The string displayed when +fetching a source file from Perforce. +If this is not set, then &cv-P4COM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="P4FLAGS"> +<summary> +General options that are passed to Perforce. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/RCS.xml b/src/engine/SCons/Tool/RCS.xml new file mode 100644 index 0000000..40d972f --- /dev/null +++ b/src/engine/SCons/Tool/RCS.xml @@ -0,0 +1,46 @@ +<!-- __COPYRIGHT__ --> +<tool name="RCS"> +<summary> +XXX +</summary> +</tool> + +<cvar name="RCS"> +<summary> +The RCS executable. +Note that this variable is not actually used +for the command to fetch source files from RCS; +see the +&cv-RCS_CO; +construction variable, below. +</summary> +</cvar> + +<cvar name="RCS_CO"> +<summary> +The RCS "checkout" executable, +used to fetch source files from RCS. +</summary> +</cvar> + +<cvar name="RCS_COCOM"> +<summary> +The command line used to +fetch (checkout) source files from RCS. +</summary> +</cvar> + +<cvar name="RCS_COCOMSTR"> +<summary> +The string displayed when fetching +a source file from RCS. +If this is not set, then &cv-RCS_COCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="RCS_COFLAGS"> +<summary> +Options that are passed to the &cv-RCS_CO; command. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/SCCS.xml b/src/engine/SCons/Tool/SCCS.xml new file mode 100644 index 0000000..08aa949 --- /dev/null +++ b/src/engine/SCons/Tool/SCCS.xml @@ -0,0 +1,43 @@ +<!-- __COPYRIGHT__ --> +<tool name="SCCS"> +<summary> +XXX +</summary> +</tool> + +<cvar name="SCCS"> +<summary> +The SCCS executable. +</summary> +</cvar> + +<cvar name="SCCSCOM"> +<summary> +The command line used to +fetch source files from SCCS. +</summary> +</cvar> + +<cvar name="SCCSCOMSTR"> +<summary> +The string displayed when fetching +a source file from a CVS repository. +If this is not set, then &cv-SCCSCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="SCCSFLAGS"> +<summary> +General options that are passed to SCCS. +</summary> +</cvar> + +<cvar name="SCCSGETFLAGS"> +<summary> +Options that are passed specifically to the SCCS "get" subcommand. +This can be set, for example, to +<option>-e</option> +to check out editable files from SCCS. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/Subversion.xml b/src/engine/SCons/Tool/Subversion.xml new file mode 100644 index 0000000..e5560d1 --- /dev/null +++ b/src/engine/SCons/Tool/Subversion.xml @@ -0,0 +1,32 @@ +<!-- __COPYRIGHT__ --> +<tool name="Subversion"> +<summary> +XXX +</summary> +</tool> + +<!-- +<cvar name="SVN"> +<summary> +The Subversion executable (usually named +<command>svn</command>). +</summary> +</cvar> +--> + +<!-- +<cvar name="SVNCOM"> +<summary> +The command line used to +fetch source files from a Subversion repository. +</summary> +</cvar> +--> + +<!-- +<cvar name="SVNFLAGS"> +<summary> +General options that are passed to Subversion. +</summary> +</cvar> +--> diff --git a/src/engine/SCons/Tool/__init__.py b/src/engine/SCons/Tool/__init__.py index 7ef2ea0..7010e1c 100644 --- a/src/engine/SCons/Tool/__init__.py +++ b/src/engine/SCons/Tool/__init__.py @@ -161,8 +161,8 @@ def createStaticLibBuilder(env): try: static_lib = env['BUILDERS']['StaticLibrary'] except KeyError: - import SCons.Defaults - static_lib = SCons.Builder.Builder(action = SCons.Defaults.ArAction, + ar_action = SCons.Action.Action("$ARCOM", "$ARCOMSTR") + static_lib = SCons.Builder.Builder(action = ar_action, emitter = '$LIBEMITTER', prefix = '$LIBPREFIX', suffix = '$LIBSUFFIX', diff --git a/src/engine/SCons/Tool/__init__.xml b/src/engine/SCons/Tool/__init__.xml new file mode 100644 index 0000000..86b830c --- /dev/null +++ b/src/engine/SCons/Tool/__init__.xml @@ -0,0 +1,324 @@ +<!-- __COPYRIGHT__ --> +<builder name="CFile"> +<summary> +Builds a C source file given a lex (<filename>.l</filename>) +or yacc (<filename>.y</filename>) input file. +The suffix specified by the &cv-CFILESUFFIX; construction variable +(<filename>.c</filename> by default) +is automatically added to the target +if it is not already present. Example: + +<example> +# builds foo.c +env.CFile(target = 'foo.c', source = 'foo.l') +# builds bar.c +env.CFile(target = 'bar', source = 'bar.y') +</example> +</summary> +</builder> + +<builder name="CXXFile"> +<summary> +Builds a C++ source file given a lex (<filename>.ll</filename>) +or yacc (<filename>.yy</filename>) +input file. +The suffix specified by the &cv-CXXFILESUFFIX; construction variable +(<filename>.cc</filename> by default) +is automatically added to the target +if it is not already present. Example: + +<example> +# builds foo.cc +env.CXXFile(target = 'foo.cc', source = 'foo.ll') +# builds bar.cc +env.CXXFile(target = 'bar', source = 'bar.yy') +</example> +</summary> +</builder> + +<builder name="Library"> +<summary> +A synonym for the +&b-StaticLibrary; +builder method. +</summary> +</builder> + +<builder name="Object"> +<summary> +A synonym for the +&b-StaticObject; +builder method. +</summary> +</builder> + +<builder name="Program"> +<summary> +Builds an executable given one or more object files +or C, C++, D, or Fortran source files. +If any C, C++, D or Fortran source files are specified, +then they will be automatically +compiled to object files using the +&b-Object; +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-PROGPREFIX; construction variable; nothing by default) +and suffix +(specified by the &cv-PROGSUFFIX; construction variable; +by default, <filename>.exe</filename> on Windows systems, +nothing on POSIX systems) +are automatically added to the target if not already present. +Example: + +<example> +env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) +</example> +</summary> +</builder> + +<builder name="SharedLibrary"> +<summary> +Builds a shared library +(<filename>.so</filename> on a POSIX system, +<filename>.dll</filename> on WIN32) +given one or more object files +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-SHLIBPREFIX; construction variable; +by default, <filename>lib</filename> on POSIX systems, +nothing on Windows systems) +and suffix +(specified by the &cv-SHLIBSUFFIX; construction variable; +by default, <filename>.dll</filename> on Windows systems, +<filename>.so</filename> on POSIX systems) +are automatically added to the target if not already present. +Example: + +<example> +env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +</example> + +On WIN32 systems, the +&b-SharedLibrary; +builder method will always build an import +(<filename>.lib</filename>) library +in addition to the shared (<filename>.dll</filename>) library, +adding a <filename>.lib</filename> library with the same basename +if there is not already a <filename>.lib</filename> file explicitly +listed in the targets. + +Any object files listed in the +<literal>source</literal> +must have been built for a shared library +(that is, using the +&b-SharedObject; +builder method). +&scons; +will raise an error if there is any mismatch. + +On WIN32 systems, specifying +<literal>register=1</literal> +will cause the <filename>.dll</filename> to be +registered after it is built using REGSVR32. +The command that is run +("regsvr32" by default) is determined by &cv-REGSVR; construction +variable, and the flags passed are determined by &cv-REGSVRFLAGS;. By +default, &cv-REGSVRFLAGS; includes the <option>/s</option> option, +to prevent dialogs from popping +up and requiring user attention when it is run. If you change +&cv-REGSVRFLAGS;, be sure to include the <option>/s</option> option. +For example, + +<example> +env.SharedLibrary(target = 'bar', + source = ['bar.cxx', 'foo.obj'], + register=1) +</example> + +will register <filename>bar.dll</filename> as a COM object +when it is done linking it. +</summary> +</builder> + +<builder name="SharedObject"> +<summary> +Builds an object file for +inclusion in a shared library. +Source files must have one of the same set of extensions +specified above for the +&b-StaticObject; +builder method. +On some platforms building a shared object requires additional +compiler option +(e.g. <option>-fPIC</option> 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 +will only allow shared objects to be linked into a shared library, and will +use a different suffix for shared objects. On platforms where there is no +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-SHOBJPREFIX; construction variable; +by default, the same as &cv-OBJPREFIX;) +and suffix +(specified by the &cv-SHOBJSUFFIX; construction variable) +are automatically added to the target if not already present. +Examples: + +<example> +env.SharedObject(target = 'ddd', source = 'ddd.c') +env.SharedObject(target = 'eee.o', source = 'eee.cpp') +env.SharedObject(target = 'fff.obj', source = 'fff.for') +</example> +</summary> +</builder> + +<builder name="StaticLibrary"> +<summary> +Builds a static library given one or more object files +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-LIBPREFIX; construction variable; +by default, <filename>lib</filename> on POSIX systems, +nothing on Windows systems) +and suffix +(specified by the &cv-LIBSUFFIX; construction variable; +by default, <filename>.lib</filename> on Windows systems, +<filename>.a</filename> on POSIX systems) +are automatically added to the target if not already present. +Example: + +<example> +env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) +</example> + +Any object files listed in the +<literal>source</literal> +must have been built for a static library +(that is, using the +&b-StaticObject; +builder method). +&scons; +will raise an error if there is any mismatch. +</summary> +</builder> + +<builder name="StaticObject"> +<summary> +Builds a static object file +from one or more C, C++, D, or Fortran source files. +Source files must have one of the following extensions: + +<example> + .asm assembly language file + .ASM assembly language file + .c C file + .C WIN32: C file + POSIX: C++ file + .cc C++ file + .cpp C++ file + .cxx C++ file + .cxx C++ file + .c++ C++ file + .C++ C++ file + .d D file + .f Fortran file + .F WIN32: Fortran file + POSIX: Fortran file + C pre-processor + .for Fortran file + .FOR Fortran file + .fpp Fortran file + C pre-processor + .FPP Fortran file + C pre-processor + .s assembly language file + .S WIN32: assembly language file + POSIX: assembly language file + C pre-processor + .spp assembly language file + C pre-processor + .SPP assembly language file + C pre-processor +</example> + +The target object file prefix +(specified by the &cv-OBJPREFIX; construction variable; nothing by default) +and suffix +(specified by the &cv-OBJSUFFIX; construction variable; +<filename>.obj</filename> on Windows systems, +<filename>.o</filename> on POSIX systems) +are automatically added to the target if not already present. +Examples: + +<example> +env.StaticObject(target = 'aaa', source = 'aaa.c') +env.StaticObject(target = 'bbb.o', source = 'bbb.c++') +env.StaticObject(target = 'ccc.obj', source = 'ccc.f') +</example> +</summary> +</builder> + +<cvar name="CCVERSION"> +<summary> +The version number of the C compiler. +This may or may not be set, +depending on the specific C compiler being used. +</summary> +</cvar> + +<cvar name="CFILESUFFIX"> +<summary> +The suffix for C source files. +This is used by the internal CFile builder +when generating C files from Lex (.l) or YACC (.y) input files. +The default suffix, of course, is +<filename>.c</filename> +(lower case). +On case-insensitive systems (like Win32), +SCons also treats +<filename>.C</filename> +(upper case) files +as C files. +</summary> +</cvar> + +<cvar name="CXXVERSION"> +<summary> +The version number of the C++ compiler. +This may or may not be set, +depending on the specific C++ compiler being used. +</summary> +</cvar> + +<cvar name="CXXFILESUFFIX"> +<summary> +The suffix for C++ source files. +This is used by the internal CXXFile builder +when generating C++ files from Lex (.ll) or YACC (.yy) input files. +The default suffix is +<filename>.cc</filename>. +SCons also treats files with the suffixes +<filename>.cpp</filename>, +<filename>.cxx</filename>, +<filename>.c++</filename>, +and +<filename>.C++</filename> +as C++ files. +On case-sensitive systems (Linux, UNIX, and other POSIX-alikes), +SCons also treats +<filename>.C</filename> +(upper case) files +as C++ files. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/aixc++.xml b/src/engine/SCons/Tool/aixc++.xml new file mode 100644 index 0000000..d386779 --- /dev/null +++ b/src/engine/SCons/Tool/aixc++.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="aixc++"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/aixcc.xml b/src/engine/SCons/Tool/aixcc.xml new file mode 100644 index 0000000..cb27adb --- /dev/null +++ b/src/engine/SCons/Tool/aixcc.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="aixcc"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/aixf77.xml b/src/engine/SCons/Tool/aixf77.xml new file mode 100644 index 0000000..7e7988c --- /dev/null +++ b/src/engine/SCons/Tool/aixf77.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="aixf77"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/aixlink.xml b/src/engine/SCons/Tool/aixlink.xml new file mode 100644 index 0000000..378dcbf --- /dev/null +++ b/src/engine/SCons/Tool/aixlink.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="aixlink"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/applelink.xml b/src/engine/SCons/Tool/applelink.xml new file mode 100644 index 0000000..d839be0 --- /dev/null +++ b/src/engine/SCons/Tool/applelink.xml @@ -0,0 +1,11 @@ +<!-- __COPYRIGHT__ --> +<cvar name="FRAMEWORKSFLAGS"> +<summary> +On Mac OS X, +frameworks options to be added at +the end of a command +line building a loadable module. +</summary> +</cvar> + + diff --git a/src/engine/SCons/Tool/ar.py b/src/engine/SCons/Tool/ar.py index ab232ee..92cab59 100644 --- a/src/engine/SCons/Tool/ar.py +++ b/src/engine/SCons/Tool/ar.py @@ -37,6 +37,7 @@ import SCons.Defaults import SCons.Tool import SCons.Util + def generate(env): """Add Builders and construction variables for ar to an Environment.""" SCons.Tool.createStaticLibBuilder(env) diff --git a/src/engine/SCons/Tool/ar.xml b/src/engine/SCons/Tool/ar.xml new file mode 100644 index 0000000..de3246f --- /dev/null +++ b/src/engine/SCons/Tool/ar.xml @@ -0,0 +1,48 @@ +<!-- __COPYRIGHT__ --> +<tool name="ar"> +<summary> +XXX +</summary> +</tool> + +<cvar name="AR"> +<summary> +The static library archiver. +</summary> +</cvar> + +<cvar name="ARCOM"> +<summary> +The command line used to generate a static library from object files. +</summary> +</cvar> + +<cvar name="ARCOMSTR"> +<summary> +The string displayed when an object file +is generated from an assembly-language source file. +If this is not set, then &cv-ARCOM; (the command line) is displayed. + +<example> +env = Environment(ARCOMSTR = "Archiving $TARGET") +</example> +</summary> +</cvar> + +<cvar name="ARFLAGS"> +<summary> +General options passed to the static library archiver. +</summary> +</cvar> + +<cvar name="RANLIB"> +<summary> +The archive indexer. +</summary> +</cvar> + +<cvar name="RANLIBFLAGS"> +<summary> +General options passed to the archive indexer. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/as.xml b/src/engine/SCons/Tool/as.xml new file mode 100644 index 0000000..a9395df --- /dev/null +++ b/src/engine/SCons/Tool/as.xml @@ -0,0 +1,69 @@ +<!-- __COPYRIGHT__ --> +<tool name="as"> +<summary> +XXX +</summary> +</tool> + +<cvar name="AS"> +<summary> +The assembler. +</summary> +</cvar> + +<cvar name="ASCOM"> +<summary> +The command line used to generate an object file +from an assembly-language source file. +</summary> +</cvar> + +<cvar name="ASCOMSTR"> +<summary> +The string displayed when an object file +is generated from an assembly-language source file. +If this is not set, then &cv-ASCOM; (the command line) is displayed. + +<example> +env = Environment(ASCOMSTR = "Assembling $TARGET") +</example> +</summary> +</cvar> + +<cvar name="ASFLAGS"> +<summary> +General options passed to the assembler. +</summary> +</cvar> + +<cvar name="ASPPCOM"> +<summary> +The command line used to assemble an assembly-language +source file into an object file +after first running the file through the C preprocessor. +Any options specified in the &cv-ASFLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +</summary> +</cvar> + +<cvar name="ASPPCOMSTR"> +<summary> +The string displayed when an object file +is generated from an assembly-language source file +after first running the file through the C preprocessor. +If this is not set, then &cv-ASPPCOM; (the command line) is displayed. + +<example> +env = Environment(ASPPCOMSTR = "Assembling $TARGET") +</example> +</summary> +</cvar> + +<cvar name="ASPPFLAGS"> +<summary> +General options when an assembling an assembly-language +source file into an object file +after first running the file through the C preprocessor. +The default is to use the value of &cv-ASFLAGS;. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/bcc32.xml b/src/engine/SCons/Tool/bcc32.xml new file mode 100644 index 0000000..ded614c --- /dev/null +++ b/src/engine/SCons/Tool/bcc32.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="bcc32"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/c++.xml b/src/engine/SCons/Tool/c++.xml new file mode 100644 index 0000000..eaa8e6c --- /dev/null +++ b/src/engine/SCons/Tool/c++.xml @@ -0,0 +1,76 @@ +<!-- __COPYRIGHT__ --> +<tool name="c++"> +<summary> +XXX +</summary> +</tool> + +<cvar name="CXX"> +<summary> +The C++ compiler. +</summary> +</cvar> + +<cvar name="CXXCOM"> +<summary> +The command line used to compile a C++ source file to an object file. +Any options specified in the &cv-CXXFLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +</summary> +</cvar> + +<cvar name="CXXCOMSTR"> +<summary> +The string displayed when a C++ source file +is compiled to a (static) object file. +If this is not set, then &cv-CXXCOM; (the command line) is displayed. + +<example> +env = Environment(CXXCOMSTR = "Compiling static object $TARGET") +</example> +</summary> +</cvar> + +<cvar name="CXXFLAGS"> +<summary> +General options that are passed to the C++ compiler. +By default, this includes the value of &cv-CCFLAGS;, +so that setting &cv-CCFLAGS; affects both C and C++ compilation. +If you want to add C++-specific flags, +you must set or override the value of &cv-CXXFLAGS;. +</summary> +</cvar> + +<cvar name="SHCXX"> +<summary> +The C++ compiler used for generating shared-library objects. +</summary> +</cvar> + +<cvar name="SHCXXCOM"> +<summary> +The command line used to compile a C++ source file +to a shared-library object file. +Any options specified in the &cv-SHCXXFLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +</summary> +</cvar> + +<cvar name="SHCXXCOMSTR"> +<summary> +The string displayed when a C++ source file +is compiled to a shared object file. +If this is not set, then &cv-SHCXXCOM; (the command line) is displayed. + +<example> +env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET") +</example> +</summary> +</cvar> + +<cvar name="SHCXXFLAGS"> +<summary> +Options that are passed to the C++ compiler +to generate shared-library objects. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/cc.xml b/src/engine/SCons/Tool/cc.xml new file mode 100644 index 0000000..fb688ad --- /dev/null +++ b/src/engine/SCons/Tool/cc.xml @@ -0,0 +1,111 @@ +<!-- __COPYRIGHT__ --> +<tool name="cc"> +<summary> +XXX +</summary> +</tool> + +<cvar name="CC"> +<summary> +The C compiler. +</summary> +</cvar> + +<cvar name="CCCOM"> +<summary> +The command line used to compile a C source file to a (static) object file. +Any options specified in the &cv-CCFLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +</summary> +</cvar> + +<cvar name="CCCOMSTR"> +<summary> +The string displayed when a C source file +is compiled to a (static) object file. +If this is not set, then &cv-CCCOM; (the command line) is displayed. + +<example> +env = Environment(CCCOMSTR = "Compiling static object $TARGET") +</example> +</summary> +</cvar> + +<cvar name="CCFLAGS"> +<summary> +General options that are passed to the C compiler. +</summary> +</cvar> + +<cvar name="CPPFLAGS"> +<summary> +User-specified C preprocessor options. +These will be included in any command that uses the C preprocessor, +including not just compilation of C and C++ source files +via the &cv-CCCOM;, &cv-SHCCCOM;, &cv-CXXCOM; and &cv-SHCXXCOM; command lines, +but also the &cv-FORTRANPPCOM;, &cv-SHFORTRANPPCOM;, +&cv-F77PPCOM; and &cv-SHF77PPCOM; command lines +used to compile a Fortran source file, +and the &cv-ASPPCOM; command line +used to assemble an assembly language source file, +after first running each file through the C preprocessor. +Note that this variable does +<emphasis>not</emphasis> +contain +<option>-I</option> +(or similar) include search path options +that scons generates automatically from &cv-CPPPATH;. +See &cv-link-_CPPINCFLAGS;, below, +for the variable that expands to those options. +</summary> +</cvar> + +<cvar name="CPPSUFFIXES"> +<summary> +The list of suffixes of files that will be scanned +for C preprocessor implicit dependencies +(#include lines). +The default list is: + +<example> +[".c", ".C", ".cxx", ".cpp", ".c++", ".cc", + ".h", ".H", ".hxx", ".hpp", ".hh", + ".F", ".fpp", ".FPP", + ".S", ".spp", ".SPP"] +</example> +</summary> +</cvar> + +<cvar name="SHCC"> +<summary> +The C compiler used for generating shared-library objects. +</summary> +</cvar> + +<cvar name="SHCCCOM"> +<summary> +The command line used to compile a C source file +to a shared-library object file. +Any options specified in the &cv-SHCCFLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +</summary> +</cvar> + +<cvar name="SHCCCOMSTR"> +<summary> +The string displayed when a C source file +is compiled to a shared object file. +If this is not set, then &cv-SHCCCOM; (the command line) is displayed. + +<example> +env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET") +</example> +</summary> +</cvar> + +<cvar name="SHCCFLAGS"> +<summary> +Options that are passed to the C compiler +to generate shared-library objects. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/cvf.xml b/src/engine/SCons/Tool/cvf.xml new file mode 100644 index 0000000..bd848ae --- /dev/null +++ b/src/engine/SCons/Tool/cvf.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="cvf"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/default.xml b/src/engine/SCons/Tool/default.xml new file mode 100644 index 0000000..371e5bc --- /dev/null +++ b/src/engine/SCons/Tool/default.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="default"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/dmd.xml b/src/engine/SCons/Tool/dmd.xml new file mode 100644 index 0000000..99ca8d9 --- /dev/null +++ b/src/engine/SCons/Tool/dmd.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="dmd"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/dvipdf.xml b/src/engine/SCons/Tool/dvipdf.xml new file mode 100644 index 0000000..fbb4933 --- /dev/null +++ b/src/engine/SCons/Tool/dvipdf.xml @@ -0,0 +1,38 @@ +<!-- __COPYRIGHT__ --> +<tool name="dvipdf"> +<summary> +XXX +</summary> +</tool> + +<cvar name="DVIPDF"> +<summary> +The TeX DVI file to PDF file converter. +</summary> +</cvar> + +<cvar name="DVIPDFFLAGS"> +<summary> +General options passed to the TeX DVI file to PDF file converter. +</summary> +</cvar> + +<cvar name="DVIPDFCOM"> +<summary> +The command line used to convert TeX DVI files into a PDF file. +</summary> +</cvar> + +<cvar name="DVIPDFCOMSTR"> +<summary> +The string displayed when a TeX DVI file +is converted into a PDF file. +If this is not set, then &cv-DVIPDFCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="PDFCOM"> +<summary> +A deprecated synonym for &cv-DVIPDFCOM;. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/dvips.xml b/src/engine/SCons/Tool/dvips.xml new file mode 100644 index 0000000..c290469 --- /dev/null +++ b/src/engine/SCons/Tool/dvips.xml @@ -0,0 +1,66 @@ +<!-- __COPYRIGHT__ --> +<tool name="dvips"> +<summary> +XXX +</summary> +</tool> + +<builder name="PostScript"> +<summary> +Builds a <filename>.ps</filename> file +from a <filename>.dvi</filename> input file +(or, by extension, a <filename>.tex</filename>, +<filename>.ltx</filename>, +or +<filename>.latex</filename> input file). +The suffix specified by the &cv-PSSUFFIX; construction variable +(<filename>.ps</filename> by default) +is added automatically to the target +if it is not already present. Example: + +<example> +# builds from aaa.tex +env.PostScript(target = 'aaa.ps', source = 'aaa.tex') +# builds bbb.ps from bbb.dvi +env.PostScript(target = 'bbb', source = 'bbb.dvi') +</example> +</summary> +</builder> + +<cvar name="DVIPS"> +<summary> +The TeX DVI file to PostScript converter. +</summary> +</cvar> + +<cvar name="DVIPSFLAGS"> +<summary> +General options passed to the TeX DVI file to PostScript converter. +</summary> +</cvar> + +<cvar name="PSCOM"> +<summary> +The command line used to convert TeX DVI files into a PostScript file. +</summary> +</cvar> + +<cvar name="PSCOMSTR"> +<summary> +The string displayed when a TeX DVI file +is converted into a PostScript file. +If this is not set, then &cv-PSCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="PSPREFIX"> +<summary> +The prefix used for PostScript file names. +</summary> +</cvar> + +<cvar name="PSSUFFIX"> +<summary> +The prefix used for PostScript file names. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/f77.xml b/src/engine/SCons/Tool/f77.xml new file mode 100644 index 0000000..caf959f --- /dev/null +++ b/src/engine/SCons/Tool/f77.xml @@ -0,0 +1,196 @@ +<!-- __COPYRIGHT__ --> +<tool name="f77"> +<summary> +XXX +</summary> +</tool> + +<cvar name="F77"> +<summary> +The Fortran 77 compiler. +You should normally set the &cv-FORTRAN; variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set &cv-F77; if you need to use a specific compiler +or compiler version for Fortran 77 files. +</summary> +</cvar> + +<cvar name="F77COM"> +<summary> +The command line used to compile a Fortran 77 source file to an object file. +You only need to set &cv-F77COM; if you need to use a specific +command line for Fortran 77 files. +You should normally set the &cv-FORTRANCOM; variable, +which specifies the default command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="F77COMSTR"> +<summary> +The string displayed when a Fortran 77 source file +is compiled to an object file. +If this is not set, then &cv-F77COM; or &cv-FORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="F77FLAGS"> +<summary> +General user-specified options that are passed to the Fortran 77 compiler. +Note that this variable does +<emphasis>not</emphasis> +contain +<option>-I</option> +(or similar) include search path options +that scons generates automatically from &cv-F77PATH;. +See +&cv-_F77INCFLAGS; +below, +for the variable that expands to those options. +You only need to set &cv-F77FLAGS; if you need to define specific +user options for Fortran 77 files. +You should normally set the &cv-FORTRANFLAGS; variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. +</summary> +</cvar> + +<cvar name="_F77INCFLAGS"> +<summary> +An automatically-generated construction variable +containing the Fortran 77 compiler command-line options +for specifying directories to be searched for include files. +The value of &cv-_F77INCFLAGS; is created +by appending &cv-INCPREFIX; and &cv-INCSUFFIX; +to the beginning and end +of each directory in &cv-F77PATH;. +</summary> +</cvar> + +<cvar name="F77PATH"> +<summary> +The list of directories that the Fortran 77 compiler will search for include +directories. The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in &cv-F77FLAGS; because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in &cv-F77PATH; will be looked-up relative to the SConscript +directory when they are used in a command. To force +&scons; +to look-up a directory relative to the root of the source tree use #: +You only need to set &cv-F77PATH; if you need to define a specific +include path for Fortran 77 files. +You should normally set the &cv-FORTRANPATH; variable, +which specifies the include path +for the default Fortran compiler +for all Fortran versions. + +<example> +env = Environment(F77PATH='#/include') +</example> + +The directory look-up can also be forced using the +&Dir;() +function: + +<example> +include = Dir('include') +env = Environment(F77PATH=include) +</example> + +The directory list will be added to command lines +through the automatically-generated +&cv-_F77INCFLAGS; +construction variable, +which is constructed by +appending the values of the +&cv-INCPREFIX; and &cv-INCSUFFIX; +construction variables +to the beginning and end +of each directory in &cv-F77PATH;. +Any command lines you define that need +the F77PATH directory list should +include &cv-_F77INCFLAGS;: + +<example> +env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE") +</example> +</summary> +</cvar> + +<cvar name="F77PPCOM"> +<summary> +The command line used to compile a Fortran 77 source file to an object file +after first running the file through the C preprocessor. +Any options specified in the &cv-F77FLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +You only need to set &cv-F77PPCOM; if you need to use a specific +C-preprocessor command line for Fortran 77 files. +You should normally set the &cv-FORTRANPPCOM; variable, +which specifies the default C-preprocessor command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF77"> +<summary> +The Fortran 77 compiler used for generating shared-library objects. +You should normally set the &cv-SHFORTRAN; variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set &cv-SHF77; if you need to use a specific compiler +or compiler version for Fortran 77 files. +</summary> +</cvar> + +<cvar name="SHF77COM"> +<summary> +The command line used to compile a Fortran 77 source file +to a shared-library object file. +You only need to set &cv-SHF77COM; if you need to use a specific +command line for Fortran 77 files. +You should normally set the &cv-SHFORTRANCOM; variable, +which specifies the default command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF77COMSTR"> +<summary> +The string displayed when a Fortran 77 source file +is compiled to a shared-library object file. +If this is not set, then &cv-SHF77COM; or &cv-SHFORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="SHF77FLAGS"> +<summary> +Options that are passed to the Fortran 77 compiler +to generated shared-library objects. +You only need to set &cv-SHF77FLAGS; if you need to define specific +user options for Fortran 77 files. +You should normally set the &cv-SHFORTRANFLAGS; variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF77PPCOM"> +<summary> +The command line used to compile a Fortran 77 source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified in the &cv-SHF77FLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +You only need to set &cv-SHF77PPCOM; if you need to use a specific +C-preprocessor command line for Fortran 77 files. +You should normally set the &cv-SHFORTRANPPCOM; variable, +which specifies the default C-preprocessor command line +for all Fortran versions. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/f90.xml b/src/engine/SCons/Tool/f90.xml new file mode 100644 index 0000000..b2f0857 --- /dev/null +++ b/src/engine/SCons/Tool/f90.xml @@ -0,0 +1,196 @@ +<!-- __COPYRIGHT__ --> +<tool name="f90"> +<summary> +XXX +</summary> +</tool> + +<cvar name="F90"> +<summary> +The Fortran 90 compiler. +You should normally set the &cv-FORTRAN; variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set &cv-F90; if you need to use a specific compiler +or compiler version for Fortran 90 files. +</summary> +</cvar> + +<cvar name="F90COM"> +<summary> +The command line used to compile a Fortran 90 source file to an object file. +You only need to set &cv-F90COM; if you need to use a specific +command line for Fortran 90 files. +You should normally set the &cv-FORTRANCOM; variable, +which specifies the default command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="F90COMSTR"> +<summary> +The string displayed when a Fortran 90 source file +is compiled to an object file. +If this is not set, then &cv-F90COM; or &cv-FORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="F90FLAGS"> +<summary> +General user-specified options that are passed to the Fortran 90 compiler. +Note that this variable does +<emphasis>not</emphasis> +contain +<option>-I</option> +(or similar) include search path options +that scons generates automatically from &cv-F90PATH;. +See +&cv-_F90INCFLAGS; +below, +for the variable that expands to those options. +You only need to set &cv-F90FLAGS; if you need to define specific +user options for Fortran 90 files. +You should normally set the &cv-FORTRANFLAGS; variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. +</summary> +</cvar> + +<cvar name="_F90INCFLAGS"> +<summary> +An automatically-generated construction variable +containing the Fortran 90 compiler command-line options +for specifying directories to be searched for include files. +The value of &cv-_F90INCFLAGS; is created +by appending &cv-INCPREFIX; and &cv-INCSUFFIX; +to the beginning and end +of each directory in &cv-F90PATH;. +</summary> +</cvar> + +<cvar name="F90PATH"> +<summary> +The list of directories that the Fortran 90 compiler will search for include +directories. The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in &cv-F90FLAGS; because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in &cv-F90PATH; will be looked-up relative to the SConscript +directory when they are used in a command. To force +&scons; +to look-up a directory relative to the root of the source tree use #: +You only need to set &cv-F90PATH; if you need to define a specific +include path for Fortran 90 files. +You should normally set the &cv-FORTRANPATH; variable, +which specifies the include path +for the default Fortran compiler +for all Fortran versions. + +<example> +env = Environment(F90PATH='#/include') +</example> + +The directory look-up can also be forced using the +&Dir;() +function: + +<example> +include = Dir('include') +env = Environment(F90PATH=include) +</example> + +The directory list will be added to command lines +through the automatically-generated +&cv-_F90INCFLAGS; +construction variable, +which is constructed by +appending the values of the +&cv-INCPREFIX; and &cv-INCSUFFIX; +construction variables +to the beginning and end +of each directory in &cv-F90PATH;. +Any command lines you define that need +the F90PATH directory list should +include &cv-_F90INCFLAGS;: + +<example> +env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE") +</example> +</summary> +</cvar> + +<cvar name="F90PPCOM"> +<summary> +The command line used to compile a Fortran 90 source file to an object file +after first running the file through the C preprocessor. +Any options specified in the &cv-F90FLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +You only need to set &cv-F90PPCOM; if you need to use a specific +C-preprocessor command line for Fortran 90 files. +You should normally set the &cv-FORTRANPPCOM; variable, +which specifies the default C-preprocessor command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF90"> +<summary> +The Fortran 90 compiler used for generating shared-library objects. +You should normally set the &cv-SHFORTRAN; variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set &cv-SHF90; if you need to use a specific compiler +or compiler version for Fortran 90 files. +</summary> +</cvar> + +<cvar name="SHF90COM"> +<summary> +The command line used to compile a Fortran 90 source file +to a shared-library object file. +You only need to set &cv-SHF90COM; if you need to use a specific +command line for Fortran 90 files. +You should normally set the &cv-SHFORTRANCOM; variable, +which specifies the default command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF90COMSTR"> +<summary> +The string displayed when a Fortran 90 source file +is compiled to a shared-library object file. +If this is not set, then &cv-SHF90COM; or &cv-SHFORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="SHF90FLAGS"> +<summary> +Options that are passed to the Fortran 90 compiler +to generated shared-library objects. +You only need to set &cv-SHF90FLAGS; if you need to define specific +user options for Fortran 90 files. +You should normally set the &cv-SHFORTRANFLAGS; variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF90PPCOM"> +<summary> +The command line used to compile a Fortran 90 source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified in the &cv-SHF90FLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +You only need to set &cv-SHF90PPCOM; if you need to use a specific +C-preprocessor command line for Fortran 90 files. +You should normally set the &cv-SHFORTRANPPCOM; variable, +which specifies the default C-preprocessor command line +for all Fortran versions. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/f95.xml b/src/engine/SCons/Tool/f95.xml new file mode 100644 index 0000000..df74422 --- /dev/null +++ b/src/engine/SCons/Tool/f95.xml @@ -0,0 +1,196 @@ +<!-- __COPYRIGHT__ --> +<tool name="f95"> +<summary> +XXX +</summary> +</tool> + +<cvar name="F95"> +<summary> +The Fortran 95 compiler. +You should normally set the &cv-FORTRAN; variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set &cv-F95; if you need to use a specific compiler +or compiler version for Fortran 95 files. +</summary> +</cvar> + +<cvar name="F95COM"> +<summary> +The command line used to compile a Fortran 95 source file to an object file. +You only need to set &cv-F95COM; if you need to use a specific +command line for Fortran 95 files. +You should normally set the &cv-FORTRANCOM; variable, +which specifies the default command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="F95COMSTR"> +<summary> +The string displayed when a Fortran 95 source file +is compiled to an object file. +If this is not set, then &cv-F95COM; or &cv-FORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="F95FLAGS"> +<summary> +General user-specified options that are passed to the Fortran 95 compiler. +Note that this variable does +<emphasis>not</emphasis> +contain +<option>-I</option> +(or similar) include search path options +that scons generates automatically from &cv-F95PATH;. +See +&cv-_F95INCFLAGS; +below, +for the variable that expands to those options. +You only need to set &cv-F95FLAGS; if you need to define specific +user options for Fortran 95 files. +You should normally set the &cv-FORTRANFLAGS; variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. +</summary> +</cvar> + +<cvar name="_F95INCFLAGS"> +<summary> +An automatically-generated construction variable +containing the Fortran 95 compiler command-line options +for specifying directories to be searched for include files. +The value of &cv-_F95INCFLAGS; is created +by appending &cv-INCPREFIX; and &cv-INCSUFFIX; +to the beginning and end +of each directory in &cv-F95PATH;. +</summary> +</cvar> + +<cvar name="F95PATH"> +<summary> +The list of directories that the Fortran 95 compiler will search for include +directories. The implicit dependency scanner will search these +directories for include files. Don't explicitly put include directory +arguments in &cv-F95FLAGS; because the result will be non-portable +and the directories will not be searched by the dependency scanner. Note: +directory names in &cv-F95PATH; will be looked-up relative to the SConscript +directory when they are used in a command. To force +&scons; +to look-up a directory relative to the root of the source tree use #: +You only need to set &cv-F95PATH; if you need to define a specific +include path for Fortran 95 files. +You should normally set the &cv-FORTRANPATH; variable, +which specifies the include path +for the default Fortran compiler +for all Fortran versions. + +<example> +env = Environment(F95PATH='#/include') +</example> + +The directory look-up can also be forced using the +&Dir;() +function: + +<example> +include = Dir('include') +env = Environment(F95PATH=include) +</example> + +The directory list will be added to command lines +through the automatically-generated +&cv-_F95INCFLAGS; +construction variable, +which is constructed by +appending the values of the +&cv-INCPREFIX; and &cv-INCSUFFIX; +construction variables +to the beginning and end +of each directory in &cv-F95PATH;. +Any command lines you define that need +the F95PATH directory list should +include &cv-_F95INCFLAGS;: + +<example> +env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE") +</example> +</summary> +</cvar> + +<cvar name="F95PPCOM"> +<summary> +The command line used to compile a Fortran 95 source file to an object file +after first running the file through the C preprocessor. +Any options specified in the &cv-F95FLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +You only need to set &cv-F95PPCOM; if you need to use a specific +C-preprocessor command line for Fortran 95 files. +You should normally set the &cv-FORTRANPPCOM; variable, +which specifies the default C-preprocessor command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF95"> +<summary> +The Fortran 95 compiler used for generating shared-library objects. +You should normally set the &cv-SHFORTRAN; variable, +which specifies the default Fortran compiler +for all Fortran versions. +You only need to set &cv-SHF95; if you need to use a specific compiler +or compiler version for Fortran 95 files. +</summary> +</cvar> + +<cvar name="SHF95COM"> +<summary> +The command line used to compile a Fortran 95 source file +to a shared-library object file. +You only need to set &cv-SHF95COM; if you need to use a specific +command line for Fortran 95 files. +You should normally set the &cv-SHFORTRANCOM; variable, +which specifies the default command line +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF95COMSTR"> +<summary> +The string displayed when a Fortran 95 source file +is compiled to a shared-library object file. +If this is not set, then &cv-SHF95COM; or &cv-SHFORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="SHF95FLAGS"> +<summary> +Options that are passed to the Fortran 95 compiler +to generated shared-library objects. +You only need to set &cv-SHF95FLAGS; if you need to define specific +user options for Fortran 95 files. +You should normally set the &cv-SHFORTRANFLAGS; variable, +which specifies the user-specified options +passed to the default Fortran compiler +for all Fortran versions. +</summary> +</cvar> + +<cvar name="SHF95PPCOM"> +<summary> +The command line used to compile a Fortran 95 source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified in the &cv-SHF95FLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +You only need to set &cv-SHF95PPCOM; if you need to use a specific +C-preprocessor command line for Fortran 95 files. +You should normally set the &cv-SHFORTRANPPCOM; variable, +which specifies the default C-preprocessor command line +for all Fortran versions. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/fortran.xml b/src/engine/SCons/Tool/fortran.xml new file mode 100644 index 0000000..4282f30 --- /dev/null +++ b/src/engine/SCons/Tool/fortran.xml @@ -0,0 +1,240 @@ +<!-- __COPYRIGHT__ --> +<tool name="fortran"> +<summary> +XXX +</summary> +</tool> + +<cvar name="FORTRAN"> +<summary> +The default Fortran compiler +for all versions of Fortran. +</summary> +</cvar> + +<cvar name="FORTRANCOM"> +<summary> +The command line used to compile a Fortran source file to an object file. +By default, any options specified +in the &cv-FORTRANFLAGS;, &cv-CPPFLAGS;, &cv-_CPPDEFFLAGS;, +&cv-_FORTRANMODFLAG;, and &cv-_FORTRANINCFLAGS; construction variables +are included on this command line. +</summary> +</cvar> + +<cvar name="FORTRANCOMSTR"> +<summary> +The string displayed when a Fortran source file +is compiled to an object file. +If this is not set, then &cv-FORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="FORTRANFLAGS"> +<summary> +General user-specified options that are passed to the Fortran compiler. +Note that this variable does +<emphasis>not</emphasis> +contain +<option>-I</option> +(or similar) include or module search path options +that scons generates automatically from &cv-FORTRANPATH;. +See +&cv-_FORTRANINCFLAGS; and &cv-_FORTRANMODFLAG;, +below, +for the variables that expand those options. +</summary> +</cvar> + +<cvar name="_FORTRANINCFLAGS"> +<summary> +An automatically-generated construction variable +containing the Fortran compiler command-line options +for specifying directories to be searched for include +files and module files. +The value of &cv-_FORTRANINCFLAGS; is created +by prepending/appending &cv-INCPREFIX; and &cv-INCSUFFIX; +to the beginning and end +of each directory in &cv-FORTRANPATH;. +</summary> +</cvar> + +<cvar name="FORTRANMODDIR"> +<summary> +Directory location where the Fortran compiler should place +any module files it generates. This variable is empty, by default. Some +Fortran compilers will internally append this directory in the search path +for module files, as well +</summary> +</cvar> + +<cvar name="FORTRANMODDIRPREFIX"> +<summary> +The prefix used to specify a module directory on the Fortran compiler command +line. +This will be appended to the beginning of the directory +in the &cv-FORTRANMODDIR; construction variables +when the &cv-_FORTRANMODFLAG; variables is automatically generated. +</summary> +</cvar> + +<cvar name="FORTRANMODDIRSUFFIX"> +<summary> +The suffix used to specify a module directory on the Fortran compiler command +line. +This will be appended to the beginning of the directory +in the &cv-FORTRANMODDIR; construction variables +when the &cv-_FORTRANMODFLAG; variables is automatically generated. +</summary> +</cvar> + +<cvar name="_FORTRANMODFLAG"> +<summary> +An automatically-generated construction variable +containing the Fortran compiler command-line option +for specifying the directory location where the Fortran +compiler should place any module files that happen to get +generated during compilation. +The value of &cv-_FORTRANMODFLAG; is created +by prepending/appending &cv-FORTRANMODDIRPREFIX; and &cv-FORTRANMODDIRSUFFIX; +to the beginning and end of the directory in &cv-FORTRANMODDIR;. +</summary> +</cvar> + +<cvar name="FORTRANMODPREFIX"> +<summary> +The module file prefix used by the Fortran compiler. SCons assumes that +the Fortran compiler follows the quasi-standard naming convention for +module files of +<filename>module_name.mod</filename>. +As a result, this variable is left empty, by default. For situations in +which the compiler does not necessarily follow the normal convention, +the user may use this variable. Its value will be appended to every +module file name as scons attempts to resolve dependencies. +</summary> +</cvar> + +<cvar name="FORTRANMODSUFFIX"> +<summary> +The module file suffix used by the Fortran compiler. SCons assumes that +the Fortran compiler follows the quasi-standard naming convention for +module files of +<filename>module_name.mod</filename>. +As a result, this variable is set to ".mod", by default. For situations +in which the compiler does not necessarily follow the normal convention, +the user may use this variable. Its value will be appended to every +module file name as scons attempts to resolve dependencies. +</summary> +</cvar> + +<cvar name="FORTRANPATH"> +<summary> +The list of directories that the Fortran compiler will search for +include files and (for some compilers) module files. The Fortran implicit +dependency scanner will search these directories for include files (but +not module files since they are autogenerated and, as such, may not +actually exist at the time the scan takes place). Don't explicitly put +include directory arguments in FORTRANFLAGS because the result will be +non-portable and the directories will not be searched by the dependency +scanner. Note: directory names in FORTRANPATH will be looked-up relative +to the SConscript directory when they are used in a command. To force +&scons; +to look-up a directory relative to the root of the source tree use #: + +<example> +env = Environment(FORTRANPATH='#/include') +</example> + +The directory look-up can also be forced using the +&Dir;() +function: + +<example> +include = Dir('include') +env = Environment(FORTRANPATH=include) +</example> + +The directory list will be added to command lines +through the automatically-generated +&cv-_FORTRANINCFLAGS; +construction variable, +which is constructed by +appending the values of the +&cv-INCPREFIX; and &cv-INCSUFFIX; +construction variables +to the beginning and end +of each directory in &cv-FORTRANPATH;. +Any command lines you define that need +the FORTRANPATH directory list should +include &cv-_FORTRANINCFLAGS;: + +<example> +env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE") +</example> +</summary> +</cvar> + +<cvar name="FORTRANPPCOM"> +<summary> +The command line used to compile a Fortran source file to an object file +after first running the file through the C preprocessor. +By default, any options specified in the &cv-FORTRANFLAGS;, &cv-CPPFLAGS;, +_CPPDEFFLAGS, &cv-_FORTRANMODFLAG;, and &cv-_FORTRANINCFLAGS; +construction variables are included on this command line. +</summary> +</cvar> + +<cvar name="FORTRANSUFFIXES"> +<summary> +The list of suffixes of files that will be scanned +for Fortran implicit dependencies +(INCLUDE lines and USE statements). +The default list is: + +<example> +[".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP", +".f77", ".F77", ".f90", ".F90", ".f95", ".F95"] +</example> +</summary> +</cvar> + +<cvar name="SHFORTRAN"> +<summary> +The default Fortran compiler used for generating shared-library objects. +</summary> +</cvar> + +<cvar name="SHFORTRANCOM"> +<summary> +The command line used to compile a Fortran source file +to a shared-library object file. +</summary> +</cvar> + +<cvar name="SHFORTRANCOMSTR"> +<summary> +The string displayed when a Fortran source file +is compiled to a shared-library object file. +If this is not set, then &cv-SHFORTRANCOM; +(the command line) is displayed. +</summary> +</cvar> + +<cvar name="SHFORTRANFLAGS"> +<summary> +Options that are passed to the Fortran compiler +to generate shared-library objects. +</summary> +</cvar> + +<cvar name="SHFORTRANPPCOM"> +<summary> +The command line used to compile a Fortran source file to a +shared-library object file +after first running the file through the C preprocessor. +Any options specified +in the &cv-SHFORTRANFLAGS; and &cv-CPPFLAGS; construction variables +are included on this command line. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/g++.xml b/src/engine/SCons/Tool/g++.xml new file mode 100644 index 0000000..b6fb5b0 --- /dev/null +++ b/src/engine/SCons/Tool/g++.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="g++"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/g77.xml b/src/engine/SCons/Tool/g77.xml new file mode 100644 index 0000000..94f415a --- /dev/null +++ b/src/engine/SCons/Tool/g77.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="g77"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/gas.xml b/src/engine/SCons/Tool/gas.xml new file mode 100644 index 0000000..29179e2 --- /dev/null +++ b/src/engine/SCons/Tool/gas.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="gas"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/gcc.xml b/src/engine/SCons/Tool/gcc.xml new file mode 100644 index 0000000..51dac07 --- /dev/null +++ b/src/engine/SCons/Tool/gcc.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="gcc"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/gnulink.xml b/src/engine/SCons/Tool/gnulink.xml new file mode 100644 index 0000000..d7c1a42 --- /dev/null +++ b/src/engine/SCons/Tool/gnulink.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="gnulink"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/gs.xml b/src/engine/SCons/Tool/gs.xml new file mode 100644 index 0000000..377bfc3 --- /dev/null +++ b/src/engine/SCons/Tool/gs.xml @@ -0,0 +1,34 @@ +<!-- __COPYRIGHT__ --> +<tool name="gs"> +<summary> +XXX +</summary> +</tool> + +<cvar name="GS"> +<summary> +The Ghostscript program used to convert PostScript to PDF files. +</summary> +</cvar> + +<cvar name="GSCOM"> +<summary> +The Ghostscript command line used to convert PostScript to PDF files. +</summary> +</cvar> + +<cvar name="GSCOMSTR"> +<summary> +The string displayed when +Ghostscript is used to convert +a PostScript file to a PDF file. +If this is not set, then &cv-GSCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="GSFLAGS"> +<summary> +General options passed to the Ghostscript program +when converting PostScript to PDF files. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/hpc++.xml b/src/engine/SCons/Tool/hpc++.xml new file mode 100644 index 0000000..5c13718 --- /dev/null +++ b/src/engine/SCons/Tool/hpc++.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="hpc++"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/hpcc.xml b/src/engine/SCons/Tool/hpcc.xml new file mode 100644 index 0000000..db2fccd --- /dev/null +++ b/src/engine/SCons/Tool/hpcc.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="hpcc"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/hplink.xml b/src/engine/SCons/Tool/hplink.xml new file mode 100644 index 0000000..71f5e22 --- /dev/null +++ b/src/engine/SCons/Tool/hplink.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="hplink"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/icc.xml b/src/engine/SCons/Tool/icc.xml new file mode 100644 index 0000000..a6fdea2 --- /dev/null +++ b/src/engine/SCons/Tool/icc.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="icc"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/icl.xml b/src/engine/SCons/Tool/icl.xml new file mode 100644 index 0000000..be20912 --- /dev/null +++ b/src/engine/SCons/Tool/icl.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="icl"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/ifl.xml b/src/engine/SCons/Tool/ifl.xml new file mode 100644 index 0000000..34dfecb --- /dev/null +++ b/src/engine/SCons/Tool/ifl.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="ifl"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/ifort.xml b/src/engine/SCons/Tool/ifort.xml new file mode 100644 index 0000000..2cb889b --- /dev/null +++ b/src/engine/SCons/Tool/ifort.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="ifort"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/ilink.xml b/src/engine/SCons/Tool/ilink.xml new file mode 100644 index 0000000..4f86883 --- /dev/null +++ b/src/engine/SCons/Tool/ilink.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="ilink"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/ilink32.xml b/src/engine/SCons/Tool/ilink32.xml new file mode 100644 index 0000000..0d62be4 --- /dev/null +++ b/src/engine/SCons/Tool/ilink32.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="ilink32"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/intelc.xml b/src/engine/SCons/Tool/intelc.xml new file mode 100644 index 0000000..47cfbec --- /dev/null +++ b/src/engine/SCons/Tool/intelc.xml @@ -0,0 +1,14 @@ +<!-- __COPYRIGHT__ --> +<tool name="intelc"> +<summary> +XXX +</summary> +</tool> + +<cvar name="INTEL_C_COMPILER_VERSION"> +<summary> +Set by the "intelc" Tool +to the major version number of the Intel C compiler +selected for use. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/jar.xml b/src/engine/SCons/Tool/jar.xml new file mode 100644 index 0000000..b89468d --- /dev/null +++ b/src/engine/SCons/Tool/jar.xml @@ -0,0 +1,82 @@ +<!-- __COPYRIGHT__ --> +<tool name="jar"> +<summary> +XXX +</summary> +</tool> + +<builder name="Jar"> +<summary> +Builds a Java archive (<filename>.jar</filename>) file +from a source tree of <filename>.class</filename> files. +If the &cv-JARCHDIR; value is set, the +&jar; +command will change to the specified directory using the +<option>-C</option> +option. +If the contents any of the source files begin with the string +<literal>Manifest-Version</literal>, +the file is assumed to be a manifest +and is passed to the +&jar; +command with the +<option>m</option> +option set. + +<example> +env.Jar(target = 'foo.jar', source = 'classes') +</example> +</summary> +</builder> + +<cvar name="JAR"> +<summary> +The Java archive tool. +</summary> +</cvar> + +<cvar name="JARCHDIR"> +<summary> +The directory to which the Java archive tool should change +(using the +<option>-C</option> +option). +</summary> +</cvar> + +<cvar name="JARCOM"> +<summary> +The command line used to call the Java archive tool. +</summary> +</cvar> + +<cvar name="JARCOMSTR"> +<summary> +The string displayed when the Java archive tool +is called +If this is not set, then &cv-JARCOM; (the command line) is displayed. + +<example> +env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET") +</example> +</summary> +</cvar> + +<cvar name="JARFLAGS"> +<summary> +General options passed to the Java archive tool. +By default this is set to +<option>cf</option> +to create the necessary +<command>jar</command> +file. +</summary> +</cvar> + +<cvar name="JARSUFFIX"> +<summary> +The suffix for Java archives: +<filename>.jar</filename> +by default. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/javac.xml b/src/engine/SCons/Tool/javac.xml new file mode 100644 index 0000000..9cd40b5 --- /dev/null +++ b/src/engine/SCons/Tool/javac.xml @@ -0,0 +1,109 @@ +<!-- __COPYRIGHT__ --> +<tool name="javac"> +<summary> +XXX +</summary> +</tool> + +<builder name="Java"> +<summary> +Builds one or more Java class files +from one or more source trees of <filename>.java</filename> files. +The class files will be placed underneath +the specified target directory. +SCons will parse each source <filename>.java</filename> file +to find the classes +(including inner classes) +defined within that file, +and from that figure out the +target <filename>.class</filename> files that will be created. +SCons will also search each Java file +for the Java package name, +which it assumes can be found on a line +beginning with the string +<literal>package</literal> +in the first column; +the resulting <filename>.class</filename> files +will be placed in a directory reflecting +the specified package name. +For example, +the file +<filename>Foo.java</filename> +defining a single public +<classname>Foo</classname> +class and +containing a package name of +<classname>sub.dir</classname> +will generate a corresponding +<filename>sub/dir/Foo.class</filename> +class file. + +Example: + +<example> +env.Java(target = 'classes', source = 'src') +env.Java(target = 'classes', source = ['src1', 'src2']) +</example> +</summary> +</builder> + +<cvar name="JAVAC"> +<summary> +The Java compiler. +</summary> +</cvar> + +<cvar name="JAVACCOM"> +<summary> +The command line used to compile a directory tree containing +Java source files to +corresponding Java class files. +Any options specified in the &cv-JAVACFLAGS; construction variable +are included on this command line. +</summary> +</cvar> + +<cvar name="JAVACCOMSTR"> +<summary> +The string displayed when compiling +a directory tree of Java source files to +corresponding Java class files. +If this is not set, then &cv-JAVACCOM; (the command line) is displayed. + +<example> +env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES") +</example> +</summary> +</cvar> + +<cvar name="JAVACFLAGS"> +<summary> +General options that are passed to the Java compiler. +</summary> +</cvar> + +<cvar name="JAVACLASSDIR"> +<summary> +The directory in which Java class files may be found. +This is stripped from the beginning of any Java .class +file names supplied to the +<literal>JavaH</literal> +builder. +</summary> +</cvar> + +<cvar name="JAVACLASSSUFFIX"> +<summary> +The suffix for Java class files; +<filename>.class</filename> +by default. +</summary> +</cvar> + +<cvar name="JAVASUFFIX"> +<summary> +The suffix for Java files; +<filename>.java</filename> +by default. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/javah.xml b/src/engine/SCons/Tool/javah.xml new file mode 100644 index 0000000..7699784 --- /dev/null +++ b/src/engine/SCons/Tool/javah.xml @@ -0,0 +1,82 @@ +<!-- __COPYRIGHT__ --> +<tool name="javah"> +<summary> +XXX +</summary> +</tool> + +<builder name="JavaH"> +<summary> +Builds C header and source files for +implementing Java native methods. +The target can be either a directory +in which the header files will be written, +or a header file name which +will contain all of the definitions. +The source can be either the names of <filename>.class</filename> files, +or the objects returned from the +&b-Java; +builder method. + +If the construction variable +&cv-JAVACLASSDIR; +is set, either in the environment +or in the call to the +&b-JavaH; +builder method itself, +then the value of the variable +will be stripped from the +beginning of any <filename>.class</filename> file names. + +Examples: + +<example> +# builds java_native.h +classes = env.Java(target = 'classdir', source = 'src') +env.JavaH(target = 'java_native.h', source = classes) + +# builds include/package_foo.h and include/package_bar.h +env.JavaH(target = 'include', + source = ['package/foo.class', 'package/bar.class']) + +# builds export/foo.h and export/bar.h +env.JavaH(target = 'export', + source = ['classes/foo.class', 'classes/bar.class'], + JAVACLASSDIR = 'classes') +</example> +</summary> +</builder> + +<cvar name="JAVAH"> +<summary> +The Java generator for C header and stub files. +</summary> +</cvar> + +<cvar name="JAVAHCOM"> +<summary> +The command line used to generate C header and stub files +from Java classes. +Any options specified in the &cv-JAVAHFLAGS; construction variable +are included on this command line. +</summary> +</cvar> + +<cvar name="JAVAHCOMSTR"> +<summary> +The string displayed when C header and stub files +are generated from Java classes. +If this is not set, then &cv-JAVAHCOM; (the command line) is displayed. + +<example> +env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES") +</example> +</summary> +</cvar> + +<cvar name="JAVAHFLAGS"> +<summary> +General options passed to the C header and stub file generator +for Java classes. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/latex.xml b/src/engine/SCons/Tool/latex.xml new file mode 100644 index 0000000..6a415f7 --- /dev/null +++ b/src/engine/SCons/Tool/latex.xml @@ -0,0 +1,36 @@ +<!-- __COPYRIGHT__ --> +<tool name="latex"> +<summary> +XXX +</summary> +</tool> + +<cvar name="LATEX"> +<summary> +The LaTeX structured formatter and typesetter. +</summary> +</cvar> + +<cvar name="LATEXCOM"> +<summary> +The command line used to call the LaTeX structured formatter and typesetter. +</summary> +</cvar> + +<cvar name="LATEXCOMSTR"> +<summary> +The string displayed when calling +the LaTeX structured formatter and typesetter. +If this is not set, then &cv-LATEXCOM; (the command line) is displayed. + +<example> +env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES") +</example> +</summary> +</cvar> + +<cvar name="LATEXFLAGS"> +<summary> +General options passed to the LaTeX structured formatter and typesetter. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/lex.py b/src/engine/SCons/Tool/lex.py index 4a17fae..3331f6c 100644 --- a/src/engine/SCons/Tool/lex.py +++ b/src/engine/SCons/Tool/lex.py @@ -33,17 +33,19 @@ selection method. __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" -import SCons.Defaults +import SCons.Action import SCons.Tool import SCons.Util +LexAction = SCons.Action.Action("$LEXCOM", "$LEXCOMSTR") + def generate(env): """Add Builders and construction variables for lex to an Environment.""" c_file, cxx_file = SCons.Tool.createCFileBuilders(env) - c_file.add_action('.l', SCons.Defaults.LexAction) - c_file.add_action('.lex', SCons.Defaults.LexAction) - cxx_file.add_action('.ll', SCons.Defaults.LexAction) + c_file.add_action('.l', LexAction) + c_file.add_action('.lex', LexAction) + cxx_file.add_action('.ll', LexAction) env['LEX'] = env.Detect('flex') or 'lex' env['LEXFLAGS'] = SCons.Util.CLVar('') diff --git a/src/engine/SCons/Tool/lex.xml b/src/engine/SCons/Tool/lex.xml new file mode 100644 index 0000000..3fb62e1 --- /dev/null +++ b/src/engine/SCons/Tool/lex.xml @@ -0,0 +1,37 @@ +<!-- __COPYRIGHT__ --> +<tool name="lex"> +<summary> +XXX +</summary> +</tool> + +<cvar name="LEX"> +<summary> +The lexical analyzer generator. +</summary> +</cvar> + +<cvar name="LEXCOM"> +<summary> +The command line used to call the lexical analyzer generator +to generate a source file. +</summary> +</cvar> + +<cvar name="LEXCOMSTR"> +<summary> +The string displayed when generating a source file +using the lexical analyzer generator. +If this is not set, then &cv-LEXCOM; (the command line) is displayed. + +<example> +env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES") +</example> +</summary> +</cvar> + +<cvar name="LEXFLAGS"> +<summary> +General options passed to the lexical analyzer generator. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/link.xml b/src/engine/SCons/Tool/link.xml new file mode 100644 index 0000000..420a5b7 --- /dev/null +++ b/src/engine/SCons/Tool/link.xml @@ -0,0 +1,146 @@ +<!-- __COPYRIGHT__ --> +<tool name="link"> +<summary> +XXX +</summary> +</tool> + +<cvar name="LDMODULE"> +<summary> +The linker for building loadable modules. +By default, this is the same as &cv-SHLINK;. +</summary> +</cvar> + +<cvar name="LDMODULECOM"> +<summary> +The command line for building loadable modules. +On Mac OS X, this uses the &cv-LDMODULE;, +&cv-LDMODULEFLAGS; and &cv-FRAMEWORKSFLAGS; variables. +On other systems, this is the same as &cv-SHLINK;. +</summary> +</cvar> + +<cvar name="LDMODULECOMSTR"> +<summary> +The string displayed when building loadable modules. +If this is not set, then &cv-LDMODULECOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="LDMODULEFLAGS"> +<summary> +General user options passed to the linker for building loadable modules. +</summary> +</cvar> + +<cvar name="LDMODULEPREFIX"> +<summary> +The prefix used for loadable module file names. +On Mac OS X, this is null; +on other systems, this is +the same as &cv-SHLIBPREFIX;. +</summary> +</cvar> + +<cvar name="LDMODULESUFFIX"> +<summary> +The suffix used for loadable module file names. +On Mac OS X, this is null; +on other systems, this is +the same as $SHLIBSUFFIX. +</summary> +</cvar> + +<cvar name="LINK"> +<summary> +The linker. +</summary> +</cvar> + +<cvar name="LINKCOM"> +<summary> +The command line used to link object files into an executable. +</summary> +</cvar> + +<cvar name="LINKCOMSTR"> +<summary> +The string displayed when object files +are linked into an executable. +If this is not set, then &cv-LINKCOM; (the command line) is displayed. + +<example> +env = Environment(LINKCOMSTR = "Linking $TARGET") +</example> +</summary> +</cvar> + +<cvar name="LINKFLAGS"> +<summary> +General user options passed to the linker. +Note that this variable should +<emphasis>not</emphasis> +contain +<option>-l</option> +(or similar) options for linking with the libraries listed in &cv-LIBS;, +nor +<option>-L</option> +(or similar) library search path options +that scons generates automatically from &cv-LIBPATH;. +See +&cv-_LIBFLAGS; +above, +for the variable that expands to library-link options, +and +&cv-_LIBDIRFLAGS; +above, +for the variable that expands to library search path options. +</summary> +</cvar> + +<cvar name="SHLINK"> +<summary> +The linker for programs that use shared libraries. +</summary> +</cvar> + +<cvar name="SHLINKCOM"> +<summary> +The command line used to link programs using shared libaries. +</summary> +</cvar> + +<cvar name="SHLINKCOMSTR"> +<summary> +The string displayed when programs using shared libraries are linked. +If this is not set, then &cv-SHLINKCOM; (the command line) is displayed. + +<example> +env = Environment(SHLINKCOMSTR = "Linking shared $TARGET") +</example> +</summary> +</cvar> + +<cvar name="SHLINKFLAGS"> +<summary> +General user options passed to the linker for programs using shared libraries. +Note that this variable should +<emphasis>not</emphasis> +contain +<option>-l</option> +(or similar) options for linking with the libraries listed in &cv-LIBS;, +nor +<option>-L</option> +(or similar) include search path options +that scons generates automatically from &cv-LIBPATH;. +See +&cv-_LIBFLAGS; +above, +for the variable that expands to library-link options, +and +&cv-_LIBDIRFLAGS; +above, +for the variable that expands to library search path options. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/linkloc.xml b/src/engine/SCons/Tool/linkloc.xml new file mode 100644 index 0000000..12a9d50 --- /dev/null +++ b/src/engine/SCons/Tool/linkloc.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="linkloc"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/m4.xml b/src/engine/SCons/Tool/m4.xml new file mode 100644 index 0000000..1f91770 --- /dev/null +++ b/src/engine/SCons/Tool/m4.xml @@ -0,0 +1,48 @@ +<!-- __COPYRIGHT__ --> +<tool name="m4"> +<summary> +XXX +</summary> +</tool> + +<builder name="M4"> +<summary> +Builds an output file from an M4 input file. +This uses a default &cv-M4FLAGS; value of +<option>-E</option>, +which considers all warnings to be fatal +and stops on the first warning +when using the GNU version of m4. +Example: + +<example> +env.M4(target = 'foo.c', source = 'foo.c.m4') +</example> +</summary> +</builder> + +<cvar name="M4"> +<summary> +The M4 macro preprocessor. +</summary> +</cvar> + +<cvar name="M4COM"> +<summary> +The command line used to pass files through the M4 macro preprocessor. +</summary> +</cvar> + +<cvar name="M4COMSTR"> +<summary> +The string displayed when +a file is passed through the M4 macro preprocessor. +If this is not set, then &cv-M4COM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="M4FLAGS"> +<summary> +General options passed to the M4 macro preprocessor. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/masm.xml b/src/engine/SCons/Tool/masm.xml new file mode 100644 index 0000000..82c14cf --- /dev/null +++ b/src/engine/SCons/Tool/masm.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="masm"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/midl.xml b/src/engine/SCons/Tool/midl.xml new file mode 100644 index 0000000..4d5c7e0 --- /dev/null +++ b/src/engine/SCons/Tool/midl.xml @@ -0,0 +1,29 @@ +<!-- __COPYRIGHT__ --> +<tool name="midl"> +<summary> +XXX +</summary> +</tool> + +<builder name="TypeLibrary"> +<summary> +Builds a Windows type library (<filename>.tlb</filename>) +file from an input IDL file (<filename>.idl</filename>). +In addition, it will build the associated inteface stub and +proxy source files, +naming them according to the base name of the <filename>.idl</filename> file. +For example, + +<example> +env.TypeLibrary(source="foo.idl") +</example> + +Will create <filename>foo.tlb</filename>, +<filename>foo.h</filename>, +<filename>foo_i.c</filename>, +<filename>foo_p.c</filename> +and +<filename>foo_data.c</filename> +files. +</summary> +</builder> diff --git a/src/engine/SCons/Tool/mingw.xml b/src/engine/SCons/Tool/mingw.xml new file mode 100644 index 0000000..273a861 --- /dev/null +++ b/src/engine/SCons/Tool/mingw.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="mingw"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/mslib.xml b/src/engine/SCons/Tool/mslib.xml new file mode 100644 index 0000000..7da4365 --- /dev/null +++ b/src/engine/SCons/Tool/mslib.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="mslib"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/mslink.xml b/src/engine/SCons/Tool/mslink.xml new file mode 100644 index 0000000..82249e7 --- /dev/null +++ b/src/engine/SCons/Tool/mslink.xml @@ -0,0 +1,105 @@ +<!-- __COPYRIGHT__ --> +<tool name="mslink"> +<summary> +XXX +</summary> +</tool> + +<cvar name="no_import_lib"> +<summary> +When set to non-zero, +suppresses creation of a corresponding Win32 static import lib by the +<literal>SharedLibrary</literal> +builder when used with +MinGW, Microsoft Visual Studio or Metrowerks. +This also suppresses creation +of an export (.exp) file +when using Microsoft Visual Studio. +</summary> +</cvar> + +<cvar name="PDB"> +<summary> +The Microsoft Visual C++ PDB file that will store debugging information for +object files, shared libraries, and programs. This variable is ignored by +tools other than Microsoft Visual C++. +When this variable is +defined SCons will add options to the compiler and linker command line to +cause them to generate external debugging information, and will also set up the +dependencies for the PDB file. Example: + +<example> +env['PDB'] = 'hello.pdb' +</example> +</summary> +</cvar> + +<cvar name="REGSVR"> +<summary> +The program used on WIN32 systems +to register a newly-built DLL library +whenever the &b-SharedLibrary; builder +is passed a keyword argument of <literal>register=1</literal>. +</summary> +</cvar> + +<cvar name="REGSVRCOM"> +<summary> +The command line used on WIN32 systems +to register a newly-built DLL library +whenever the &b-SharedLibrary; builder +is passed a keyword argument of <literal>register=1</literal>. +</summary> +</cvar> + +<cvar name="REGSVRCOMSTR"> +<summary> +The string displayed when registering a newly-built DLL file. +If this is not set, then &cv-REGSVRCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="REGSVRFLAGS"> +<summary> +Flags passed to the DLL registration program +on WIN32 systems when a newly-built DLL library is registered. +By default, +this includes the <option>/s</option> +that prevents dialog boxes from popping up +and requiring user attention. +</summary> +</cvar> + +<cvar name="WIN32_INSERT_DEF"> +<summary> +When this is set to true, +a library build of a WIN32 shared library (.dll file) +will also build a corresponding .def file at the same time, +if a .def file is not already listed as a build target. +The default is 0 (do not build a .def file). +</summary> +</cvar> + +<cvar name="WIN32DEFPREFIX"> +<summary> +The prefix used for WIN32 .def file names. +</summary> +</cvar> + +<cvar name="WIN32DEFSUFFIX"> +<summary> +The suffix used for WIN32 .def file names. +</summary> +</cvar> + +<cvar name="WIN32EXPPREFIX"> +<summary> +XXX The prefix used for WIN32 .def file names. +</summary> +</cvar> + +<cvar name="WIN32EXPSUFFIX"> +<summary> +XXX The suffix used for WIN32 .def file names. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/msvc.xml b/src/engine/SCons/Tool/msvc.xml new file mode 100644 index 0000000..426014b --- /dev/null +++ b/src/engine/SCons/Tool/msvc.xml @@ -0,0 +1,112 @@ +<!-- __COPYRIGHT__ --> +<tool name="msvc"> +<summary> +XXX +</summary> +</tool> + +<builder name="PCH"> +<summary> +Builds a Microsoft Visual C++ precompiled header. +Calling this builder method +returns a list of two targets: the PCH as the first element, and the object +file as the second element. Normally the object file is ignored. +This builder method is only +provided when Microsoft Visual C++ is being used as the compiler. +The PCH builder method is generally used in +conjuction with the PCH construction variable to force object files to use +the precompiled header: + +<example> +env['PCH'] = env.PCH('StdAfx.cpp')[0] +</example> +</summary> +</builder> + +<builder name="RES"> +<summary> +Builds a Microsoft Visual C++ resource file. +This builder method is only provided +when Microsoft Visual C++ or MinGW is being used as the compiler. The +<filename>.res</filename> +(or +<filename>.o</filename> +for MinGW) suffix is added to the target name if no other suffix is given. +The source +file is scanned for implicit dependencies as though it were a C file. Example: + +<example> +env.RES('resource.rc') +</example> +</summary> +</builder> + +<cvar name="PCH"> +<summary> +The Microsoft Visual C++ precompiled header that will be used when compiling +object files. This variable is ignored by tools other than Microsoft Visual C++. +When this variable is +defined SCons will add options to the compiler command line to +cause it to use the precompiled header, and will also set up the +dependencies for the PCH file. Example: + +<example> +env['PCH'] = 'StdAfx.pch' +</example> +</summary> +</cvar> + +<cvar name="PCHCOM"> +<summary> +The command line used by the +&b-PCH; +builder to generated a precompiled header. +</summary> +</cvar> + +<cvar name="PCHCOMSTR"> +<summary> +The string displayed when generating a precompiled header. +If this is not set, then &cv-PCHCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="PCHSTOP"> +<summary> +This variable specifies how much of a source file is precompiled. This +variable is ignored by tools other than Microsoft Visual C++, or when +the PCH variable is not being used. When this variable is define it +must be a string that is the name of the header that +is included at the end of the precompiled portion of the source files, or +the empty string if the "#pragma hrdstop" construct is being used: + +<example> +env['PCHSTOP'] = 'StdAfx.h' +</example> +</summary> +</cvar> + +<cvar name="RC"> +<summary> +The resource compiler used by the RES builder. +</summary> +</cvar> + +<cvar name="RCCOM"> +<summary> +The command line used by the RES builder. +</summary> +</cvar> + +<cvar name="RCCOMSTR"> +<summary> +The string displayed when invoking the resource compiler. +If this is not set, then &cv-RCCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="RCFLAGS"> +<summary> +The flags passed to the resource compiler by the RES builder. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/msvs.xml b/src/engine/SCons/Tool/msvs.xml new file mode 100644 index 0000000..4103ce1 --- /dev/null +++ b/src/engine/SCons/Tool/msvs.xml @@ -0,0 +1,266 @@ +<!-- __COPYRIGHT__ --> +<tool name="msvs"> +<summary> +XXX +</summary> +</tool> + +<builder name ="MSVSProject"> +<summary> +Builds Microsoft Visual Studio project files. +This builds a Visual Studio project file, based on the version of +Visual Studio that is configured (either the latest installed version, +or the version set by +&cv-MSVS_VERSION; +in the Environment constructor). +For VS 6, it will generate +<filename>.dsp</filename> +and +<filename>.dsw</filename> +files, for VS 7, it will +generate +<filename>.vcproj</filename> +and +<filename>.sln</filename> +files. + +It takes several lists of filenames to be placed into the project +file, currently these are limited to +<literal>srcs</literal>, +<literal>incs</literal>, +<literal>localincs</literal>, +<literal>resources</literal>, +and +<literal>misc</literal>. +These are pretty self explanatory, but it +should be noted that the <literal>srcs</literal> list +is NOT added to the &cv-SOURCES; +construction variable. This is because it represents a list of files +to be added to the project file, not the source used to build the +project file (in this case, the "source" is the &SConscript; file used +to call MSVSProject). + +In addition to these values (which are all optional, although not +specifying any of them results in an empty project file), the +following values must be specified: + +target: The name of the target +<filename>.dsp</filename> +or +<filename>.vcproj</filename> +file. The correct +suffix for the version of Visual Studio must be used, but the +&cv-MSVSPROJECTSUFFIX; +construction value +will be defined to the correct value (see example below). + +variant: The name of this particular variant. These are typically +things like "Debug" or "Release", but really can be anything you want. +Multiple calls to MSVSProject with different variants are allowed: all +variants will be added to the project file with their appropriate +build targets and sources. + +buildtarget: A list of SCons.Node.FS objects which is returned from +the command which builds the target. This is used to tell SCons what +to build when the 'build' button is pressed inside of the IDE. + +Example usage: + +<example> +barsrcs = ['bar.cpp'], +barincs = ['bar.h'], +barlocalincs = ['StdAfx.h'] +barresources = ['bar.rc','resource.h'] +barmisc = ['bar_readme.txt'] + +dll = local.SharedLibrary(target = 'bar.dll', + source = barsrcs) + +local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], + srcs = barsrcs, + incs = barincs, + localincs = barlocalincs, + resources = barresources, + misc = barmisc, + buildtarget = dll, + variant = 'Release') +</example> +</summary> +</builder> + +<cvar name="MSVS"> +<summary> +When the Microsoft Visual Studio tools are initialized, they set up +this dictionary with the following keys: + +<envar>VERSION</envar> +the version of MSVS being used (can be set via +MSVS_VERSION) + +<envar>VERSIONS</envar> +the available versions of MSVS installed + +<envar>VCINSTALLDIR</envar> +installed directory of Visual C++ + +<envar>VSINSTALLDIR</envar> +installed directory of Visual Studio + +<envar>FRAMEWORKDIR</envar> +installed directory of the .NET framework + +<envar>FRAMEWORKVERSIONS</envar> +list of installed versions of the .NET framework, sorted latest to oldest. + +<envar>FRAMEWORKVERSION</envar> +latest installed version of the .NET framework + +<envar>FRAMEWORKSDKDIR</envar> +installed location of the .NET SDK. + +<envar>PLATFORMSDKDIR</envar> +installed location of the Platform SDK. + +<envar>PLATFORMSDK_MODULES</envar> +dictionary of installed Platform SDK modules, +where the dictionary keys are keywords for the various modules, and +the values are 2-tuples where the first is the release date, and the +second is the version number. + +If a value isn't set, it wasn't available in the registry. +</summary> +</cvar> + +<cvar name="MSVS_IGNORE_IDE_PATHS"> +<summary> +Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings, +instead of the settings from the IDE. + +For Visual Studio, SCons will (by default) automatically determine +where MSVS is installed, and use the LIB, INCLUDE, and PATH variables +set by the IDE. You can override this behavior by setting these +variables after Environment initialization, or by setting +<envar>MSVS_IGNORE_IDE_PATHS = 1</envar> +in the Environment initialization. +Specifying this will not leave these unset, but will set them to a +minimal set of paths needed to run the tools successfully. + +For VS6, the mininimal set is: +<example> + INCLUDE:'VSDir\VC98\ATL\include;VSDir\VC98\MFC\include;VSDir\VC98\include' + LIB:'VSDir\VC98\MFC\lib;VSDir\VC98\lib' + PATH:'VSDir\Common\MSDev98\bin;VSDir\VC98\bin' +</example> +For VS7, it is: +<example> + INCLUDE:'VSDir\Vc7\atlmfc\include;VSDir\Vc7\include' + LIB:'VSDir\Vc7\atlmfc\lib;VSDir\Vc7\lib' + PATH:'VSDir\Common7\Tools\bin;VSDir\Common7\Tools;VSDir\Vc7\bin' +</example> + +Where 'VSDir' is the installed location of Visual Studio. +</summary> +</cvar> + +<cvar name="MSVS_USE_MFC_DIRS"> +<summary> +Tells the MS Visual Studio tool(s) to use +the MFC directories in its default paths +for compiling and linking. +Under MSVS version 6, +setting +<envar>MSVS_USE_MFC_DIRS</envar> +to a non-zero value +adds the +<filename>ATL\include</filename> +and +<filename>MFC\include</filename> +directories to +the default +<envar>INCLUDE</envar> +external environment variable, +and adds the +<envar>MFC\lib</envar> +directory to +the default +<envar>LIB</envar> +external environment variable. +Under MSVS version 7, +setting +<envar>MSVS_USE_MFC_DIRS</envar> +to a non-zero value +adds the +<envar>atlmfc\include</envar> +directory to the default +<envar>INCLUDE</envar> +external environment variable, +and adds the +<envar>atlmfc\lib</envar> +directory to the default +<envar>LIB</envar> +external environment variable. +The current default value is +<literal>1</literal> +which means these directories +are added to the paths by default. +This default value is likely to change +in a future release, +so users who want the ATL and MFC +values included in their paths +are encouraged to enable the +<envar>MSVS_USE_MFC_DIRS</envar> +value explicitly +to avoid future incompatibility. +This variable has no effect if the +<envar>INCLUDE</envar> +or +<envar>LIB</envar> +environment variables are set explictly. +</summary> +</cvar> + +<cvar name="MSVS_VERSION"> +<summary> +Sets the preferred version of MSVS to use. + +SCons will (by default) select the latest version of MSVS +installed on your machine. So, if you have version 6 and version 7 +(MSVS .NET) installed, it will prefer version 7. You can override this by +specifying the +<envar>MSVS_VERSION</envar> +variable in the Environment initialization, setting it to the +appropriate version ('6.0' or '7.0', for example). +If the given version isn't installed, tool initialization will fail. +</summary> +</cvar> + +<cvar name="MSVSPROJECTCOM"> +<summary> +The action used to generate Microsoft Visual Studio +project and solution files. +</summary> +</cvar> + +<cvar name="MSVSPROJECTSUFFIX"> +<summary> +The suffix used for Microsoft Visual Studio project (DSP) files. +The default value is +<filename>.vcproj</filename> +when using Visual Studio version 7.x (.NET), +and +<filename>.dsp</filename> +when using earlier versions of Visual Studio. +</summary> +</cvar> + +<cvar name="MSVSSOLUTIONSUFFIX"> +<summary> +The suffix used for Microsoft Visual Studio solution (DSW) files. +The default value is +<filename>.sln</filename> +when using Visual Studio version 7.x (.NET), +and +<filename>.dsw</filename> +when using earlier versions of Visual Studio. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/mwcc.xml b/src/engine/SCons/Tool/mwcc.xml new file mode 100644 index 0000000..83eaab3 --- /dev/null +++ b/src/engine/SCons/Tool/mwcc.xml @@ -0,0 +1,20 @@ +<!-- __COPYRIGHT__ --> +<tool name="mwcc"> +<summary> +XXX +</summary> +</tool> + +<cvar name="MWCW_VERSION"> +<summary> +The version number of the MetroWerks CodeWarrior C compiler +to be used. +</summary> +</cvar> + +<cvar name="MWCW_VERSIONS"> +<summary> +A list of installed versions of the MetroWerks CodeWarrior C compiler +on this system. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/mwld.xml b/src/engine/SCons/Tool/mwld.xml new file mode 100644 index 0000000..ade9848 --- /dev/null +++ b/src/engine/SCons/Tool/mwld.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="mwld"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/nasm.xml b/src/engine/SCons/Tool/nasm.xml new file mode 100644 index 0000000..328386e --- /dev/null +++ b/src/engine/SCons/Tool/nasm.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="nasm"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/pdflatex.xml b/src/engine/SCons/Tool/pdflatex.xml new file mode 100644 index 0000000..7878079 --- /dev/null +++ b/src/engine/SCons/Tool/pdflatex.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="pdflatex"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/pdftex.xml b/src/engine/SCons/Tool/pdftex.xml new file mode 100644 index 0000000..701a280 --- /dev/null +++ b/src/engine/SCons/Tool/pdftex.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="pdftex"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/qt.xml b/src/engine/SCons/Tool/qt.xml new file mode 100644 index 0000000..b5335b6 --- /dev/null +++ b/src/engine/SCons/Tool/qt.xml @@ -0,0 +1,274 @@ +<!-- __COPYRIGHT__ --> +<tool name="qt"> +<summary> +XXX +</summary> +</tool> + +<builder name="Moc"> +<summary> +Builds an output file from a moc input file. Moc input files are either +header files or cxx files. This builder is only available after using the +tool 'qt'. See the &cv-QTDIR; variable for more information. +Example: + +<example> +env.Moc('foo.h') # generates moc_foo.cc +env.Moc('foo.cpp') # generates foo.moc +</example> +</summary> +</builder> + +<builder name="Uic"> +<summary> +Builds a header file, an implementation file and a moc file from an ui file. +and returns the corresponding nodes in the above order. +This builder is only available after using the tool 'qt'. Note: you can +specify <filename>.ui</filename> files directly as source +files to the &b-Program;, +&b-Library; and &b-SharedLibrary; builders +without using this builder. Using this builder lets you override the standard +naming conventions (be careful: prefixes are always prepended to names of +built files; if you don't want prefixes, you may set them to ``). +See the &cv-QTDIR; variable for more information. +Example: + +<example> +env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] +env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), + source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] +</example> +</summary> +</builder> + +<cvar name="QTDIR"> +<summary> +The qt tool tries to take this from os.environ. +It also initializes all QT_* +construction variables listed below. +(Note that all paths are constructed +with python's os.path.join() method, +but are listed here with the '/' separator +for easier reading.) +In addition, the construction environment +variables &cv-CPPPATH;, &cv-LIBPATH; and &cv-LIBS; may be modified +and the variables +PROGEMITTER, SHLIBEMITTER and LIBEMITTER +are modified. Because the build-performance is affected when using this tool, +you have to explicitly specify it at Environment creation: + +<example> +Environment(tools=['default','qt']) +</example> + +The qt tool supports the following operations: + +.B Automatic moc file generation from header files. +You do not have to specify moc files explicitly, the tool does it for you. +However, there are a few preconditions to do so: Your header file must have +the same filebase as your implementation file and must stay in the same +directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You +can turn off automatic moc file generation by setting QT_AUTOSCAN to 0. +See also the corresponding builder method +.B Moc() + +.B Automatic moc file generation from cxx files. +As stated in the qt documentation, include the moc file at the end of +the cxx file. Note that you have to include the file, which is generated +by the transformation ${QT_MOCCXXPREFIX}basename${QT_MOCCXXSUFFIX}, by default +basename.moc. A warning is generated after building the moc file, if you +do not include the correct file. If you are using BuildDir, you may +need to specify duplicate=1. You can turn off automatic moc file generation +by setting QT_AUTOSCAN to 0. See also the corresponding builder method +.B Moc() + +.B Automatic handling of .ui files. +The implementation files generated from .ui files are handled much the same +as yacc or lex files. Each .ui file given as a source of Program, Library or +SharedLibrary will generate three files, the declaration file, the +implementation file and a moc file. Because there are also generated headers, +you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method +.B Uic() +</summary> +</cvar> + +<cvar name="QT_AUTOSCAN"> +<summary> +Turn off scanning for mocable files. Use the Moc Builder to explicitely +specify files to run moc on. +</summary> +</cvar> + +<cvar name="QT_BINPATH"> +<summary> +The path where the qt binaries are installed. +The default value is '&cv-QTDIR;/bin'. +</summary> +</cvar> + +<cvar name="QT_CPPPATH"> +<summary> +The path where the qt header files are installed. +The default value is '&cv-QTDIR;/include'. +Note: If you set this variable to None, the tool won't change the &cv-CPPPATH; +construction variable. +</summary> +</cvar> + +<cvar name="QT_DEBUG"> +<summary> +Prints lots of debugging information while scanning for moc files. +</summary> +</cvar> + +<cvar name="QT_LIB"> +<summary> +Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set +this variable to None, the tool won't change the &cv-LIBS; variable. +</summary> +</cvar> + +<cvar name="QT_LIBPATH"> +<summary> +The path where the qt libraries are installed. +The default value is '&cv-QTDIR;/lib'. +Note: If you set this variable to None, the tool won't change the &cv-LIBPATH; +construction variable. +</summary> +</cvar> + +<cvar name="QT_MOC"> +<summary> +Default value is '&cv-QT_BINPATH;/bin/moc'. +</summary> +</cvar> + +<cvar name="QT_MOCCXXPREFIX"> +<summary> +Default value is ''. Prefix for moc output files, when source is a cxx file. +</summary> +</cvar> + +<cvar name="QT_MOCCXXSUFFIX"> +<summary> +Default value is '.moc'. Suffix for moc output files, when source is a cxx +file. +</summary> +</cvar> + +<cvar name="QT_MOCFROMCPPFLAGS"> +<summary> +Default value is '-i'. These flags are passed to moc, when moccing a +cpp file. +</summary> +</cvar> + +<cvar name="QT_MOCFROMCXXCOM"> +<summary> +Command to generate a moc file from a cpp file. +</summary> +</cvar> + +<cvar name="QT_MOCFROMCXXCOMSTR"> +<summary> +The string displayed when generating a moc file from a cpp file. +If this is not set, then &cv-QT_MOCFROMCXXCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="QT_MOCFROMHCOM"> +<summary> +Command to generate a moc file from a header. +</summary> +</cvar> + +<cvar name="QT_MOCFROMHCOMSTR"> +<summary> +The string displayed when generating a moc file from a cpp file. +If this is not set, then &cv-QT_MOCFROMHCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="QT_MOCFROMHFLAGS"> +<summary> +Default value is ''. These flags are passed to moc, when moccing a header +file. +</summary> +</cvar> + +<cvar name="QT_MOCHPREFIX"> +<summary> +Default value is 'moc_'. Prefix for moc output files, when source is a header. +</summary> +</cvar> + +<cvar name="QT_MOCHSUFFIX"> +<summary> +Default value is '&cv-CXXFILESUFFIX;'. Suffix for moc output files, when source is +a header. +</summary> +</cvar> + +<cvar name="QT_UIC"> +<summary> +Default value is '&cv-QT_BINPATH;/uic'. +</summary> +</cvar> + +<cvar name="QT_UICCOM"> +<summary> +Command to generate header files from .ui files. +</summary> +</cvar> + +<cvar name="QT_UICCOMSTR"> +<summary> +The string displayed when generating header files from .ui files. +If this is not set, then &cv-QT_UICCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="QT_UICDECLFLAGS"> +<summary> +Default value is ''. These flags are passed to uic, when creating a a h +file from a .ui file. +</summary> +</cvar> + +<cvar name="QT_UICDECLPREFIX"> +<summary> +Default value is ''. Prefix for uic generated header files. +</summary> +</cvar> + +<cvar name="QT_UICDECLSUFFIX"> +<summary> +Default value is '.h'. Suffix for uic generated header files. +</summary> +</cvar> + +<cvar name="QT_UICIMPLFLAGS"> +<summary> +Default value is ''. These flags are passed to uic, when creating a cxx +file from a .ui file. +</summary> +</cvar> + +<cvar name="QT_UICIMPLPREFIX"> +<summary> +Default value is 'uic_'. Prefix for uic generated implementation files. +</summary> +</cvar> + +<cvar name="QT_UICIMPLSUFFIX"> +<summary> +Default value is '&cv-CXXFILESUFFIX;'. Suffix for uic generated implementation +files. +</summary> +</cvar> + +<cvar name="QT_UISUFFIX"> +<summary> +Default value is '.ui'. Suffix of designer input files. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/rmic.xml b/src/engine/SCons/Tool/rmic.xml new file mode 100644 index 0000000..390aaaf --- /dev/null +++ b/src/engine/SCons/Tool/rmic.xml @@ -0,0 +1,79 @@ +<!-- __COPYRIGHT__ --> +<tool name="rmic"> +<summary> +XXX +</summary> +</tool> + +<builder name="RMIC"> +<summary> +Builds stub and skeleton class files +for remote objects +from Java <filename>.class</filename> files. +The target is a directory +relative to which the stub +and skeleton class files will be written. +The source can be the names of <filename>.class</filename> files, +or the objects return from the +&b-Java; +builder method. + +If the construction variable +&cv-JAVACLASSDIR; +is set, either in the environment +or in the call to the +&b-RMIC; +builder method itself, +then the value of the variable +will be stripped from the +beginning of any <filename>.class </filename> +file names. + +<example> +classes = env.Java(target = 'classdir', source = 'src') +env.RMIC(target = 'outdir1', source = classes) + +env.RMIC(target = 'outdir2', + source = ['package/foo.class', 'package/bar.class']) + +env.RMIC(target = 'outdir3', + source = ['classes/foo.class', 'classes/bar.class'], + JAVACLASSDIR = 'classes') +</example> +</summary> +</builder> + +<cvar name="RMIC"> +<summary> +The Java RMI stub compiler. +</summary> +</cvar> + +<cvar name="RMICCOM"> +<summary> +The command line used to compile stub +and skeleton class files +from Java classes that contain RMI implementations. +Any options specified in the &cv-RMICFLAGS; construction variable +are included on this command line. +</summary> +</cvar> + +<cvar name="RMICCOMSTR"> +<summary> +The string displayed when compiling +stub and skeleton class files +from Java classes that contain RMI implementations. +If this is not set, then &cv-RMICCOM; (the command line) is displayed. + +<example> +env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES") +</example> +</summary> +</cvar> + +<cvar name="RMICFLAGS"> +<summary> +General options passed to the Java RMI stub compiler. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/rpcgen.xml b/src/engine/SCons/Tool/rpcgen.xml new file mode 100644 index 0000000..9fdf13e --- /dev/null +++ b/src/engine/SCons/Tool/rpcgen.xml @@ -0,0 +1,122 @@ +<!-- __COPYRIGHT__ --> +<tool name="rpcgen"> +<summary> +XXX +</summary> +</tool> + +<builder name="RPCGenClient"> +<summary> +Generates an RPC client stub (<filename>_clnt.c</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +<example> +# Builds src/rpcif_clnt.c +env.RPCGenClient('src/rpcif.x') +</example> +</summary> +</builder> + +<builder name="RPCGenHeader"> +<summary> +Generates an RPC header (<filename>.h</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +<example> +# Builds src/rpcif.h +env.RPCGenHeader('src/rpcif.x') +</example> +</summary> +</builder> + +<builder name="RPCGenService"> +<summary> +Generates an RPC server-skeleton (<filename>_svc.c</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +<example> +# Builds src/rpcif_svc.c +env.RPCGenClient('src/rpcif.x') +</example> +</summary> +</builder> + +<builder name="RPCGenXDR"> +<summary> +Generates an RPC XDR routine (<filename>_xdr.c</filename>) file +from a specified RPC (<filename>.x</filename>) source file. +Because rpcgen only builds output files +in the local directory, +the command will be executed +in the source file's directory by default. + +<example> +# Builds src/rpcif_xdr.c +env.RPCGenClient('src/rpcif.x') +</example> +</summary> +</builder> + +<cvar name="RPCGEN"> +<summary> +The RPC protocol compiler. +</summary> +</cvar> + +<cvar name="RPCGENCLIENTFLAGS"> +<summary> +Options passed to the RPC protocol compiler +when generating client side stubs. +These are in addition to any flags specified in the +&cv-RPCGENFLAGS; +construction variable. +</summary> +</cvar> + +<cvar name="RPCGENFLAGS"> +<summary> +General options passed to the RPC protocol compiler. +</summary> +</cvar> + +<cvar name="RPCGENHEADERFLAGS"> +<summary> +Options passed to the RPC protocol compiler +when generating a header file. +These are in addition to any flags specified in the +&cv-RPCGENFLAGS; +construction variable. +</summary> +</cvar> + +<cvar name="RPCGENSERVICEFLAGS"> +<summary> +Options passed to the RPC protocol compiler +when generating server side stubs. +These are in addition to any flags specified in the +&cv-RPCGENFLAGS; +construction variable. +</summary> +</cvar> + +<cvar name="RPCGENXDRFLAGS"> +<summary> +Options passed to the RPC protocol compiler +when generating XDR routines. +These are in addition to any flags specified in the +&cv-RPCGENFLAGS; +construction variable. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/sgiar.xml b/src/engine/SCons/Tool/sgiar.xml new file mode 100644 index 0000000..cd1d414 --- /dev/null +++ b/src/engine/SCons/Tool/sgiar.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="sgiar"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/sgic++.xml b/src/engine/SCons/Tool/sgic++.xml new file mode 100644 index 0000000..318ebbf --- /dev/null +++ b/src/engine/SCons/Tool/sgic++.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="sgic++"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/sgicc.xml b/src/engine/SCons/Tool/sgicc.xml new file mode 100644 index 0000000..bd752ec --- /dev/null +++ b/src/engine/SCons/Tool/sgicc.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="sgicc"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/sgilink.xml b/src/engine/SCons/Tool/sgilink.xml new file mode 100644 index 0000000..64eecb8 --- /dev/null +++ b/src/engine/SCons/Tool/sgilink.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="sgilink"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/sunar.xml b/src/engine/SCons/Tool/sunar.xml new file mode 100644 index 0000000..b94443c --- /dev/null +++ b/src/engine/SCons/Tool/sunar.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="sunar"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/sunc++.xml b/src/engine/SCons/Tool/sunc++.xml new file mode 100644 index 0000000..fcd6b0a --- /dev/null +++ b/src/engine/SCons/Tool/sunc++.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="sunc++"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/suncc.xml b/src/engine/SCons/Tool/suncc.xml new file mode 100644 index 0000000..ab86294 --- /dev/null +++ b/src/engine/SCons/Tool/suncc.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="suncc"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/sunlink.xml b/src/engine/SCons/Tool/sunlink.xml new file mode 100644 index 0000000..127651e --- /dev/null +++ b/src/engine/SCons/Tool/sunlink.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="sunlink"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/swig.xml b/src/engine/SCons/Tool/swig.xml new file mode 100644 index 0000000..5c08412 --- /dev/null +++ b/src/engine/SCons/Tool/swig.xml @@ -0,0 +1,80 @@ +<!-- __COPYRIGHT__ --> +<tool name="swig"> +<summary> +XXX +</summary> +</tool> + +<cvar name="SWIG"> +<summary> +The scripting language wrapper and interface generator. +</summary> +</cvar> + +<cvar name="SWIGCFILESUFFIX"> +<summary> +The suffix that will be used for intermediate C +source files generated by +the scripting language wrapper and interface generator. +The default value is +<filename>_wrap</filename>&cv-CFILESUFFIX;. +By default, this value is used whenever the +<option>-c++</option> +option is +<emphasis>not</emphasis> +specified as part of the +&cv-SWIGFLAGS; +construction variable. +</summary> +</cvar> + +<cvar name="SWIGCOM"> +<summary> +The command line used to call +the scripting language wrapper and interface generator. +</summary> +</cvar> + +<cvar name="SWIGCOMSTR"> +<summary> +The string displayed when calling +the scripting language wrapper and interface generator. +If this is not set, then &cv-SWIGCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="SWIGCXXFILESUFFIX"> +<summary> +The suffix that will be used for intermediate C++ +source files generated by +the scripting language wrapper and interface generator. +The default value is +<filename>_wrap</filename>&cv-CFILESUFFIX;. +By default, this value is used whenever the +<filename>-c++</filename> +option is specified as part of the +&cv-SWIGFLAGS; +construction variable. +</summary> +</cvar> + +<cvar name="SWIGFLAGS"> +<summary> +General options passed to +the scripting language wrapper and interface generator. +This is where you should set +<option>-python</option>, +<option>-perl5</option>, +<option>-tcl</option>, +or whatever other options you want to specify to SWIG. +If you set the +<option>-c++</option> +option in this variable, +&scons; +will, by default, +generate a C++ intermediate source file +with the extension that is specified as the +&cv-CXXFILESUFFIX; +variable. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/tar.xml b/src/engine/SCons/Tool/tar.xml new file mode 100644 index 0000000..c00910a --- /dev/null +++ b/src/engine/SCons/Tool/tar.xml @@ -0,0 +1,75 @@ +<!-- __COPYRIGHT__ --> +<tool name="tar"> +<summary> +XXX +</summary> +</tool> + +<builder name="Tar"> +<summary> +Builds a tar archive of the specified files +and/or directories. +Unlike most builder methods, +the +&b-Tar; +builder method may be called multiple times +for a given target; +each additional call +adds to the list of entries +that will be built into the archive. + +<example> +env.Tar('src.tar', 'src') + +# Create the stuff.tar file. +env.Tar('stuff', ['subdir1', 'subdir2']) +# Also add "another" to the stuff.tar file. +env.Tar('stuff', 'another') + +# Set TARFLAGS to create a gzip-filtered archive. +env = Environment(TARFLAGS = '-c -z') +env.Tar('foo.tar.gz', 'foo') + +# Also set the suffix to .tgz. +env = Environment(TARFLAGS = '-c -z', + TARSUFFIX = '.tgz') +env.Tar('foo') +</example> +</summary> +</builder> + +<cvar name="TAR"> +<summary> +The tar archiver. +</summary> +</cvar> + +<cvar name="TARCOM"> +<summary> +The command line used to call the tar archiver. +</summary> +</cvar> + +<cvar name="TARCOMSTR"> +<summary> +The string displayed when archiving files +using the tar archiver. +If this is not set, then &cv-TARCOM; (the command line) is displayed. + +<example> +env = Environment(TARCOMSTR = "Archiving $TARGET") +</example> +</summary> +</cvar> + +<cvar name="TARFLAGS"> +<summary> +General options passed to the tar archiver. +</summary> +</cvar> + +<cvar name="TARSUFFIX"> +<summary> +The suffix used for tar file names. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/tex.xml b/src/engine/SCons/Tool/tex.xml new file mode 100644 index 0000000..4f69041 --- /dev/null +++ b/src/engine/SCons/Tool/tex.xml @@ -0,0 +1,70 @@ +<!-- __COPYRIGHT__ --> +<tool name="tex"> +<summary> +XXX +</summary> +</tool> + +<cvar name="BIBTEX"> +<summary> +The bibliography generator for the TeX formatter and typesetter and the +LaTeX structured formatter and typesetter. +</summary> +</cvar> + +<cvar name="BIBTEXCOM"> +<summary> +The command line used to call the bibliography generator for the +TeX formatter and typesetter and the LaTeX structured formatter and +typesetter. +</summary> +</cvar> + +<cvar name="BIBTEXCOMSTR"> +<summary> +The string displayed when generating a bibliography +for TeX or LaTeX. +If this is not set, then &cv-BIBTEXCOM; (the command line) is displayed. + +<example> +env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET") +</example> +</summary> +</cvar> + +<cvar name="BIBTEXFLAGS"> +<summary> +General options passed to the bibliography generator for the TeX formatter +and typesetter and the LaTeX structured formatter and typesetter. +</summary> +</cvar> + +<cvar name="TEX"> +<summary> +The TeX formatter and typesetter. +</summary> +</cvar> + +<cvar name="TEXCOM"> +<summary> +The command line used to call the TeX formatter and typesetter. +</summary> +</cvar> + +<cvar name="TEXCOMSTR"> +<summary> +The string displayed when calling +the TeX formatter and typesetter. +If this is not set, then &cv-TEXCOM; (the command line) is displayed. + +<example> +env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES") +</example> +</summary> +</cvar> + +<cvar name="TEXFLAGS"> +<summary> +General options passed to the TeX formatter and typesetter. +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/tlib.xml b/src/engine/SCons/Tool/tlib.xml new file mode 100644 index 0000000..0351568 --- /dev/null +++ b/src/engine/SCons/Tool/tlib.xml @@ -0,0 +1,6 @@ +<!-- __COPYRIGHT__ --> +<tool name="tlib"> +<summary> +XXX +</summary> +</tool> diff --git a/src/engine/SCons/Tool/yacc.py b/src/engine/SCons/Tool/yacc.py index 2c93b7c..da88aa2 100644 --- a/src/engine/SCons/Tool/yacc.py +++ b/src/engine/SCons/Tool/yacc.py @@ -39,6 +39,8 @@ import SCons.Defaults import SCons.Tool import SCons.Util +YaccAction = SCons.Action.Action("$YACCCOM", "$YACCCOMSTR") + def _yaccEmitter(target, source, env, ysuf, hsuf): # If -d is specified on the command line, yacc will emit a .h # or .hpp file as well as a .c or .cpp file, depending on whether @@ -60,9 +62,9 @@ def generate(env): """Add Builders and construction variables for yacc to an Environment.""" c_file, cxx_file = SCons.Tool.createCFileBuilders(env) - c_file.add_action('.y', SCons.Defaults.YaccAction) - c_file.add_action('.yacc', SCons.Defaults.YaccAction) - cxx_file.add_action('.yy', SCons.Defaults.YaccAction) + c_file.add_action('.y', YaccAction) + c_file.add_action('.yacc', YaccAction) + cxx_file.add_action('.yy', YaccAction) c_file.add_emitter('.y', yEmitter) c_file.add_emitter('.yacc', yEmitter) cxx_file.add_emitter('.yy', yyEmitter) diff --git a/src/engine/SCons/Tool/yacc.xml b/src/engine/SCons/Tool/yacc.xml new file mode 100644 index 0000000..59735af --- /dev/null +++ b/src/engine/SCons/Tool/yacc.xml @@ -0,0 +1,42 @@ +<!-- __COPYRIGHT__ --> +<tool name="yacc"> +<summary> +XXX +</summary> +</tool> + +<cvar name="YACC"> +<summary> +The parser generator. +</summary> +</cvar> + +<cvar name="YACCCOM"> +<summary> +The command line used to call the parser generator +to generate a source file. +</summary> +</cvar> + +<cvar name="YACCCOMSTR"> +<summary> +The string displayed when generating a source file +using the parser generator. +If this is not set, then &cv-YACCCOM; (the command line) is displayed. + +<example> +env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES") +</example> +</summary> +</cvar> + +<cvar name="YACCFLAGS"> +<summary> +General options passed to the parser generator. +If &cv-YACCFLAGS; contains a <option>-d</option> option, +SCons assumes that the call will also create a .h file +(if the yacc source file ends in a .y suffix) +or a .hpp file +(if the yacc source file ends in a .yy suffix) +</summary> +</cvar> diff --git a/src/engine/SCons/Tool/zip.xml b/src/engine/SCons/Tool/zip.xml new file mode 100644 index 0000000..4e33c15 --- /dev/null +++ b/src/engine/SCons/Tool/zip.xml @@ -0,0 +1,83 @@ +<!-- __COPYRIGHT__ --> +<tool name="zip"> +<summary> +XXX +</summary> +</tool> + +<builder name="Zip"> +<summary> +Builds a zip archive of the specified files +and/or directories. +Unlike most builder methods, +the +&b-Zip; +builder method may be called multiple times +for a given target; +each additional call +adds to the list of entries +that will be built into the archive. + +<example> +env.Zip('src.zip', 'src') + +# Create the stuff.zip file. +env.Zip('stuff', ['subdir1', 'subdir2']) +# Also add "another" to the stuff.tar file. +env.Zip('stuff', 'another') +</example> +</summary> +</builder> + +<cvar name="ZIP"> +<summary> +The zip compression and file packaging utility. +</summary> +</cvar> + +<cvar name="ZIPCOM"> +<summary> +The command line used to call the zip utility, +or the internal Python function used to create a +zip archive. +</summary> +</cvar> + +<cvar name="ZIPCOMSTR"> +<summary> +The string displayed when archiving files +using the zip utility. +If this is not set, then &cv-ZIPCOM; +(the command line or internal Python function) is displayed. + +<example> +env = Environment(ZIPCOMSTR = "Zipping $TARGET") +</example> +</summary> +</cvar> + +<cvar name="ZIPCOMPRESSION"> +<summary> +The +<varname>compression</varname> +flag +from the Python +<filename>zipfile</filename> +module used by the internal Python function +to control whether the zip archive +is compressed or not. +The default value is +<varname>zipfile.ZIP_DEFLATED</varname>, +which creates a compressed zip archive. +This value has no effect when using Python 1.5.2 +or if the +<varname>zipfile</varname> +module is otherwise unavailable. +</summary> +</cvar> + +<cvar name="ZIPFLAGS"> +<summary> +General options passed to the zip utility. +</summary> +</cvar> diff --git a/src/test_copyrights.py b/src/test_copyrights.py index 1671dbd..44dc8fa 100644 --- a/src/test_copyrights.py +++ b/src/test_copyrights.py @@ -93,6 +93,7 @@ src_remove_list = [ 'gentoo', 'config', 'MANIFEST.in', + 'MANIFEST-xml.in', ] # XXX Remove '*-stamp' when we get rid of those. |
