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/nodes.in | 431 ------------------------------------------------------ 1 file changed, 431 deletions(-) delete mode 100644 doc/user/nodes.in (limited to 'doc/user/nodes.in') diff --git a/doc/user/nodes.in b/doc/user/nodes.in deleted file mode 100644 index 1cb5a3d..0000000 --- a/doc/user/nodes.in +++ /dev/null @@ -1,431 +0,0 @@ - - - - - Internally, &SCons; represents all of the files - and directories it knows about as &Nodes;. - These internal objects - (not object files) - can be used in a variety of ways - to make your &SConscript; - files portable and easy to read. - - - -
- Builder Methods Return Lists of Target Nodes - - - - All builder methods return a list of - &Node; objects that identify the - target file or files that will be built. - These returned &Nodes; can be passed - as arguments to other builder methods. - - - - - - For example, suppose that we want to build - the two object files that make up a program with different options. - This would mean calling the &b-link-Object; - builder once for each object file, - specifying the desired options: - - - - - Object('hello.c', CCFLAGS='-DHELLO') - Object('goodbye.c', CCFLAGS='-DGOODBYE') - - - - - One way to combine these object files - into the resulting program - would be to call the &b-link-Program; - builder with the names of the object files - listed as sources: - - - - - Object('hello.c', CCFLAGS='-DHELLO') - Object('goodbye.c', CCFLAGS='-DGOODBYE') - Program(['hello.o', 'goodbye.o']) - - - - - The problem with specifying the names as strings - is that our &SConstruct; file is no longer portable - across operating systems. - It won't, for example, work on Windows - because the object files there would be - named &hello_obj; and &goodbye_obj;, - not &hello_o; and &goodbye_o;. - - - - - - A better solution is to assign the lists of targets - returned by the calls to the &b-Object; builder to variables, - which we can then concatenate in our - call to the &b-Program; builder: - - - - - - hello_list = Object('hello.c', CCFLAGS='-DHELLO') - goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE') - Program(hello_list + goodbye_list) - - - int main() { printf("Hello, world!\n"); } - - - int main() { printf("Goodbye, world!\n"); } - - - - - - This makes our &SConstruct; file portable again, - the build output on Linux looking like: - - - - - scons -Q - - - - - And on Windows: - - - - - scons -Q - - - - - We'll see examples of using the list of nodes - returned by builder methods throughout - the rest of this guide. - - - -
- -
- Explicitly Creating File and Directory Nodes - - - - It's worth mentioning here that - &SCons; maintains a clear distinction - between Nodes that represent files - and Nodes that represent directories. - &SCons; supports &File; and &Dir; - functions that, respectively, - return a file or directory Node: - - - - - - hello_c = File('hello.c') - Program(hello_c) - - classes = Dir('classes') - Java(classes, 'src') - - - - - - Normally, you don't need to call - &File; or &Dir; directly, - because calling a builder method automatically - treats strings as the names of files or directories, - and translates them into - the Node objects for you. - The &File; and &Dir; functions can come in handy - in situations where you need to explicitly - instruct &SCons; about the type of Node being - passed to a builder or other function, - or unambiguously refer to a specific - file in a directory tree. - - - - - - - There are also times when you may need to - refer to an entry in a file system - without knowing in advance - whether it's a file or a directory. - For those situations, - &SCons; also supports an &Entry; function, - which returns a Node - that can represent either a file or a directory. - - - - - xyzzy = Entry('xyzzy') - - - - - The returned xyzzy Node - will be turned into a file or directory Node - the first time it is used by a builder method - or other function that - requires one vs. the other. - - - -
- -
- Printing &Node; File Names - - - - One of the most common things you can do - with a Node is use it to print the - file name that the node represents. - Keep in mind, though, that because the object - returned by a builder call - is a list of Nodes, - you must use Python subscripts - to fetch individual Nodes from the list. - For example, the following &SConstruct; file: - - - - - - object_list = Object('hello.c') - program_list = Program(object_list) - print "The object file is:", object_list[0] - print "The program file is:", program_list[0] - - - int main() { printf("Hello, world!\n"); } - - - - - - Would print the following file names on a POSIX system: - - - - - scons -Q - - - - - And the following file names on a Windows system: - - - - - scons -Q - - - - - Note that in the above example, - the object_list[0] - extracts an actual Node object - from the list, - and the Python print statement - converts the object to a string for printing. - - - -
- -
- Using a &Node;'s File Name as a String - - - - Printing a &Node;'s name - as described in the previous section - works because the string representation of a &Node; object - is the name of the file. - If you want to do something other than - print the name of the file, - you can fetch it by using the builtin Python - &str; function. - For example, if you want to use the Python - os.path.exists - to figure out whether a file - exists while the &SConstruct; file - is being read and executed, - you can fetch the string as follows: - - - - - - import os.path - program_list = Program('hello.c') - program_name = str(program_list[0]) - if not os.path.exists(program_name): - print program_name, "does not exist!" - - - int main() { printf("Hello, world!\n"); } - - - - - - Which executes as follows on a POSIX system: - - - - - scons -Q - - -
- -
- &GetBuildPath;: Getting the Path From a &Node; or String - - - - env.GetBuildPath(file_or_list) - returns the path of a &Node; or a string representing a - path. It can also take a list of &Node;s and/or strings, and - returns the list of paths. If passed a single &Node;, the result - is the same as calling str(node) (see above). - The string(s) can have embedded construction variables, which are - expanded as usual, using the calling environment's set of - variables. The paths can be files or directories, and do not have - to exist. - - - - - - env=Environment(VAR="value") - n=File("foo.c") - print env.GetBuildPath([n, "sub/dir/$VAR"]) - - - - - - Would print the following file names: - - - - - scons -Q - - - - - There is also a function version of &GetBuildPath; which can - be called without an &Environment;; that uses the default SCons - &Environment; to do substitution on any string arguments. - - - -
- - - - -- cgit v1.2.3