3 Copyright (c) 2001, 2002, 2003 Steven Knight
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 Once a program is built,
29 it is often appropriate to install it in another
30 directory for public use.
31 You use the &Install; method
32 to arrange for a program, or any other file,
33 to be copied into a destination directory:
37 <scons_example name="ex1">
38 <file name="SConstruct" printme="1">
40 hello = env.Program('hello.c')
41 env.Install('__ROOT__/usr/bin', hello)
44 int main() { printf("Hello, world!\n"); }
50 Note, however, that installing a file is
51 still considered a type of file "build."
52 This is important when you remember that
53 the default behavior of &SCons; is
54 to build files in or below the current directory.
55 If, as in the example above,
56 you are installing files in a directory
57 outside of the top-level &SConstruct; file's directory tree,
58 you must specify that directory
59 (or a higher directory, such as <literal>/</literal>)
60 for it to install anything there:
64 <scons_output example="ex1">
65 <command>scons</command>
66 <command>scons __ROOT__/usr/bin</command>
71 It can, however, be cumbersome to remember
72 (and type) the specific destination directory
73 in which the program (or any other file)
75 This is an area where the &Alias;
76 function comes in handy,
77 allowing you, for example,
78 to create a pseudo-target named <literal>install</literal>
79 that can expand to the specified destination directory:
83 <scons_example name="ex2">
84 <file name="SConstruct" printme="1">
86 hello = env.Program('hello.c')
87 env.Install('__ROOT__/usr/bin', hello)
88 env.Alias('install', '__ROOT__/usr/bin')
91 int main() { printf("Hello, world!\n"); }
97 This then yields the more natural
98 ability to install the program
99 in its destination as follows:
103 <scons_output example="ex1">
104 <command>scons</command>
105 <command>scons install</command>
109 <title>Installing Multiple Files in a Directory</title>
113 You can install multiple files into a directory
114 simply by calling the &Install; function multiple times:
118 <scons_example name="ex3">
119 <file name="SConstruct" printme="1">
121 hello = env.Program('hello.c')
122 goodbye = env.Program('goodbye.c')
123 env.Install('__ROOT__/usr/bin', hello)
124 env.Install('__ROOT__/usr/bin', goodbye)
125 env.Alias('install', '__ROOT__/usr/bin')
127 <file name="hello.c">
128 int main() { printf("Hello, world!\n"); }
134 Or, more succinctly, listing the multiple input
136 (just like you can do with any other builder):
142 hello = env.Program('hello.c')
143 goodbye = env.Program('goodbye.c')
144 env.Install('__ROOT__/usr/bin', [hello, goodbye])
145 env.Alias('install', '__ROOT__/usr/bin')
150 Either of these two examples yields:
154 <scons_output example="ex3">
155 <command>scons install</command>
161 <title>Installing a File Under a Different Name</title>
165 The &Install; method preserves the name
166 of the file when it is copied into the
167 destination directory.
168 If you need to change the name of the file
169 when you copy it, use the &InstallAs; function:
173 <scons_example name="ex4">
174 <file name="SConstruct" printme="1">
176 hello = env.Program('hello.c')
177 env.InstallAs('__ROOT__/usr/bin/hello-new', hello)
178 env.Alias('install', '__ROOT__/usr/bin')
180 <file name="hello.c">
181 int main() { printf("Hello, world!\n"); }
187 This installs the <literal>hello</literal>
188 program with the name <literal>hello-new</literal>
193 <scons_output example="ex4">
194 <command>scons install</command>
200 <title>Installing Multiple Files Under Different Names</title>
204 Lastly, if you have multiple files that all
205 need to be installed with different file names,
206 you can either call the &InstallAs; function
207 multiple times, or as a shorthand,
208 you can supply same-length lists
209 for the both the target and source arguments:
213 <scons_example name="ex5">
214 <file name="SConstruct" printme="1">
216 hello = env.Program('hello.c')
217 goodbye = env.Program('goodbye.c')
218 env.InstallAs(['__ROOT__/usr/bin/hello-new',
219 '__ROOT__/usr/bin/goodbye-new'],
222 <file name="hello.c">
223 int main() { printf("Hello, world!\n"); }
229 In this case, the &InstallAs; function
230 loops through both lists simultaneously,
231 and copies each source file into its corresponding
236 <scons_output example="ex5">
237 <command>scons install</command>