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/less-simple.in | 623 ------------------------------------------------ 1 file changed, 623 deletions(-) delete mode 100644 doc/user/less-simple.in (limited to 'doc/user/less-simple.in') diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in deleted file mode 100644 index f3c251f..0000000 --- a/doc/user/less-simple.in +++ /dev/null @@ -1,623 +0,0 @@ - - - - - In this chapter, - you will see several examples of - very simple build configurations using &SCons;, - which will demonstrate how easy - it is to use &SCons; to - build programs from several different programming languages - on different types of systems. - - - -
- Specifying the Name of the Target (Output) File - - - - 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 - executable program from the &hello_c; source file - will build an executable program named &hello; on POSIX systems, - and an executable program named &hello_exe; on Windows systems: - - - - - Program('hello.c') - - - - - If you want to build a program with - a different name than the base of the source file name, - you simply put the target file name - to the left of the source file name: - - - - - - Program('new_hello', 'hello.c') - - - int main() { printf("Hello, world!\n"); } - - - - - - (&SCons; requires the target file name first, - followed by the source file name, - so that the order mimics that of an - assignment statement in most programming languages, - including Python: - "program = source files".) - - - - - - Now &SCons; will build an executable program - named &new_hello; when run on a POSIX system: - - - - - scons -Q - - - - - And &SCons; will build an executable program - named &new_hello_exe; when run on a Windows system: - - - - - scons -Q - - -
- -
- Compiling Multiple Source Files - - - - You've just seen how to configure &SCons; - to compile a program from a single source file. - It's more common, of course, - that you'll need to build a program from - many input source files, not just one. - To do this, you need to put the - source files in a Python list - (enclosed in square brackets), - like so: - - - - - - Program(['prog.c', 'file1.c', 'file2.c']) - - - int main() { printf("prog.c\n"); } - - - void file1() { printf("file1.c\n"); } - - - void file2() { printf("file2.c\n"); } - - - - - - A build of the above example would look like: - - - - - scons -Q - - - - - Notice that &SCons; - deduces the output program name - from the first source file specified - in the list--that is, - because the first source file was &prog_c;, - &SCons; will name the resulting program &prog; - (or &prog_exe; on a Windows system). - If you want to specify a different program name, - then (as we've seen in the previous section) - you slide the list of source files - over to the right - to make room for the output program file name. - (&SCons; puts the output file name to the left - of the source file names - so that the order mimics that of an - assignment statement: "program = source files".) - This makes our example: - - - - - - Program('program', ['prog.c', 'file1.c', 'file2.c']) - - - int main() { printf("prog.c\n"); } - - - void file1() { printf("file1.c\n"); } - - - void file2() { printf("file2.c\n"); } - - - - - - On Linux, a build of this example would look like: - - - - - scons -Q - - - - - Or on Windows: - - - - - scons -Q - - -
- -
- Making a list of files with &Glob; - - - - You can also use the &Glob; function to find all files matching a - certain template, using the standard shell pattern matching - characters *, ? - and [abc] to match any of - a, b or c. - [!abc] is also supported, - to match any character except - a, b or c. - This makes many multi-source-file builds quite easy: - - - - - Program('program', Glob('*.c')) - - - - - The SCons man page has more details on using &Glob; - with variant directories - (see , below) - and repositories - (see , below), - and returning strings rather than Nodes. - - - -
- -
- Specifying Single Files Vs. Lists of Files - - - - We've now shown you two ways to specify - the source for a program, - one with a list of files: - - - - - Program('hello', ['file1.c', 'file2.c']) - - - - - And one with a single file: - - - - - Program('hello', 'hello.c') - - - - - You could actually put a single file name in a list, too, - which you might prefer just for the sake of consistency: - - - - - Program('hello', ['hello.c']) - - - - - &SCons; functions will accept a single file name in either form. - In fact, internally, &SCons; treats all input as lists of files, - but allows you to omit the square brackets - to cut down a little on the typing - when there's only a single file name. - - - - - - - - Although &SCons; functions - are forgiving about whether or not you - use a string vs. a list for a single file name, - Python itself is more strict about - treating lists and strings differently. - So where &SCons; allows either - a string or list: - - - - - # The following two calls both work correctly: - Program('program1', 'program1.c') - Program('program2', ['program2.c']) - - - - - Trying to do "Python things" that mix strings and - lists will cause errors or lead to incorrect results: - - - - - common_sources = ['file1.c', 'file2.c'] - - # THE FOLLOWING IS INCORRECT AND GENERATES A PYTHON ERROR - # BECAUSE IT TRIES TO ADD A STRING TO A LIST: - Program('program1', common_sources + 'program1.c') - - # The following works correctly, because it's adding two - # lists together to make another list. - Program('program2', common_sources + ['program2.c']) - - - - -
- -
- Making Lists of Files Easier to Read - - - - One drawback to the use of a Python list - for source files is that - each file name must be enclosed in quotes - (either single quotes or double quotes). - This can get cumbersome and difficult to read - when the list of file names is long. - Fortunately, &SCons; and Python provide a number of ways - to make sure that - the &SConstruct; file stays easy to read. - - - - - - To make long lists of file names - easier to deal with, &SCons; provides a - &Split; function - that takes a quoted list of file names, - with the names separated by spaces or other white-space characters, - and turns it into a list of separate file names. - Using the &Split; function turns the - previous example into: - - - - - Program('program', Split('main.c file1.c file2.c')) - - - - - (If you're already familiar with Python, - you'll have realized that this is similar to the - split() method - in the Python standard string module. - Unlike the split() member function of strings, - however, the &Split; function - does not require a string as input - and will wrap up a single non-string object in a list, - or return its argument untouched if it's already a list. - This comes in handy as a way to make sure - arbitrary values can be passed to &SCons; functions - without having to check the type of the variable by hand.) - - - - - - Putting the call to the &Split; function - 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 - &b-Program; function: - - - - - src_files = Split('main.c file1.c file2.c') - Program('program', src_files) - - - - - Lastly, the &Split; function - doesn't care how much white space separates - the file names in the quoted string. - This allows you to create lists of file - names that span multiple lines, - which often makes for easier editing: - - - - - src_files = Split("""main.c - file1.c - file2.c""") - Program('program', src_files) - - - - - (Note in this example that we used - the Python "triple-quote" syntax, - which allows a string to contain - multiple lines. - The three quotes can be either - single or double quotes.) - - - -
- -
- Keyword Arguments - - - - &SCons; also allows you to identify - the output file and input source files - using Python keyword arguments. - The output file is known as the - target, - and the source file(s) are known (logically enough) as the - source. - The Python syntax for this is: - - - - - src_files = Split('main.c file1.c file2.c') - Program(target = 'program', source = src_files) - - - - - Because the keywords explicitly identify - what each argument is, - you can actually reverse the order if you prefer: - - - - - src_files = Split('main.c file1.c file2.c') - Program(source = src_files, target = 'program') - - - - - Whether or not you choose to use keyword arguments - to identify the target and source files, - and the order in which you specify them - when using keywords, - are purely personal choices; - &SCons; functions the same regardless. - - - -
- -
- Compiling Multiple Programs - - - - In order to compile multiple programs - within the same &SConstruct; file, - simply call the &Program; method - multiple times, - once for each program you need to build: - - - - - - Program('foo.c') - Program('bar', ['bar1.c', 'bar2.c']) - - - int main() { printf("foo.c\n"); } - - - int main() { printf("bar1.c\n"); } - - - void bar2() { printf("bar2.c\n"); } - - - - - - &SCons; would then build the programs as follows: - - - - - scons -Q - - - - - Notice that &SCons; does not necessarily build the - programs in the same order in which you specify - them in the &SConstruct; file. - &SCons; does, however, recognize that - the individual object files must be built - before the resulting program can be built. - We'll discuss this in greater detail in - the "Dependencies" section, below. - - - -
- -
- Sharing Source Files Between Multiple Programs - - - - It's common to re-use code by sharing source files - between multiple programs. - One way to do this is to create a library - from the common source files, - which can then be linked into resulting programs. - (Creating libraries is discussed in - , below.) - - - - - - A more straightforward, but perhaps less convenient, - way to share source files between multiple programs - is simply to include the common files - in the lists of source files for each program: - - - - - - Program(Split('foo.c common1.c common2.c')) - Program('bar', Split('bar1.c bar2.c common1.c common2.c')) - - - int main() { printf("foo.c\n"); } - - - int main() { printf("bar1.c\n"); } - - - int bar2() { printf("bar2.c\n"); } - - - void common1() { printf("common1.c\n"); } - - - void common22() { printf("common2.c\n"); } - - - - - - &SCons; recognizes that the object files for - the &common1_c; and &common2_c; source files - each need to be built only once, - even though the resulting object files are - each linked in to both of the resulting executable programs: - - - - - scons -Q - - - - - If two or more programs - share a lot of common source files, - repeating the common files in the list for each program - can be a maintenance problem when you need to change the - list of common files. - You can simplify this by creating a separate Python list - to hold the common file names, - and concatenating it with other lists - using the Python + operator: - - - - - common = ['common1.c', 'common2.c'] - foo_files = ['foo.c'] + common - bar_files = ['bar1.c', 'bar2.c'] + common - Program('foo', foo_files) - Program('bar', bar_files) - - - - - This is functionally equivalent to the previous example. - - - -
-- cgit v1.2.3