summaryrefslogtreecommitdiff
path: root/doc/user/nodes.in
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
committerLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
commit140d836e9cd54fb67b969fd82ef7ed19ba574d40 (patch)
tree0df3e32ee39603d43f9b90fd2f2e1f7cce4249d4 /doc/user/nodes.in
parentcb3425abe0bc2d05caf401ca24b82a25a81f009d (diff)
Imported Upstream version 2.3.1upstream/2.3.1
Diffstat (limited to 'doc/user/nodes.in')
-rw-r--r--doc/user/nodes.in431
1 files changed, 0 insertions, 431 deletions
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 @@
-<!--
-
- Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
-
- Permission is hereby granted, free of charge, to any person obtaining
- a copy of this software and associated documentation files (the
- "Software"), to deal in the Software without restriction, including
- without limitation the rights to use, copy, modify, merge, publish,
- distribute, sublicense, and/or sell copies of the Software, and to
- permit persons to whom the Software is furnished to do so, subject to
- the following conditions:
-
- The above copyright notice and this permission notice shall be included
- in all copies or substantial portions of the Software.
-
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
- KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
- WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
--->
-
- <para>
-
- Internally, &SCons; represents all of the files
- and directories it knows about as &Nodes;.
- These internal objects
- (not object <emphasis>files</emphasis>)
- can be used in a variety of ways
- to make your &SConscript;
- files portable and easy to read.
-
- </para>
-
- <section>
- <title>Builder Methods Return Lists of Target Nodes</title>
-
- <para>
-
- 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.
-
- </para>
-
- <para>
-
- 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:
-
- </para>
-
- <sconstruct>
- Object('hello.c', CCFLAGS='-DHELLO')
- Object('goodbye.c', CCFLAGS='-DGOODBYE')
- </sconstruct>
-
- <para>
-
- 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:
-
- </para>
-
- <sconstruct>
- Object('hello.c', CCFLAGS='-DHELLO')
- Object('goodbye.c', CCFLAGS='-DGOODBYE')
- Program(['hello.o', 'goodbye.o'])
- </sconstruct>
-
- <para>
-
- 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;.
-
- </para>
-
- <para>
-
- 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:
-
- </para>
-
- <scons_example name="ex1">
- <file name="SConstruct" printme="1">
- hello_list = Object('hello.c', CCFLAGS='-DHELLO')
- goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE')
- Program(hello_list + goodbye_list)
- </file>
- <file name="hello.c">
- int main() { printf("Hello, world!\n"); }
- </file>
- <file name="goodbye.c">
- int main() { printf("Goodbye, world!\n"); }
- </file>
- </scons_example>
-
- <para>
-
- This makes our &SConstruct; file portable again,
- the build output on Linux looking like:
-
- </para>
-
- <scons_output example="ex1" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- And on Windows:
-
- </para>
-
- <scons_output example="ex1" os="win32">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- We'll see examples of using the list of nodes
- returned by builder methods throughout
- the rest of this guide.
-
- </para>
-
- </section>
-
- <section>
- <title>Explicitly Creating File and Directory Nodes</title>
-
- <para>
-
- 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:
-
- </para>
-
- <scons_example name="print">
- <file name="SConstruct" printme="1">
- hello_c = File('hello.c')
- Program(hello_c)
-
- classes = Dir('classes')
- Java(classes, 'src')
- </file>
- </scons_example>
-
- <para>
-
- 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.
- <!--
- (For an example of when you might
- need to use &File; or &Dir; to
- prevent ambiguous interpretation of a string
- naming a file or directory, see
- <xref linkend="chap-hierarchy">.)
- -->
-
- </para>
-
- <para>
-
- 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.
-
- </para>
-
- <sconstruct>
- xyzzy = Entry('xyzzy')
- </sconstruct>
-
- <para>
-
- The returned <literal>xyzzy</literal> 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.
-
- </para>
-
- </section>
-
- <section>
- <title>Printing &Node; File Names</title>
-
- <para>
-
- 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 <emphasis>list</emphasis> of Nodes,
- you must use Python subscripts
- to fetch individual Nodes from the list.
- For example, the following &SConstruct; file:
-
- </para>
-
- <scons_example name="print">
- <file name="SConstruct" printme="1">
- 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]
- </file>
- <file name="hello.c">
- int main() { printf("Hello, world!\n"); }
- </file>
- </scons_example>
-
- <para>
-
- Would print the following file names on a POSIX system:
-
- </para>
-
- <scons_output example="print" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- And the following file names on a Windows system:
-
- </para>
-
- <scons_output example="print" os="win32">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- Note that in the above example,
- the <literal>object_list[0]</literal>
- extracts an actual Node <emphasis>object</emphasis>
- from the list,
- and the Python <literal>print</literal> statement
- converts the object to a string for printing.
-
- </para>
-
- </section>
-
- <section>
- <title>Using a &Node;'s File Name as a String</title>
-
- <para>
-
- 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
- <function>os.path.exists</function>
- to figure out whether a file
- exists while the &SConstruct; file
- is being read and executed,
- you can fetch the string as follows:
-
- </para>
-
- <scons_example name="exists">
- <file name="SConstruct" printme="1">
- 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!"
- </file>
- <file name="hello.c">
- int main() { printf("Hello, world!\n"); }
- </file>
- </scons_example>
-
- <para>
-
- Which executes as follows on a POSIX system:
-
- </para>
-
- <scons_output example="exists" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- </section>
-
- <section>
- <title>&GetBuildPath;: Getting the Path From a &Node; or String</title>
-
- <para>
-
- <function>env.GetBuildPath(file_or_list)</function>
- 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 <literal>str(node)</literal> (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.
-
- </para>
-
- <scons_example name="GetBuildPath">
- <file name="SConstruct" printme="1">
- env=Environment(VAR="value")
- n=File("foo.c")
- print env.GetBuildPath([n, "sub/dir/$VAR"])
- </file>
- </scons_example>
-
- <para>
-
- Would print the following file names:
-
- </para>
-
- <scons_output example="GetBuildPath" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- <para>
-
- 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.
-
- </para>
-
- </section>
-
- <!--
-
- <section>
- <title>Fetching the Contents of a &Node;</title>
-
- <para>
-
- XXX Describe using read() and readlines()
- when we add that as a public interface.
-
- </para>
-
- <scons_example name="read">
- <file name="SConstruct" printme="1">
- hello_c = File('hello.c')
- contents = hello_c.read()
- print "contents are:"
- print contents
- </file>
- <file name="hello.c">
- int main() { printf("Hello, world!\n"); }
- </file>
- </scons_example>
-
- <para>
-
- Which executes as follows on a POSIX system:
-
- </para>
-
- <scons_output example="read" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
-
- </section>
-
- -->
-
- <!--
-
- <section>
- <title>Python Value &Node;</title>
-
- <para>
-
- XXX Value()
-
- </para>
-
- </section>
-
- -->