Docs for InstallVersionedLib and --install-sandbox [ci skip]

Adds --install-sandbox to manpage options and to
section on Install builder.

Adds mention of InstallVersionedLib to user guide.

Fixes #3007

Signed-off-by: Mats Wichmann <mats@linux.com>

4 files changed, 95 insertions, 4 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index eb9f00b..9af3f3e 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1080,6 +1080,18 @@ This implies
 
   </listitem>
   </varlistentry>
+
+  <varlistentry>
+  <term>--install-sandbox=<replaceable>path</replaceable></term>
+  <listitem>
+<para>
+When using the &Install; functions, prepend <replaceable>path</replaceable>
+to the installation paths such that all installed files will be placed
+underneath <replaceable>path</replaceable>.
+</para>
+  </listitem>
+  </varlistentry>
+
   <varlistentry>
   <term>--interactive</term>
   <listitem>
diff --git a/doc/scons.mod b/doc/scons.mod
index 77fa39b..71e996d 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -212,6 +212,7 @@
 <!ENTITY Import "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Import</function>">
 <!ENTITY Install "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Install</function>">
 <!ENTITY InstallAs "<function xmlns='http://www.scons.org/dbxsd/v1.0'>InstallAs</function>">
+<!ENTITY InstallVersionedLib "<function xmlns='http://www.scons.org/dbxsd/v1.0'>InstallVersionedLib</function>">
 <!ENTITY Link "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Link</function>">
 <!ENTITY ListOption "<function xmlns='http://www.scons.org/dbxsd/v1.0'>ListOption</function>">
 <!ENTITY ListVariable "<function xmlns='http://www.scons.org/dbxsd/v1.0'>ListVariable</function>">
diff --git a/doc/user/install.xml b/doc/user/install.xml
index 8c224d4..db87521 100644
--- a/doc/user/install.xml
+++ b/doc/user/install.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE sconsdoc [
     <!ENTITY % scons SYSTEM "../scons.mod">
     %scons;
-    
+
     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
     %builders-mod;
     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
@@ -11,7 +11,7 @@
     %tools-mod;
     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
     %variables-mod;
-    
+
 ]>
 
 <chapter id="chap-install"
@@ -50,7 +50,7 @@
   Once a program is built,
   it is often appropriate to install it in another
   directory for public use.
-  You use the &Install; method 
+  You use the &Install; method
   to arrange for a program, or any other file,
   to be copied into a destination directory:
 
@@ -226,7 +226,7 @@ int main() { printf("Hello, world!\n"); }
 
     <para>
 
-    Lastly, if you have multiple files that all
+    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,
@@ -268,4 +268,66 @@ int main() { printf("Goodbye, world!\n"); }
 
   </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>
+-->
+
+  </section>
+
 </chapter>
diff --git a/src/engine/SCons/Tool/install.xml b/src/engine/SCons/Tool/install.xml
index 6ae3e30..74169b3 100644
--- a/src/engine/SCons/Tool/install.xml
+++ b/src/engine/SCons/Tool/install.xml
@@ -52,6 +52,22 @@ a builder.
 <example_commands>
 env.Install('/usr/local/bin', source = ['foo', 'bar'])
 </example_commands>
+
+<para>
+If the <option>--install-sandbox</option> command line
+option is given, the target directory will be prefixed
+by the directory path specified.
+This is useful to test installs without installing to
+a "live" location in the system.
+</para>
+
+<para>
+See also &FindInstalledFiles;.
+For more thoughts on installation, see the User Guide
+(particularly the section on Command-Line Targets
+and the chapters on Installing Files and on Alias Targets).
+</para>
+
 </summary>
 </builder>