From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- doc/user/builders-built-in.in | 950 ------------------------------------------ 1 file changed, 950 deletions(-) delete mode 100644 doc/user/builders-built-in.in (limited to 'doc/user/builders-built-in.in') diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in deleted file mode 100644 index f248d76..0000000 --- a/doc/user/builders-built-in.in +++ /dev/null @@ -1,950 +0,0 @@ - - - - - &SCons; provides the ability to build a lot of different - types of files right "out of the box." - So far, we've been using &SCons;' ability to build - programs, objects and libraries to - illustrate much of the underlying functionality of &SCons; - This section will describe all of the different - types of files that you can build with &SCons;, - and the built-in &Builder; objects used to build them. - By default, all of the &Builder; objects in this section - can be built either with or without an explicit - construction environment. - - - -
- Programs: 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, - and the ⌖ argument is the - name of the executable program name to be created. - For example: - - - - - Program('prog', 'file1.o') - - - - - Will create the &prog; - executable on a POSIX system, - the &prog_exe; executable on a Windows system. - - - - - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-PROGPREFIX; - and - &cv-link-PROGSUFFIX; - construction variables - will be appended appropriately. - For example: - - - - - env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx') - env.Program('prog', ['file1.o', 'file2.o']) - - - - - Will create a program named - myprog.xxx - regardless of the system on which it is run. - - - - - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the target - program created. - For example: - - - - - Program(['hello.c', 'goodbye.c']) - - - - - Will create the &hello; - executable on a POSIX system, - the &hello_exe; executable on a Windows system. - - - - - - Two construction variables control what libraries - will be linked with the resulting program. - The &cv-link-LIBS; variable is a list of the names of - libraries that will be linked into any programs, - 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 - options for the running system. - For example: - - - - - - env = Environment(LIBS = ['foo1', 'foo2'], - LIBPATH = ['/usr/dir1', 'dir2']) - env.Program(['hello.c', 'goodbye.c']) - - - int hello() { printf("Hello, world!\n"); } - - - int goodbye() { printf("Goodbye, world!\n"); } - - - - - - Will execute as follows on a POSIX system: - - - - - scons -Q - - - - - And execute as follows on a Windows system: - - - - - scons -Q - - - - - The &cv-LIBS; construction variable - is turned into command line options - by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; - construction variables to the beginning and end, - respectively, of each specified library. - - - - - - The &cv-LIBPATH; construction variable - is turned into command line options - by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX; - construction variables to the beginning and end, - respectively, of each specified library. - - - - - - Other relevant construction variables - include those used by the &b-link-Object; - builders to affect how the - source files specified as input to the &t-Program; - builders are turned into object files; - see the next section. - - - - - - The command line used to control how a program is linked - is specified by the &cv-link-LINKCOM; construction variable. - By default, it uses the - &cv-link-LINK; construction variable - and the &cv-link-LINKFLAGS; construction variable. - - - -
- -
- Object-File Builders - - - - &SCons; provides separate Builder objects - to create static and shared object files. - The distinction becomes especially important when - archiving object files into different types of libraries. - - - -
- 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. - The &source; argument is a single source-code file, - and the ⌖ argument is the - name of the static object file to be created. - For example: - - - - - StaticObject('file', 'file.c') - - - - - Will create the &file_o; - object file on a POSIX system, - the &file_obj; executable on a Windows system. - - - - - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-OBJPREFIX; - and - &cv-link-OBJSUFFIX; - construction variables - will be appended appropriately. - For example: - - - - - env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx') - env.StaticObject('file', 'file.c') - - - - - Will create an object file named - myfile.xxx - regardless of the system on which it is run. - - - - - - If you omit the ⌖, - the base of the first input - file name specified - beomces the base of the name - of the static object file to be created. - For example: - - - - - StaticObject('file.c') - - - - - Will create the &file_o; - executable on a POSIX system, - the &file_obj; executable on a Windows system. - - - -
- -
- 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. - The &source; argument is a single source-code file, - and the ⌖ argument is the - name of the shared object file to be created. - For example: - - - - - SharedObject('file', 'file.c') - - - - - Will create the &file_o; - object file on a POSIX system, - the &file_obj; executable on a Windows system. - - - - - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-SHOBJPREFIX; - and - &cv-link-SHOBJSUFFIX; - construction variables - will be appended appropriately. - For example: - - - - - env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx') - env.SharedObject('file', 'file.c') - - - - - Will create an object file named - myfile.xxx - regardless of the system on which it is run. - - - - - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the name - of the shared object file to be created. - For example: - - - - - SharedObject('file.c') - - - - - Will create the &file_o; - executable on a POSIX system, - the &file_obj; executable on a Windows system. - - - -
- -
- The &Object; Builder - - - - The &b-link-Object; Builder is a synonym for &b-link-StaticObject; - and is completely equivalent. - - - -
- -
- -
- Library Builders - - - - &SCons; provides separate Builder objects - to create static and shared libraries. - - - -
- 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 - source-code files or object files, - and the ⌖ argument is the - name of the static library to be created. - For example: - - - - - StaticLibrary('foo', ['file1.c', 'file2.c']) - - - - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-LIBPREFIX; - and - &cv-link-LIBSUFFIX; - construction variables - will be appended appropriately. - For example: - - - - - env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx') - env.StaticLibrary('lib', ['file1.o', 'file2.o']) - - - - - Will create an object file named - mylib.xxx - regardless of the system on which it is run. - - - - - StaticLibrary('foo', ['file1.c', 'file2.c']) - - - - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the name of the static object file to be created. - For example: - - - - - StaticLibrary(['file.c', 'another.c']) - - - - - Will create the &libfile_a; - library on a POSIX system, - the &file_lib; library on a Windows system. - - - -
- -
- 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 - source-code files or object files, - and the ⌖ argument is the - name of the shared library to be created. - For example: - - - - - SharedLibrary('foo', ['file1.c', 'file2.c']) - - - - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-SHLIBPREFIX; - and - &cv-link-SHLIBSUFFIX; - construction variables - will be appended appropriately. - For example: - - - - - env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx') - env.SharedLibrary('shared', ['file1.o', 'file2.o']) - - - - - Will create an object file named - myshared.xxx - regardless of the system on which it is run. - - - - - SharedLibrary('foo', ['file1.c', 'file2.c']) - - - - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the name of the shared library to be created. - For example: - - - - - SharedLibrary(['file.c', 'another.c']) - - - - - Will create the &libfile_so; - library on a POSIX system, - the &file_dll; library on a Windows system. - - - -
- -
- The &Library; Builder - - - - The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; - and is completely equivalent. - - - -
- -
- -
- Pre-Compiled Headers: the &PCH; Builder - - - - XXX PCH() - - - -
- -
- Microsoft Visual C++ Resource Files: the &RES; Builder - - - - XXX RES() - - - -
- -
- Source Files - - - - By default - &SCons; supports two Builder objects - that know how to build source files - from other input files. - These are typically invoked "internally" - to turn files that need preprocessing into other source files. - - - -
- The &CFile; Builder - - - - XXX CFile() - - - - - XXX CFile() programlisting - - - - XXX CFile() screen - - -
- -
- The &CXXFile; Builder - - - - XXX CXXFILE() - - - - - XXX CXXFILE() programlisting - - - - XXX CXXFILE() screen - - -
- -
- -
- Documents - - - - &SCons; provides a number of Builder objects - for creating different types of documents. - - - -
- The &DVI; Builder - - - - XXX DVI() para - - - - - XXX DVI() programlisting - - - - XXX DVI() screen - - -
- -
- The &PDF; Builder - - - - XXX PDF() para - - - -
- -
- The &PostScript; Builder - - - - XXX PostScript() para - - - - - XXX PostScript() programlisting - - - - XXX PostScript() screen - - -
- -
- -
- Archives - - - - &SCons; provides Builder objects - for creating two different types of archive files. - - - -
- The &Tar; Builder - - - - The &b-link-Tar; Builder object uses the &tar; - utility to create archives of files - and/or directory trees: - - - - - - env = Environment() - env.Tar('out1.tar', ['file1', 'file2']) - env.Tar('out2', 'directory') - - - file1 - - - file2 - - - directory/file3 - - - - - scons -Q . - - - - - One common requirement when creating a &tar; archive - is to create a compressed archive using the - option. - This is easily handled by specifying - the value of the &cv-link-TARFLAGS; variable - when you create the construction environment. - Note, however, that the used to - to instruct &tar; to create the archive - is part of the default value of &cv-TARFLAGS;, - so you need to set it both options: - - - - - - env = Environment(TARFLAGS = '-c -z') - env.Tar('out.tar.gz', 'directory') - - - directory/file - - - - - scons -Q . - - - - - you may also wish to set the value of the - &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: - - - - - - env = Environment(TARFLAGS = '-c -z', - TARSUFFIX = '.tgz') - env.Tar('out', 'directory') - - - directory/file - - - - - scons -Q . - - -
- -
- The &Zip; Builder - - - - 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 - that &SCons; will use. - In this case, given the following - &SConstruct; file: - - - - - - env = Environment() - env.Zip('out', ['file1', 'file2']) - - - file1 - - - file2 - - - - - - Your output will reflect the fact - that an internal Python function - is being used to create the output ZIP archive: - - - - - scons -Q . - - -
- -
- -
- Java - - - - &SCons; provides Builder objects - for creating various types of Java output files. - - - -
- Building Class Files: the &Java; Builder - - - - The &b-link-Java; builder takes one or more input - .java files - and turns them into one or more - .class files - Unlike most builders, however, - the &Java; builder takes - target and source directories, - not files, as input. - - - - - env = Environment() - env.Java(target = 'classes', source = 'src') - - - - - The &Java; builder will then - search the specified source directory - tree for all .java files, - and pass any out-of-date - - - - - XXX Java() screen - - -
- -
- The &Jar; Builder - - - - XXX The &Jar; builder object - - - - - env = Environment() - env.Java(target = 'classes', source = 'src') - env.Jar(target = '', source = 'classes') - - - - XXX Jar() screen - - -
- -
- Building C header and stub files: the &JavaH; Builder - - - - XXX JavaH() para - - - - - XXX JavaH() programlisting - - - - XXX JavaH() screen - - -
- -
- Building RMI stub and skeleton class files: the &RMIC; Builder - - - - XXX RMIC() para - - - - - XXX RMIC() programlisting - - - - XXX RMIC() screen - - -
- -
-- cgit v1.2.3