SCons/Tool/install.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27
  28 <tool name="install">
  29 <summary>
  30 <para>
  31 Sets construction variables for file
  32 and directory installation.
  33 </para>
  34 </summary>
  35 <sets>
  36 <item>INSTALL</item>
  37 <item>INSTALLSTR</item>
  38 </sets>
  39 </tool>
  40
  41 <builder name="Install">
  42 <summary>
  43 <para>
  44 Installs one or more source files or directories
  45 in the specified target,
  46 which must be a directory.
  47 The names of the specified source files or directories
  48 remain the same within the destination directory. The
  49 sources may be given as a string or as a node returned by
  50 a builder.
  51 </para>
  52
  53 <example_commands>
  54 env.Install(target='/usr/local/bin', source=['foo', 'bar'])
  55 </example_commands>
  56
  57 <para>
  58 Note that if target paths chosen for the
  59 &Install; builder (and the related &InstallAs; and
  60 &InstallVersionedLib; builders) are outside the
  61 project tree, such as in the example above,
  62 they may not be selected for "building" by default,
  63 since in the absence of other instructions
  64 &scons; builds targets that are underneath the top directory
  65 (the directory that contains the &SConstruct; file,
  66 usually the current directory).
  67 Use command line targets or the &Default; function
  68 in this case.
  69 </para>
  70
  71 <para>
  72 If the <option>--install-sandbox</option> command line
  73 option is given, the target directory will be prefixed
  74 by the directory path specified.
  75 This is useful to test installation behavior without installing to
  76 a "live" location in the system.
  77 </para>
  78
  79 <para>
  80 See also &FindInstalledFiles;.
  81 For more thoughts on installation, see the User Guide
  82 (particularly the section on Command-Line Targets
  83 and the chapters on Installing Files and on Alias Targets).
  84 </para>
  85
  86 </summary>
  87 </builder>
  88
  89 <builder name="InstallAs">
  90 <summary>
  91 <para>
  92 Installs one or more source files or directories
  93 to specific names,
  94 allowing changing a file or directory name
  95 as part of the installation.
  96 It is an error if the
  97 target
  98 and
  99 source
 100 arguments list different numbers of files or directories.
 101 </para>
 102
 103 <example_commands>
 104 env.InstallAs(target='/usr/local/bin/foo',
 105               source='foo_debug')
 106 env.InstallAs(target=['../lib/libfoo.a', '../lib/libbar.a'],
 107               source=['libFOO.a', 'libBAR.a'])
 108 </example_commands>
 109
 110 <para>
 111 See the note under &Install;.
 112 </para>
 113
 114 </summary>
 115 </builder>
 116
 117 <builder name="InstallVersionedLib">
 118 <summary>
 119 <para>
 120 Installs a versioned shared library. The symlinks appropriate to the
 121 architecture will be generated based on symlinks of the source library.
 122 </para>
 123
 124 <example_commands>
 125 env.InstallVersionedLib(target='/usr/local/bin/foo',
 126                         source='libxyz.1.5.2.so')
 127 </example_commands>
 128
 129 <para>
 130 See the note under &Install;.
 131 </para>
 132
 133 </summary>
 134 </builder>
 135
 136 </sconsdoc>