.RE
.fi
..
-.TH SCONS 1 "May 2002"
+.TH SCONS 1 "July 2002"
.SH NAME
scons \- a software construction tool
.SH SYNOPSIS
appear up-to-date is unnecessary when using
.BR scons .)
-.TP
--T
-Works exactly the same way as the
-.B -u
-option except for the way default targets are handled.
-When this option is used and no targets are specified on the command line,
-all default targets that are defined in the SConscript files in the current
-directory are built, regardless of what directory the resulant targets end
-up in.
-
.TP
-u, --up, --search-up
Walks up the directory structure until an
Build rules are specified by calling a construction
environment's builder methods.
-The arguments to the builder methods are target (a list of
-target files) and source (a list of source files).
-If a string is given
-for target or source, then
-.B scons
-.I currently
-interprets it as a space-delimited list of files.
-NOTE: Splitting a string into a list of files this
-way will be
-.I removed
-as of the next version of SCons.
-If you currently use space-delimited file lists,
-you must change them by next release.
-See the discussion of the Split() function
-for more information.
-
-The following are examples of calling the Program builder:
-
-.ES
-# The recommended ways to call a builder
-# with multiple source input files:
+The arguments to the builder methods are
+.B target
+(a list of target files)
+and
+.B source
+(a list of source files).
+
+Because long lists of file names
+can lead to a lot of quoting,
+.B scons
+supplies a
+.B Split()
+function that splits a single string
+into a list, separated on
+strings of white-space characters.
+(This is similar to the
+string.split() method
+from the standard Python library.)
+
+Like all Python arguments,
+the target and source arguments to a builder
+can be specified either with or without
+the "target" and "source" keywords.
+When the keywords are omitted,
+the target is first,
+followed by the source.
+The following are equivalent examples of calling the Program builder:
+
+.ES
env.Program('bar', ['bar.c', 'foo.c'])
env.Program('bar', Split('bar.c foo.c'))
+env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
+env.Program(target = 'bar', Split('bar.c foo.c'))
+env.Program('bar', source = string.split('bar.c foo.c'))
+.EE
-# Space-delimited lists.
-# The following will NOT work in version 0.08 of SCons!
-env.Program(target = 'bar', source = 'bar.c foo.c')
-env.Program('bar', 'bar.c foo.c')
+When the target shares the same base name
+as the source and only the suffix varies,
+and if the builder has a suffix defined for the target file type,
+then the target argument may be omitted completely,
+and
+.B scons
+will deduce the target file name from
+the source file name.
+The following examples all build the
+executable program
+.B bar
+(on POSIX systems)
+or
+.B bar.exe
+(on Windows sytems)
+from the bar.c source file:
+
+.ES
+env.Program(target = 'bar', source = 'bar.c')
+env.Program('bar', source = 'bar.c')
+env.Program(source = 'bar.c')
+env.Program('bar.c')
.EE
.B scons
.SPP assembly language file + C pre-processor
.EE
.IP
-The target object file prefix and suffix (if any) are automatically
-added. Examples:
+The target object file prefix
+(specified by the $OBJPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $OBJSUFFIX construction variable;
+\.obj on Windows systems, .o on POSIX systems)
+are automatically added to the target if not already present.
+Examples:
.ES
env.StaticObject(target = 'aaa', source = 'aaa.c')
specified above for the
.B StaticObject
builder.
-The target object file prefix and suffix (if any) are automatically
-added. Examples:
+The target object file prefix
+(specified by the $OBJPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $OBJSUFFIX construction variable;
+\.obj on Windows systems, .o on POSIX systems)
+are automatically added to the target if not already present.
+Examples:
.ES
env.SharedObject(target = 'ddd', source = 'ddd.c')
see that builder's description for
a list of legal source file suffixes
and how they are interpreted.
-The executable prefix and suffix (if any) are
-automatically added to the target. Example:
+The target executable file prefix
+(specified by the $PROGPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $PROGSUFFIX construction variable;
+by default, .exe on Windows systems, nothing on POSIX systems)
+are automatically added to the target if not already present.
+Example:
.ES
-env.Program(target = 'foo', source = 'foo.o bar.c baz.f')
+env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
.EE
.IP StaticLibrary
If any source files are given,
then they will be automatically
compiled to object files.
-The library prefix and suffix (if any)
+The static library prefix and suffix (if any)
are automatically added to the target.
+The target library file prefix
+(specified by the $LIBPREFIX construction variable;
+by default, lib on POSIX systems, nothing on Windows systems)
+and suffix
+(specified by the $LIBSUFFIX construction variable;
+by default, .lib on Windows systems, .a on POSIX systems)
+are automatically added to the target if not already present.
Example:
.ES
-env.StaticLibrary(target = 'bar', source = 'bar.c foo.o')
+env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
.EE
+.IP
Any object files listed in the
.B source
must have been built for a static library
If any source files are given,
then they will be automatically
compiled to object files.
-The library prefix and suffix (if any)
+The static library prefix and suffix (if any)
are automatically added to the target.
+The target library file prefix
+(specified by the $SHLIBPREFIX construction variable;
+by default, lib on POSIX systems, nothing on Windows systems)
+and suffix
+(specified by the $SHLIBSUFFIX construction variable;
+by default, .dll on Windows systems, .so on POSIX systems)
+are automatically added to the target if not already present.
Example:
.ES
-env.SharedLibrary(target = 'bar', source = 'bar.c foo.o')
+env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
.EE
.IP
On WIN32 systems, the
.ES
# builds from aaa.tex
env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
-# builds bbb.dvi
+# builds bbb.pdf from bbb.dvi
env.PDF(target = 'bbb', source = 'bbb.dvi')
.EE
.ES
# builds from aaa.tex
env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
-# builds bbb.dvi
+# builds bbb.ps from bbb.dvi
env.PostScript(target = 'bbb', source = 'bbb.dvi')
.EE
.LP
used to assemble an assembly language source file,
after first running each file through the C preprocessor.
+.IP _CPPINCFLAGS
+An automatically-generated construction variable
+containing the C preprocessor command-line options
+for specifying directories to be searched for include files.
+The value of $_CPPINCFLAGS is created
+by appending $INCPREFIX and $INCSUFFIX
+to the beginning and end
+of each directory in $CPPPATH.
+
.IP CPPPATH
The list of directories that the C preprocessor will search for include
directories. The C/C++ implicit dependency scanner will search these
env = Environment(CPPPATH=include)
.EE
+.IP
+The directory list will be added to command lines
+through the automatically-generated
+$_CPPINCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$INCPREFIX and $INCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $CPPPATH.
+Any command lines you define that need
+the CPPPATH directory list should
+include $_CPPINCFLAGS:
+
+.ES
+env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
+.EE
+
.IP CXX
The C++ compiler.
.IP F77FLAGS
General options that are passed to the Fortran compiler.
+.IP _F77INCFLAGS
+An automatically-generated construction variable
+containing the Fortran compiler command-line options
+for specifying directories to be searched for include files.
+The value of $_F77INCFLAGS is created
+by appending $INCPREFIX and $INCSUFFIX
+to the beginning and end
+of each directory in $F77PATH.
+
.IP F77PATH
The list of directories that the Fortran compiler will search for include
directories. The Fortran implicit dependency scanner will search these
env = Environment(F77PATH=include)
.EE
+.IP
+The directory list will be added to command lines
+through the automatically-generated
+$_F77INCFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$INCPREFIX and $INCSUFFIX
+construction variables
+to the beginning and end
+of each directory in $F77PATH.
+Any command lines you define that need
+the F77PATH directory list should
+include $_F77INCFLAGS:
+
+.ES
+env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
+.EE
+
.IP F77PPCOM
The command line used to compile a Fortran source file to an object file
after first running the file through the C preprocessor.
.IP INCPREFIX
The prefix used to specify an include directory on the C compiler command
line.
+This will be appended to the beginning of each directory
+in the $CPPPATH and $F77PATH construction variables
+when the $_CPPINCFLAGS and $_F77INCFLAGS
+variables are automatically generated.
.IP INCSUFFIX
The suffix used to specify an include directory on the C compiler command
line.
+This will be appended to the end of each directory
+in the $CPPPATH and $F77PATH construction variables
+when the $_CPPINCFLAGS and $_F77INCFLAGS
+variables are automatically generated.
.IP LATEX
The LaTeX structured formatter and typesetter.
The command line used to call the lexical analyzer generator
to generate a source file.
+.IP _LIBDIRFLAGS
+An automatically-generated construction variable
+containing the linker command-line options
+for specifying directories to be searched for library.
+The value of $_LIBDIRFLAGS is created
+by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
+to the beginning and end
+of each directory in $LIBPATH.
+
.IP LIBDIRPREFIX
The prefix used to specify a library directory on the linker command line.
+This will be appended to the beginning of each directory
+in the $LIBPATH construction variable
+when the $_LIBDIRFLAGS variable is automatically generated.
.IP LIBDIRSUFFIX
The suffix used to specify a library directory on the linker command line.
+This will be appended to the end of each directory
+in the $LIBPATH construction variable
+when the $_LIBDIRFLAGS variable is automatically generated.
+
+.IP _LIBFLAGS
+An automatically-generated construction variable
+containing the linker command-line options
+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.
.IP LIBLINKPREFIX
The prefix used to specify a library to link on the linker command line.
+This will be appended to the beginning of each library
+in the $LIBS construction variable
+when the $_LIBFLAGS variable is automatically generated.
.IP LIBLINKSUFFIX
The suffix used to specify a library to link on the linker command line.
+This will be appended to the end of each library
+in the $LIBS construction variable
+when the $_LIBFLAGS variable is automatically generated.
.IP LIBPATH
The list of directories that will be searched for libraries.
env = Environment(LIBPATH=libs)
.EE
+.IP
+The directory list will be added to command lines
+through the automatically-generated
+$_LIBDIRFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$LIBDIRPREFIX and $LIBDIRSUFFIX
+construction variables
+to the beginning and end
+of each directory in $LIBPATH.
+Any command lines you define that need
+the LIBPATH directory list should
+include $_LIBDIRFLAGS:
+
+.ES
+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
+.EE
+
.IP LIBPREFIX
The prefix used for (static) library file names.
any executable programs
created by this environment.
+.IP
+The library list will be added to command lines
+through the automatically-generated
+$_LIBFLAGS
+construction variable,
+which is constructed by
+appending the values of the
+$LIBLINKPREFIX and $LIBLINKSUFFIX
+construction variables
+to the beginning and end
+of each directory in $LIBS.
+Any command lines you define that need
+the LIBS library list should
+include $_LIBFLAGS:
+
+.ES
+env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
+.EE
+
.IP LIBSUFFIX
The suffix used for (static) library file names.
f6.c
""")
.EE
-.IP
-NOTE: Currently, all builders perform this white-space split
-automatically on their target and source file arguments.
-As of the next version of SCons,
-Builder objects will no longer perform this split.
-If you use white-space separated strings of file names,
-you will need to convert them to lists
-by the next release of SCons by hand,
-or by using the Split() function provided here,
-or by using a similar function such as the
-string.split() function in the Python library.
.TP
.RI Tool( string )
.SS Defining Your Own Builder Object
-You
-.I must
-specify a "name" keyword argument for the builder,
-as that becomes the Environment method name
-you use to call the builder.
-Notice also that you can leave off the target file suffix,
+Notice that you can leave off the target file suffix,
and the builder will add it automatically.
.ES
self.name = name
self.sources = []
self.builder = None
+ self.side_effect = 0
def __str__(self):
return self.name
def builder_set(self, builder):
"Source has unexpected name: %s" % tgt.sources[0].path
tgt = b1(env, target = 'tgt3', source = 'src3a src3b')
- assert len(tgt.sources) == 1
+ assert len(tgt.sources) == 1
assert tgt.sources[0].path == 'src3a src3b.c', \
"Unexpected tgt.sources[0] name: %s" % tgt.sources[0].path
action='bar',
src_builder = builder1,
src_suffix = '.foo')
- tgt = builder2(env, target='baz', source=['test.bleh.bar', 'test2.foo', 'test3.txt'])
- assert str(tgt.sources[0]) == 'test.bleh.foo', str(tgt.sources[0])
- assert str(tgt.sources[0].sources[0]) == 'test.bleh.bar', \
+ tgt = builder2(env, target='baz', source=['test.bar', 'test2.foo', 'test3.txt'])
+ assert str(tgt.sources[0]) == 'test.foo', str(tgt.sources[0])
+ assert str(tgt.sources[0].sources[0]) == 'test.bar', \
str(tgt.sources[0].sources[0])
assert str(tgt.sources[1]) == 'test2.foo', str(tgt.sources[1])
assert str(tgt.sources[2]) == 'test3.txt', str(tgt.sources[2])
assert isinstance(tgt.builder, SCons.Builder.MultiStepBuilder)
flag = 0
- tgt = builder(env, target='t5', source=[ 'test5a.foo', 'test5b.inb' ])
+ tgt = builder(env, target='t5', source='test5a.foo test5b.inb')
try:
tgt.build()
except SCons.Errors.UserError:
assert flag, "UserError should be thrown when we build targets with files of different suffixes."
flag = 0
- tgt = builder(env, target='t6', source=[ 'test6a.bar', 'test6b.ina' ])
+ tgt = builder(env, target='t6', source='test6a.bar test6b.ina')
try:
tgt.build()
except SCons.Errors.UserError:
assert flag, "UserError should be thrown when we build targets with files of different suffixes."
flag = 0
- tgt = builder(env, target='t4', source=[ 'test4a.ina', 'test4b.inb' ])
+ tgt = builder(env, target='t4', source='test4a.ina test4b.inb')
try:
tgt.build()
except SCons.Errors.UserError:
emitter="$FOO")
assert builder2 == builder2a, repr(builder2.__dict__) + "\n" + repr(builder2a.__dict__)
+ def test_no_target(self):
+ """Test deducing the target from the source."""
+
+ b = SCons.Builder.Builder(action='foo', suffix='.o')
+
+ tgt = b(env, 'aaa')
+ assert str(tgt) == 'aaa.o', str(tgt)
+ assert len(tgt.sources) == 1, map(str, tgt.sources)
+ assert str(tgt.sources[0]) == 'aaa', map(str, tgt.sources)
+
+ tgt = b(env, 'bbb.c')
+ assert str(tgt) == 'bbb.o', str(tgt)
+ assert len(tgt.sources) == 1, map(str, tgt.sources)
+ assert str(tgt.sources[0]) == 'bbb.c', map(str, tgt.sources)
+
+ tgt = b(env, 'ccc.x.c')
+ assert str(tgt) == 'ccc.x.o', str(tgt)
+ assert len(tgt.sources) == 1, map(str, tgt.sources)
+ assert str(tgt.sources[0]) == 'ccc.x.c', map(str, tgt.sources)
+
+ tgt = b(env, ['d0.c', 'd1.c'])
+ assert len(tgt) == 2, map(str, tgt)
+ assert str(tgt[0]) == 'd0.o', map(str, tgt)
+ assert str(tgt[1]) == 'd1.o', map(str, tgt)
+ assert len(tgt[0].sources) == 2, map(str, tgt[0].sources)
+ assert str(tgt[0].sources[0]) == 'd0.c', map(str, tgt[0].sources)
+ assert str(tgt[0].sources[1]) == 'd1.c', map(str, tgt[0].sources)
+ assert len(tgt[1].sources) == 2, map(str, tgt[1].sources)
+ assert str(tgt[1].sources[0]) == 'd0.c', map(str, tgt[1].sources)
+ assert str(tgt[1].sources[1]) == 'd1.c', map(str, tgt[1].sources)
+
+ tgt = b(env, source='eee')
+ assert str(tgt) == 'eee.o', str(tgt)
+ assert len(tgt.sources) == 1, map(str, tgt.sources)
+ assert str(tgt.sources[0]) == 'eee', map(str, tgt.sources)
+
+ tgt = b(env, source='fff.c')
+ assert str(tgt) == 'fff.o', str(tgt)
+ assert len(tgt.sources) == 1, map(str, tgt.sources)
+ assert str(tgt.sources[0]) == 'fff.c', map(str, tgt.sources)
+
+ tgt = b(env, source='ggg.x.c')
+ assert str(tgt) == 'ggg.x.o', str(tgt)
+ assert len(tgt.sources) == 1, map(str, tgt.sources)
+ assert str(tgt.sources[0]) == 'ggg.x.c', map(str, tgt.sources)
+
+ tgt = b(env, source=['h0.c', 'h1.c'])
+ assert len(tgt) == 2, map(str, tgt)
+ assert str(tgt[0]) == 'h0.o', map(str, tgt)
+ assert str(tgt[1]) == 'h1.o', map(str, tgt)
+ assert len(tgt[0].sources) == 2, map(str, tgt[0].sources)
+ assert str(tgt[0].sources[0]) == 'h0.c', map(str, tgt[0].sources)
+ assert str(tgt[0].sources[1]) == 'h1.c', map(str, tgt[0].sources)
+ assert len(tgt[1].sources) == 2, map(str, tgt[1].sources)
+ assert str(tgt[1].sources[0]) == 'h0.c', map(str, tgt[1].sources)
+ assert str(tgt[1].sources[1]) == 'h1.c', map(str, tgt[1].sources)
+
+
if __name__ == "__main__":
suite = unittest.makeSuite(BuilderTestCase, 'test_')
if not unittest.TextTestRunner().run(suite).wasSuccessful():
projects / scons.git / commitdiff