mirror of
https://github.com/Relintai/scons_gd.git
synced 2025-02-06 16:25:59 +01:00
346 lines
9.7 KiB
XML
346 lines
9.7 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE sconsdoc [
|
|
<!ENTITY % scons SYSTEM "../scons.mod">
|
|
%scons;
|
|
|
|
<!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
|
|
%builders-mod;
|
|
<!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
|
|
%functions-mod;
|
|
<!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
|
|
%tools-mod;
|
|
<!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
|
|
%variables-mod;
|
|
|
|
]>
|
|
|
|
<chapter id="chap-install"
|
|
xmlns="http://www.scons.org/dbxsd/v1.0"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
|
|
<title>Installing Files in Other Directories: the &Install; Builder</title>
|
|
|
|
<!--
|
|
|
|
__COPYRIGHT__
|
|
|
|
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>
|
|
|
|
<scons_example name="install_ex1">
|
|
<file name="SConstruct" printme="1">
|
|
env = Environment()
|
|
hello = env.Program('hello.c')
|
|
env.Install('__ROOT__/usr/bin', hello)
|
|
</file>
|
|
<file name="hello.c">
|
|
int main() { printf("Hello, world!\n"); }
|
|
</file>
|
|
</scons_example>
|
|
|
|
<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>
|
|
|
|
<scons_output example="install_ex1" suffix="1">
|
|
<scons_output_command>scons -Q</scons_output_command>
|
|
<scons_output_command>scons -Q __ROOT__/usr/bin</scons_output_command>
|
|
</scons_output>
|
|
|
|
<para>
|
|
|
|
It can, however, be cumbersome to remember
|
|
(and type) the specific destination directory
|
|
in which the program (or other file)
|
|
should be installed. A call to &Default; can be used to
|
|
add the directory to the list of default targets,
|
|
removing the need to type it,
|
|
but sometimes you don't want to install on every build.
|
|
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>
|
|
|
|
<scons_example name="install_ex2">
|
|
<file name="SConstruct" printme="1">
|
|
env = Environment()
|
|
hello = env.Program('hello.c')
|
|
env.Install('__ROOT__/usr/bin', hello)
|
|
env.Alias('install', '__ROOT__/usr/bin')
|
|
</file>
|
|
<file name="hello.c">
|
|
int main() { printf("Hello, world!\n"); }
|
|
</file>
|
|
</scons_example>
|
|
|
|
<para>
|
|
|
|
This then yields the more natural
|
|
ability to install the program
|
|
in its destination as a separate
|
|
invocation, as follows:
|
|
|
|
</para>
|
|
|
|
<scons_output example="install_ex2" suffix="1">
|
|
<scons_output_command>scons -Q</scons_output_command>
|
|
<scons_output_command>scons -Q install</scons_output_command>
|
|
</scons_output>
|
|
|
|
<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>
|
|
|
|
<scons_example name="install_ex3">
|
|
<file name="SConstruct" printme="1">
|
|
env = Environment()
|
|
hello = env.Program('hello.c')
|
|
goodbye = env.Program('goodbye.c')
|
|
env.Install('__ROOT__/usr/bin', hello)
|
|
env.Install('__ROOT__/usr/bin', goodbye)
|
|
env.Alias('install', '__ROOT__/usr/bin')
|
|
</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>
|
|
|
|
Or, more succinctly, listing the multiple input
|
|
files in a list
|
|
(just like you can do with any other builder):
|
|
|
|
</para>
|
|
|
|
<sconstruct>
|
|
env = Environment()
|
|
hello = env.Program('hello.c')
|
|
goodbye = env.Program('goodbye.c')
|
|
env.Install('__ROOT__/usr/bin', [hello, goodbye])
|
|
env.Alias('install', '__ROOT__/usr/bin')
|
|
</sconstruct>
|
|
|
|
<para>
|
|
|
|
Either of these two examples yields:
|
|
|
|
</para>
|
|
|
|
<scons_output example="install_ex3" suffix="1">
|
|
<scons_output_command>scons -Q install</scons_output_command>
|
|
</scons_output>
|
|
|
|
</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>
|
|
|
|
<scons_example name="install_ex4">
|
|
<file name="SConstruct" printme="1">
|
|
env = Environment()
|
|
hello = env.Program('hello.c')
|
|
env.InstallAs('__ROOT__/usr/bin/hello-new', hello)
|
|
env.Alias('install', '__ROOT__/usr/bin')
|
|
</file>
|
|
<file name="hello.c">
|
|
int main() { printf("Hello, world!\n"); }
|
|
</file>
|
|
</scons_example>
|
|
|
|
<para>
|
|
|
|
This installs the <literal>hello</literal>
|
|
program with the name <literal>hello-new</literal>
|
|
as follows:
|
|
|
|
</para>
|
|
|
|
<scons_output example="install_ex4" suffix="1">
|
|
<scons_output_command>scons -Q install</scons_output_command>
|
|
</scons_output>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Installing Multiple Files Under Different Names</title>
|
|
|
|
<para>
|
|
|
|
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>
|
|
|
|
<scons_example name="install_ex5">
|
|
<file name="SConstruct" printme="1">
|
|
env = Environment()
|
|
hello = env.Program('hello.c')
|
|
goodbye = env.Program('goodbye.c')
|
|
env.InstallAs(['__ROOT__/usr/bin/hello-new',
|
|
'__ROOT__/usr/bin/goodbye-new'],
|
|
[hello, goodbye])
|
|
env.Alias('install', '__ROOT__/usr/bin')
|
|
</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>
|
|
|
|
In this case, the &InstallAs; function
|
|
loops through both lists simultaneously,
|
|
and copies each source file into its corresponding
|
|
target file name:
|
|
|
|
</para>
|
|
|
|
<scons_output example="install_ex5" suffix="1">
|
|
<scons_output_command>scons -Q install</scons_output_command>
|
|
</scons_output>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Installing a Shared Library</title>
|
|
|
|
<para>
|
|
If a shared library is created with the
|
|
&cv-link-SHLIBVERSION; variable set,
|
|
&scons; will create symbolic links as needed based on that
|
|
variable. To properly install such a library including the
|
|
symbolic links, use the &InstallVersionedLib; function.
|
|
</para>
|
|
|
|
<para>
|
|
For example, on a Linux system, this instruction:
|
|
</para>
|
|
|
|
<sconstruct>
|
|
foo = env.SharedLibrary(target="foo", source="foo.c", SHLIBVERSION="1.2.3")
|
|
</sconstruct>
|
|
|
|
<para>
|
|
Will produce a shared library
|
|
<filename>libfoo.so.1.2.3</filename>
|
|
and symbolic links
|
|
<filename>libfoo.so</filename> and
|
|
<filename>libfoo.so.1</filename>
|
|
which point to
|
|
<filename>libfoo.so.1.2.3</filename>.
|
|
You can use the Node returned by the &SharedLibrary;
|
|
builder in order to install the library and its
|
|
symbolic links in one go without having to list
|
|
them individually:
|
|
</para>
|
|
|
|
<sconstruct>
|
|
env.InstallVersionedLib(target="lib", source=foo)
|
|
</sconstruct>
|
|
|
|
<!-- didn't get this to illustrate what I expected: example reports
|
|
installing lib without version, while manual effort has it:
|
|
|
|
<scons_example name="install_ex6">
|
|
<file name="SConstruct" printme="1">
|
|
env = Environment()
|
|
foo = env.SharedLibrary(target="foo", source="foo.c", SHLIBVERSION="1.2.3")
|
|
ins = env.InstallVersionedLib(target="lib", source=foo)
|
|
env.Alias('install', ins)
|
|
</file>
|
|
<file name="foo.c">
|
|
int call_foo() {
|
|
printf("Hello world");
|
|
return(0);
|
|
}
|
|
</file>
|
|
</scons_example>
|
|
|
|
<scons_output example="install_ex6" suffix="1">
|
|
<scons_output_command>scons -Q install</scons_output_command>
|
|
</scons_output>
|
|
-->
|
|
|
|
<para>
|
|
On systems which expect a shared library to be installed both with
|
|
a name that indicates the version, for run-time resolution,
|
|
and as a plain name, for link-time resolution, the
|
|
&InstallVersionedLib; function can be used. Symbolic links
|
|
appropriate to the type of system will be generated based on
|
|
symlinks of the source library.
|
|
</para>
|
|
</section>
|
|
|
|
</chapter>
|