summaryrefslogtreecommitdiff
path: root/doc/user/install.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
committerLuca Falavigna <dktrkranz@debian.org>2010-01-02 20:56:27 +0100
commit72c578fd4b0b4a5a43e18594339ac4ff26c376dc (patch)
treecadaf3abe37a1066ceae933bc8fe7b75c85f56d2 /doc/user/install.xml
parent548ed1064f327bccc6e538806740d41ea2d928a1 (diff)
Imported Upstream version 1.2.0.d20091224upstream/1.2.0.d20091224
Diffstat (limited to 'doc/user/install.xml')
-rw-r--r--doc/user/install.xml237
1 files changed, 237 insertions, 0 deletions
diff --git a/doc/user/install.xml b/doc/user/install.xml
new file mode 100644
index 0000000..e011986
--- /dev/null
+++ b/doc/user/install.xml
@@ -0,0 +1,237 @@
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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>
+
+ Once a program is built,
+ it is often appropriate to install it in another
+ directory for public use.
+ You use the &Install; method
+ to arrange for a program, or any other file,
+ to be copied into a destination directory:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ hello = env.Program('hello.c')
+ env.Install('/usr/bin', hello)
+ </programlisting>
+
+ <para>
+
+ Note, however, that installing a file is
+ still considered a type of file "build."
+ This is important when you remember that
+ the default behavior of &SCons; is
+ to build files in or below the current directory.
+ If, as in the example above,
+ you are installing files in a directory
+ outside of the top-level &SConstruct; file's directory tree,
+ you must specify that directory
+ (or a higher directory, such as <literal>/</literal>)
+ for it to install anything there:
+
+ </para>
+
+ <screen>
+ % <userinput>scons -Q</userinput>
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ % <userinput>scons -Q /usr/bin</userinput>
+ Install file: "hello" as "/usr/bin/hello"
+ </screen>
+
+ <para>
+
+ It can, however, be cumbersome to remember
+ (and type) the specific destination directory
+ in which the program (or any other file)
+ should be installed.
+ This is an area where the &Alias;
+ function comes in handy,
+ allowing you, for example,
+ to create a pseudo-target named <literal>install</literal>
+ that can expand to the specified destination directory:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ hello = env.Program('hello.c')
+ env.Install('/usr/bin', hello)
+ env.Alias('install', '/usr/bin')
+ </programlisting>
+
+ <para>
+
+ This then yields the more natural
+ ability to install the program
+ in its destination as follows:
+
+ </para>
+
+ <screen>
+ % <userinput>scons -Q</userinput>
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ % <userinput>scons -Q install</userinput>
+ Install file: "hello" as "/usr/bin/hello"
+ </screen>
+
+ <section>
+ <title>Installing Multiple Files in a Directory</title>
+
+ <para>
+
+ You can install multiple files into a directory
+ simply by calling the &Install; function multiple times:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ hello = env.Program('hello.c')
+ goodbye = env.Program('goodbye.c')
+ env.Install('/usr/bin', hello)
+ env.Install('/usr/bin', goodbye)
+ env.Alias('install', '/usr/bin')
+ </programlisting>
+
+ <para>
+
+ Or, more succinctly, listing the multiple input
+ files in a list
+ (just like you can do with any other builder):
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ hello = env.Program('hello.c')
+ goodbye = env.Program('goodbye.c')
+ env.Install('/usr/bin', [hello, goodbye])
+ env.Alias('install', '/usr/bin')
+ </programlisting>
+
+ <para>
+
+ Either of these two examples yields:
+
+ </para>
+
+ <screen>
+ % <userinput>scons -Q install</userinput>
+ cc -o goodbye.o -c goodbye.c
+ cc -o goodbye goodbye.o
+ Install file: "goodbye" as "/usr/bin/goodbye"
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ Install file: "hello" as "/usr/bin/hello"
+ </screen>
+
+ </section>
+
+ <section>
+ <title>Installing a File Under a Different Name</title>
+
+ <para>
+
+ The &Install; method preserves the name
+ of the file when it is copied into the
+ destination directory.
+ If you need to change the name of the file
+ when you copy it, use the &InstallAs; function:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ hello = env.Program('hello.c')
+ env.InstallAs('/usr/bin/hello-new', hello)
+ env.Alias('install', '/usr/bin')
+ </programlisting>
+
+ <para>
+
+ This installs the <literal>hello</literal>
+ program with the name <literal>hello-new</literal>
+ as follows:
+
+ </para>
+
+ <screen>
+ % <userinput>scons -Q install</userinput>
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ Install file: "hello" as "/usr/bin/hello-new"
+ </screen>
+
+ </section>
+
+ <section>
+ <title>Installing Multiple Files Under Different Names</title>
+
+ <para>
+
+ Lastly, if you have multiple files that all
+ need to be installed with different file names,
+ you can either call the &InstallAs; function
+ multiple times, or as a shorthand,
+ you can supply same-length lists
+ for both the target and source arguments:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ hello = env.Program('hello.c')
+ goodbye = env.Program('goodbye.c')
+ env.InstallAs(['/usr/bin/hello-new',
+ '/usr/bin/goodbye-new'],
+ [hello, goodbye])
+ env.Alias('install', '/usr/bin')
+ </programlisting>
+
+ <para>
+
+ In this case, the &InstallAs; function
+ loops through both lists simultaneously,
+ and copies each source file into its corresponding
+ target file name:
+
+ </para>
+
+ <screen>
+ % <userinput>scons -Q install</userinput>
+ cc -o goodbye.o -c goodbye.c
+ cc -o goodbye goodbye.o
+ Install file: "goodbye" as "/usr/bin/goodbye-new"
+ cc -o hello.o -c hello.c
+ cc -o hello hello.o
+ Install file: "hello" as "/usr/bin/hello-new"
+ </screen>
+
+ </section>