From 72c578fd4b0b4a5a43e18594339ac4ff26c376dc Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 2 Jan 2010 20:56:27 +0100 Subject: Imported Upstream version 1.2.0.d20091224 --- doc/user/factories.xml | 466 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 466 insertions(+) create mode 100644 doc/user/factories.xml (limited to 'doc/user/factories.xml') diff --git a/doc/user/factories.xml b/doc/user/factories.xml new file mode 100644 index 0000000..17e52bd --- /dev/null +++ b/doc/user/factories.xml @@ -0,0 +1,466 @@ + + + + + &SCons; provides a number of platform-independent functions, + called factories, + that perform common file system manipulations + like copying, moving or deleting files and directories, + or making directories. + These functions are factories + because they don't perform the action + at the time they're called, + they each return an &Action; object + that can be executed at the appropriate time. + + + +
+ Copying Files or Directories: The &Copy; Factory + + + + Suppose you want to arrange to make a copy of a file, + and don't have a suitable pre-existing builder. + + + Unfortunately, in the early days of SCons design, + we used the name &Copy; for the function that + returns a copy of the environment, + otherwise that would be the logical choice for + a Builder that copies a file or directory tree + to a target location. + + + One way would be to use the &Copy; action factory + in conjunction with the &Command; builder: + + + + + Command("file.out", "file.in", Copy("$TARGET", "$SOURCE")) + + + + + Notice that the action returned by the &Copy; factory + will expand the &cv-link-TARGET; and &cv-link-SOURCE; strings + at the time &file_out; is built, + and that the order of the arguments + is the same as that of a builder itself--that is, + target first, followed by source: + + + + + % scons -Q + Copy("file.out", "file.in") + + + + + You can, of course, name a file explicitly + instead of using &cv-TARGET; or &cv-SOURCE;: + + + + + Command("file.out", [], Copy("$TARGET", "file.in")) + + + + + Which executes as: + + + + + % scons -Q + Copy("file.out", "file.in") + + + + + The usefulness of the &Copy; factory + becomes more apparent when + you use it in a list of actions + passed to the &Command; builder. + For example, suppose you needed to run a + file through a utility that only modifies files in-place, + and can't "pipe" input to output. + One solution is to copy the source file + to a temporary file name, + run the utility, + and then copy the modified temporary file to the target, + which the &Copy; factory makes extremely easy: + + + + + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + + + + + The output then looks like: + + + + + % scons -Q + Copy("tempfile", "file.in") + modify tempfile + Copy("file.out", "tempfile") + + +
+ +
+ Deleting Files or Directories: The &Delete; Factory + + + + If you need to delete a file, + then the &Delete; factory + can be used in much the same way as + the &Copy; factory. + For example, if we want to make sure that + the temporary file + in our last example doesn't exist before + we copy to it, + we could add &Delete; to the beginning + of the command list: + + + + + Command("file.out", "file.in", + [ + Delete("tempfile"), + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + + + + + Which then executes as follows: + + + + + % scons -Q + Delete("tempfile") + Copy("tempfile", "file.in") + modify tempfile + Copy("file.out", "tempfile") + + + + + Of course, like all of these &Action; factories, + the &Delete; factory also expands + &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately. + For example: + + + + + Command("file.out", "file.in", + [ + Delete("$TARGET"), + Copy("$TARGET", "$SOURCE") + ]) + + + + + Executes as: + + + + + % scons -Q + Delete("file.out") + Copy("file.out", "file.in") + + + + + Note, however, that you typically don't need to + call the &Delete; factory explicitly in this way; + by default, &SCons; deletes its target(s) + for you before executing any action. + + + + + + One word of caution about using the &Delete; factory: + it has the same variable expansions available + as any other factory, including the &cv-SOURCE; variable. + Specifying Delete("$SOURCE") + is not something you usually want to do! + + + +
+ +
+ Moving (Renaming) Files or Directories: The &Move; Factory + + + + The &Move; factory + allows you to rename a file or directory. + For example, if we don't want to copy the temporary file, + we could use: + + + + + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + + + + + Which would execute as: + + + + + % scons -Q + Copy("tempfile", "file.in") + modify tempfile + Move("file.out", "tempfile") + + +
+ +
+ Updating the Modification Time of a File: The &Touch; Factory + + + + If you just need to update the + recorded modification time for a file, + use the &Touch; factory: + + + + + Command("file.out", "file.in", + [ + Copy("$TARGET", "$SOURCE"), + Touch("$TARGET"), + ]) + + + + + Which executes as: + + + + + % scons -Q + Copy("file.out", "file.in") + Touch("file.out") + + +
+ +
+ Creating a Directory: The &Mkdir; Factory + + + + If you need to create a directory, + use the &Mkdir; factory. + For example, if we need to process + a file in a temporary directory + in which the processing tool + will create other files that we don't care about, + you could use: + + + + + Command("file.out", "file.in", + [ + Delete("tempdir"), + Mkdir("tempdir"), + Copy("tempdir/${SOURCE.file}", "$SOURCE"), + "process tempdir", + Move("$TARGET", "tempdir/output_file"), + Delete("tempdir"), + ]) + + + + + Which executes as: + + + + + % scons -Q + Delete("tempdir") + Mkdir("tempdir") + Copy("tempdir/file.in", "file.in") + process tempdir + Move("file.out", "tempdir/output_file") + scons: *** [file.out] tempdir/output_file: No such file or directory + + +
+ +
+ Changing File or Directory Permissions: The &Chmod; Factory + + + + To change permissions on a file or directory, + use the &Chmod; factory. + The permission argument uses POSIX-style + permission bits and should typically + be expressed as an octal, + not decimal, number: + + + + + Command("file.out", "file.in", + [ + Copy("$TARGET", "$SOURCE"), + Chmod("$TARGET", 0755), + ]) + + + + + Which executes: + + + + + % scons -Q + Copy("file.out", "file.in") + Chmod("file.out", 0755) + + +
+ +
+ Executing an action immediately: the &Execute; Function + + + + We've been showing you how to use &Action; factories + in the &Command; function. + You can also execute an &Action; returned by a factory + (or actually, any &Action;) + at the time the &SConscript; file is read + by using the &Execute; function. + For example, if we need to make sure that + a directory exists before we build any targets, + + + + + Execute(Mkdir('/tmp/my_temp_directory')) + + + + + Notice that this will + create the directory while + the &SConscript; file is being read: + + + + + % scons + scons: Reading SConscript files ... + Mkdir("/tmp/my_temp_directory") + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + + + + + If you're familiar with Python, + you may wonder why you would want to use this + instead of just calling the native Python + os.mkdir() function. + The advantage here is that the &Mkdir; + action will behave appropriately if the user + specifies the &SCons; or + options--that is, + it will print the action but not actually + make the directory when is specified, + or make the directory but not print the action + when is specified. + + + + + + The &Execute; function returns the exit status + or return value of the underlying action being executed. + It will also print an error message if the action + fails and returns a non-zero value. + &SCons; will not, however, + actually stop the build if the action fails. + If you want the build to stop + in response to a failure in an action called by &Execute;, + you must do so by explicitly + checking the return value + and calling the &Exit; function + (or a Python equivalent): + + + + + if Execute(Mkdir('/tmp/my_temp_directory')): + # A problem occurred while making the temp directory. + Exit(1) + + +
-- cgit v1.2.3