diff options
Diffstat (limited to 'doc')
85 files changed, 5540 insertions, 698 deletions
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> --> |
