5 Permission is hereby granted, free of charge, to any person obtaining
6 a copy of this software and associated documentation files (the
7 "Software"), to deal in the Software without restriction, including
8 without limitation the rights to use, copy, modify, merge, publish,
9 distribute, sublicense, and/or sell copies of the Software, and to
10 permit persons to whom the Software is furnished to do so, subject to
11 the following conditions:
13 The above copyright notice and this permission notice shall be included
14 in all copies or substantial portions of the Software.
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
17 KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
18 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 =head2 The C<Command> method
31 The C<Command> method is called as follows:
33 Command $env <target>, <inputs>, <build action>;
35 The target is made dependent upon the list of input files specified, and the
36 inputs must be built successfully or Cons will not attempt to build the
39 To specify a command with multiple targets, you can specify a reference to a
40 list of targets. In Perl, a list reference can be created by enclosing a
41 list in square brackets. Hence the following command:
43 Command $env ['foo.h', 'foo.c'], 'foo.template', q(
47 could be used in a case where the command C<gen> creates two files, both
48 F<foo.h> and F<foo.c>.
54 Creating a &Builder; and attaching it to a &consenv;
55 allows for a lot of flexibility when you
56 want to re-use actions
57 to build multiple files of the same type.
58 This can, however, be cumbersome
59 if you only need to execute one specific command
60 to build a single file (or group of files).
61 For these situations, &SCons; supports a
62 &Command; &Builder; that arranges
63 for a specific action to be executed
64 to build a specific file or files.
65 This looks a lot like the other builders
66 (like &b-link-Program;, &b-link-Object;, etc.),
67 but takes as an additional argument
68 the command to be executed to build the file:
74 env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET")
80 &SCons; runs the specified command,
81 substituting &cv-link-SOURCE; and &cv-link-TARGET;
87 % <userinput>scons -Q</userinput>
88 sed 's/x/y/' < foo.in > foo.out
93 This is often more convenient than
94 creating a &Builder; object
95 and adding it to the &cv-link-BUILDERS; variable
102 Note that the action you specify to the
103 &Command; &Builder; can be any legal &SCons; &Action;,
104 such as a Python function:
110 def build(target, source, env):
111 # Whatever it takes to build
113 env.Command('foo.out', 'foo.in', build)
118 Which executes as follows:
123 % <userinput>scons -Q</userinput>
124 build(["foo.out"], ["foo.in"])
129 Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded
130 in the source and target as well as of SCons 1.1,
136 env.Command('${SOURCE.basename}.out', 'foo.in', build)
142 which does the same thing as the previous example, but allows you
143 to avoid repeating yourself.