diff options
Diffstat (limited to 'doc/man/scons.1')
| -rw-r--r-- | doc/man/scons.1 | 204 |
1 files changed, 154 insertions, 50 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 490975d..95696c9 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -891,6 +891,7 @@ variable after the Environment is constructed will not cause the tools to be redetected. SCons supports the following tool specifications out of the box: + .ES 386asm aixc++ @@ -1089,6 +1090,7 @@ provides the following builders: Builds a static object file from one or more C, C++, or Fortran source files. Source files must have one of the following extensions: + .ES .asm assembly language file .ASM assembly language file @@ -1424,6 +1426,7 @@ env.M4(target = 'foo.c', source = 'foo.c.m4') .IP Jar Builds a Java archive (.jar) file from a source tree of .class files. + .ES env.Jar(target = 'foo.jar', source = 'classes') .EE @@ -1678,6 +1681,32 @@ method of a construction environment (see below). .SS Other Construction Environment Methods Additional construction environment methods include: +.TP +.RI AddPostAction( target ", " action ) +Arranges for the specified +.I action +to be performed +after the specified +.I target +has been built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). + +.TP +.RI AddPreAction( target ", " action ) +Arranges for the specified +.I action +to be performed +before the specified +.I target +is built. +The specified action(s) may be +an Action object, or anything that +can be converted into an Action object +(see below). + .TP .RI Alias( alias ", " targets ) Creates a phony target that @@ -1697,6 +1726,24 @@ env.Alias('install', ['/usr/local/man']) .EE .TP +.RI AlwaysBuild( target ", ...)" +Marks each given +.I target +so that it is always assumed to be out of date, +and will always be rebuilt if needed. +Note, however, that +.BR AlwaysBuild () +does not add its target(s) to the default target list, +so the targets will only be built +if they are specified on the command line, +or are a dependent of a target specified on the command line--but +they will +.I always +be built if so specified. +Multiple targets can be passed in to a single call to +.BR AlwaysBuild (). + +.TP .RI Append( key = val ", [...])" Appends the specified keyword arguments to the end of construction variables in the environment. @@ -1717,36 +1764,6 @@ env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) .EE .TP -.RI PrependENVPath( name ", " newpath ", [" envname ", " sep ]) -This appends new path elements to the given path in the -specified external environment -.RB ( ENV -by default). -This will only add -any particular path once (leaving the first one it encounters and -ignoring the rest, to preserve path order), -and to help assure this, -will normalize all paths (using -.B os.path.normpath -and -.BR os.path.normcase ). -This can also handle the -case where the given old path variable is a list instead of a -string, in which case a list will be returned instead of a string. -Example: - -.ES -print 'before:',env['ENV']['INCLUDE'] -include_path = '/foo/bar:/foo' -env.PrependENVPath('INCLUDE', include_path) -print 'after:',env['ENV']['INCLUDE'] - -yields: -before: /biz:/foo -after: /foo/bar:/foo:/biz -.EE - -.TP .RI AppendENVPath( name ", " newpath ", [" envname ", " sep ]) This appends new path elements to the given path in the specified external environment @@ -1786,6 +1803,7 @@ The returned Builder is intended to be passed to the .B SourceCode function. + .ES env.SourceCode('.', env.BitKeeper()) .EE @@ -1834,7 +1852,7 @@ for the keywords. env2 = env.Copy() env3 = env.Copy(CCFLAGS = '-g') .EE - +.IP Additionally, a list of tools may be specified, as in the Environment constructor: @@ -1843,7 +1861,6 @@ def MyTool(env): env['FOO'] = 'bar' env4 = env.Copy(tools = ['msvc', MyTool]) .EE - .TP .RI CVS( repository ", " module ) A factory function that @@ -1883,6 +1900,44 @@ env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) .EE +.TP +.RI Default( targets ) +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 () +method, or as a list. +.BR Default () +will also accept the Node returned by any +of a construction environment's +builder methods. +Examples: + +.ES +env.Default('foo', 'bar', 'baz') +env.Default(['a', 'b', 'c']) +hello = env.Program('hello', 'hello.c') +env.Default(hello) +.EE +.IP +An argument to +.BR Default () +of +.B None +will clear all default targets. +Later calls to +.BR Default () +will add to the (now empty) default-target list +like normal. + .TP .RI Depends( target ", " dependency ) Specifies an explicit dependency; @@ -1912,6 +1967,21 @@ cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') .EE .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 = env.FindFile('foo', ['dir1', 'dir2']) +.EE + +.TP .RI Ignore( target ", " dependency ) The specified dependency file(s) will be ignored when deciding if @@ -1947,6 +2017,15 @@ env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], .EE .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. +Returns a list of the target Node or Nodes. + +.TP Perforce() A factory function that returns a Builder object @@ -1956,6 +2035,7 @@ The returned Builder is intended to be passed to the .B SourceCode function: + .ES env.SourceCode('.', env.Perforce()) .EE @@ -1978,24 +2058,6 @@ and USERNAME. .TP -.RI AlwaysBuild( target ", ...)" -Marks each given -.I target -so that it is always assumed to be out of date, -and will always be rebuilt if needed. -Note, however, that -.BR AlwaysBuild () -does not add its target(s) to the default target list, -so the targets will only be built -if they are specified on the command line, -or are a dependent of a target specified on the command line--but -they will -.I always -be built if so specified. -Multiple targets can be passed in to a single call to -.BR AlwaysBuild (). - -.TP .RI Precious( target ", ...)" Marks each given .I target @@ -2026,6 +2088,36 @@ env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) .EE .TP +.RI PrependENVPath( name ", " newpath ", [" envname ", " sep ]) +This appends new path elements to the given path in the +specified external environment +.RB ( ENV +by default). +This will only add +any particular path once (leaving the first one it encounters and +ignoring the rest, to preserve path order), +and to help assure this, +will normalize all paths (using +.B os.path.normpath +and +.BR os.path.normcase ). +This can also handle the +case where the given old path variable is a list instead of a +string, in which case a list will be returned instead of a string. +Example: + +.ES +print 'before:',env['ENV']['INCLUDE'] +include_path = '/foo/bar:/foo' +env.PrependENVPath('INCLUDE', include_path) +print 'after:',env['ENV']['INCLUDE'] + +yields: +before: /biz:/foo +after: /foo/bar:/foo:/biz +.EE + +.TP RCS() A factory function that returns a Builder object @@ -2035,6 +2127,7 @@ The returned Builder is intended to be passed to the .B SourceCode function: + .ES env.SourceCode('.', env.RCS()) .EE @@ -2072,6 +2165,7 @@ The returned Builder is intended to be passed to the .B SourceCode function: + .ES env.SourceCode('.', env.SCCS()) .EE @@ -2157,6 +2251,7 @@ source code management files on disk. You can avoid these extra searches and speed up your build a little by disabling these searches as follows: + .ES env.SourceCode('.', None) .EE @@ -2175,6 +2270,7 @@ functions that return appropriate Builders for various popular source code management systems. Canonical examples of invocation include: + .ES env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) @@ -2303,6 +2399,7 @@ Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program are available by default. If you initialize this variable when an Environment is created: + .ES env = Environment(BUILDERS = {'NewBuilder' : foo}) .EE @@ -2310,12 +2407,14 @@ env = Environment(BUILDERS = {'NewBuilder' : foo}) the default Builders will no longer be available. To use a new Builder object in addition to the default Builders, add your new Builder object like this: + .ES env = Environment() env.Append(BUILDERS = {'NewBuilder' : foo}) .EE .IP or this: + .ES env = Environment() env['BUILDERS]['NewBuilder'] = foo @@ -3235,6 +3334,7 @@ In addition, the construction environment variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER are modified. Because the build-performance is affected when using this tool, you have to explicitly specify it at Environment creation: + .ES Environment(tools=['default','qt']). .EE @@ -4614,6 +4714,7 @@ The specified will have copies made in the local tree, even if an already up-to-date copy exists in a repository. +Returns a list of the target Node or Nodes. .TP .RI ParseConfig( env ", " command ", [" function ]) @@ -4906,6 +5007,7 @@ to the directory in which each subsidiary SConscript file lives. This behavior may be disabled by specifying: + .ES SConscriptChdir(0) .EE @@ -5322,6 +5424,7 @@ the command line. This allows white space to be enclosed in an argument by defining a command in a list within a list: + .ES Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) .EE @@ -5347,6 +5450,7 @@ more than one target file or source file. The actual target and source file name(s) may be retrieved from their Node objects via the built-in Python str() function: + .ES target_file_name = str(target) source_file_names = map(lambda x: str(x), source) |