From: stevenknight Date: Wed, 13 Nov 2002 06:44:03 +0000 (+0000) Subject: Document Repository and other methods, plus some added documentation to SCons.Node... X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=46fd3ad39b8bb6d5e465d98f0ed797e82c744de0;p=scons.git Document Repository and other methods, plus some added documentation to SCons.Node and SCons.Node.FS. git-svn-id: http://scons.tigris.org/svn/scons/trunk@497 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 928c3612..25b046c3 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -26,12 +26,12 @@ .RS .nf .. -.\" EE - Example End - ends intend and turns line fill back on +.\" EE - Example End - ends indent and turns line fill back on .de EE .RE .fi .. -.TH SCONS 1 "July 2002" +.TH SCONS 1 "November 2002" .SH NAME scons \- a software construction tool .SH SYNOPSIS @@ -2214,9 +2214,15 @@ is usually safe, and is always more efficient than .TP .RI Default( targets ) -This specifies a list of default targets. Default targets will be built by +This specifies a list of default targets, +which will be built by .B scons if no explicit targets are given on the command line. +Multiple calls to +.BR Default () +are legal, +and add to the list of default targets. + Multiple targets should be specified as separate arguments to the .BR Default () @@ -2246,21 +2252,6 @@ can be a relative or absolute path. .I directory is an optional directory that will be used as the parent directory. -.TP -.RI FindFile( file ", " dirs ) -Search for -.I file -in the path specified by -.IR dirs . -.I file -may be a list of file names or a single file name. In addition to searching -for files that exist in the filesytem, this function also searches for -derived files that have not yet been built. - -.ES -foo = FindFile('foo', ['dir1', 'dir2']) -.EE - .TP .RI EnsurePythonVersion( major ", " minor ) Ensure that the Python version is at least @@ -2311,6 +2302,33 @@ can be a relative or absolute path. .I directory is an optional directory that will be used as the parent directory. +.TP +.RI FindFile( file ", " dirs ) +Search for +.I file +in the path specified by +.IR dirs . +.I file +may be a list of file names or a single file name. In addition to searching +for files that exist in the filesytem, this function also searches for +derived files that have not yet been built. + +.ES +foo = FindFile('foo', ['dir1', 'dir2']) +.EE +.\" +.\".TP +.\".RI GetBuildPath( XXX ) +.\"XXX +.\" +.\".TP +.\".RI GetCommandHandler( XXX ) +.\"XXX +.\" +.\".TP +.\".RI GetLaunchDir( XXX ) +.\"XXX + .TP .RI Help( text ) This specifies help text to be printed if the @@ -2344,6 +2362,21 @@ Import("env") Import("env", "variable") .EE +.TP +.RI Literal( string ) +The specified +.I string +will be preserved as-is +and not have construction variables expanded. + +.TP +.RI Local( targets ) +The specified +.I targets +will have copies made in the local tree, +even if an already up-to-date copy +exists in a repository. + .TP .RI ParseConfig( env , command ", [" function ]) Calls the specified @@ -2383,6 +2416,49 @@ platform keyword of the Environment() method. env = Environment(platform = Platform('win32')) .EE +.TP +.RI Repository( directory ) +Specifies that +.I directory +is a repository to be searched for files. +Multiple calls to +.BR Repository () +are legal, +and each one adds to the list of +repositories that will be searched. + +To +.BR scons , +a repository is a copy of the source tree, +from the top-level directory on down, +which may contain +both source files and derived files +that can be used to build targets in +the local source tree. +The canonical example would be an +official source tree maintained by an integrator. +If the repository contains derived files, +then the derived files should have been built using +.BR scons , +so that the repository contains the necessary +signature information to allow +.B scons +to figure out when it is appropriate to +use the repository copy of a derived file, +instead of building one locally. + +Note that if an up-to-date derived file +already exists in a repository, +.B scons +will +.I not +make a copy in the local directory tree. +In order to guarantee that a local copy +will be made, +use the +.B Local() +method. + .TP .RI Return( vars ) This tells @@ -3263,7 +3339,7 @@ env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') bar_in = File('bar.in') env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') -bar_in.scanner_set(kscan) +bar_in.target_scanner = kscan .EE .SS Creating a Hierarchical Build diff --git a/src/CHANGES.txt b/src/CHANGES.txt index 3d8a6b91..ebb9f72a 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -19,6 +19,10 @@ RELEASE 0.09 - - Add Repository() functionality, including the -Y option. + - Allow $$ in a string to be passed through as $. + + - Support file names with odd characters in them. + From Steven Knight: - Fix auto-deduction of target names so that deduced targets end diff --git a/src/engine/SCons/Node/FS.py b/src/engine/SCons/Node/FS.py index 3b0e6ca3..3e50d103 100644 --- a/src/engine/SCons/Node/FS.py +++ b/src/engine/SCons/Node/FS.py @@ -2,6 +2,9 @@ File system nodes. +These Nodes represent the canonical external objects that people think +of when they think of building software: files and directories. + This initializes a "default_fs" Node with an FS at the current directory for its own purposes, and for use by scripts or modules looking for the canonical default. diff --git a/src/engine/SCons/Node/__init__.py b/src/engine/SCons/Node/__init__.py index 1afc79f6..20336636 100644 --- a/src/engine/SCons/Node/__init__.py +++ b/src/engine/SCons/Node/__init__.py @@ -2,6 +2,21 @@ The Node package for the SCons software construction utility. +This is, in many ways, the heart of SCons. + +A Node is where we encapsulate all of the dependency information about +any thing that SCons can build, or about any thing which SCons can use +to build some other thing. The canonical "thing," of course, is a file, +but a Node can also represent something remote (like a web page) or +something completely abstract (like an Alias). + +Each specific type of "thing" is specifically represented by a subclass +of the Node base class: Node.FS.File for files, Node.Alias for aliases, +etc. Dependency information is kept here in the base class, and +information specific to files/aliases/etc. is in the subclass. The +goal, if we've done this correctly, is that any type of "thing" should +be able to depend on any other type of "thing." + """ # diff --git a/src/engine/SCons/Script/SConscript.py b/src/engine/SCons/Script/SConscript.py index 45d05b98..41368a58 100644 --- a/src/engine/SCons/Script/SConscript.py +++ b/src/engine/SCons/Script/SConscript.py @@ -333,22 +333,22 @@ def BuildDefaultGlobals(): globals['Local'] = Local globals['Object'] = SCons.Defaults.StaticObject globals['Options'] = Options - globals['Repository'] = SCons.Node.FS.default_fs.Repository - globals['SetBuildSignatureType'] = SetBuildSignatureType - globals['SetContentSignatureType'] = SetContentSignatureType - globals['StaticLibrary'] = SCons.Defaults.StaticLibrary - globals['StaticObject'] = SCons.Defaults.StaticObject - globals['SharedLibrary'] = SCons.Defaults.SharedLibrary - globals['SharedObject'] = SCons.Defaults.SharedObject globals['ParseConfig'] = SCons.Util.ParseConfig globals['Platform'] = SCons.Platform.Platform globals['Program'] = SCons.Defaults.Program + globals['Repository'] = SCons.Node.FS.default_fs.Repository globals['Return'] = Return - globals['Scanner'] = SCons.Scanner.Base globals['SConscript'] = SConscript globals['SConscriptChdir'] = SConscriptChdir + globals['Scanner'] = SCons.Scanner.Base + globals['SetBuildSignatureType'] = SetBuildSignatureType globals['SetCommandHandler'] = SCons.Action.SetCommandHandler + globals['SetContentSignatureType'] = SetContentSignatureType + globals['SharedLibrary'] = SCons.Defaults.SharedLibrary + globals['SharedObject'] = SCons.Defaults.SharedObject globals['Split'] = SCons.Util.Split + globals['StaticLibrary'] = SCons.Defaults.StaticLibrary + globals['StaticObject'] = SCons.Defaults.StaticObject globals['Tool'] = SCons.Tool.Tool globals['WhereIs'] = SCons.Util.WhereIs return globals