Sophie: a-a-p-1.090-2mdv2009.0 noarch

a-a-p-1.090-2mdv2009.0.noarch.rpm

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 17. Installing</title><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="A-A-P Recipe Executive"><link rel="up" href="user.html" title="Part II. User Manual"><link rel="prev" href="user-fetch.html" title="Chapter 16. Fetching"><link rel="next" href="user-version.html" title="Chapter 18. Version Control"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="100%" id="navtable"><tbody><tr><td align="left" class="left" width="33%"><b><a href="http://www.a-a-p.org">A-A-P home page</a></b></td><td align="center" class="center" width="34%"><b><a href="index.html">A-A-P Recipe Executive</a></b></td><td align="right" class="right" width="33%"></td></tr><tr><td align="left" class="left"><a accesskey="p" href="user-fetch.html">Prev</a></td><td align="center" class="center">User Manual</td><td align="right" class="right"><a accesskey="n" href="user-version.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="user-install"></a>Chapter 17. Installing</h2></div></div></div><p>
This section contains details about the installation
of the produced programs and other items.
Those other items can be libraries (produced by the
<a href="ref-commands.html#cmd-lib"><code class="literal">:lib</code></a>,
<a href="ref-commands.html#cmd-dll"><code class="literal">:dll</code></a>,
or
<a href="ref-commands.html#cmd-ltlib"><code class="literal">:ltlib</code></a>
commands),
header files for the API of a library,
documentation (like manpages or info files),
and as a catch-all, "data."
</p><p>
Usually installing is done with
<strong class="userinput"><code>aap install</code></strong>.
If you do not define an
"install" target in the recipe, <span class="application">Aap</span> will add one for you.
The default install target invokes up to 15 other install
targets, one for each kind of item you can install.
This makes it easy to customize the installation of
some particular kind of item (e.g. libtool archives).
</p><p>
The default
install target invokes two or three other targets:
install-platform, install-shared, and (optionally,
only if you define it in the recipe) install-local.
Each of these invokes other install targets for
specific kinds of files, as follows:
</p><div class="table"><a name="tbl-install"></a><p class="title"><b>Table 17.1. Install targets</b></p><div class="table-contents"><table summary="Install targets" border="0"><colgroup><col width="200,200,400"><col><col></colgroup><thead><tr><th>High-level Target</th><th>Lower-level Targets</th><th>Install these Files</th></tr></thead><tbody><tr><td>install-platform</td><td> </td><td>This is for installing platform-dependent files.</td></tr><tr><td> </td><td>install-exec</td><td><p>Install programs (generally produced through
      <a href="ref-commands.html#cmd-program"><code class="literal">:program</code></a>
      command).
      </p></td></tr><tr><td> </td><td>install-sbin</td><td>Install programs for system administration.
      These
      may have additional security considerations, hence a separate target.
      </td></tr><tr><td> </td><td>install-lib</td><td>Install static libraries (from the
      <a href="ref-commands.html#cmd-lib"><code class="literal">:lib</code></a> command).
      </td></tr><tr><td> </td><td>install-dll</td><td>Install shared libraries (from the
      <a href="ref-commands.html#cmd-dll"><code class="literal">:dll</code></a> command).
      </td></tr><tr><td> </td><td>install-ltlib</td><td>
      Install shared libtool libraries (from the
      <a href="ref-commands.html#cmd-ltlib"><code class="literal">:ltlib</code></a> command).
      These require special treatment by the libtool program,
      hence a separate target.
      </td></tr><tr><td> </td><td>install-conf</td><td>Install platform-specific configuration files
      (such as pkg-config files).
      </td></tr><tr><td> </td><td>install-platform-local</td><td>A catch-all for things that don't
      fit anywhere else.
      </td></tr><tr><td>install-shared</td><td> </td><td>This is for installing files shared between platforms.</td></tr><tr><td> </td><td>install-data</td><td>Install data for the package.
      This would typically include translation files,
      examples (if they're not in the manpage),
      and images used by the package.
      </td></tr><tr><td> </td><td>install-man</td><td>Install manpages.</td></tr><tr><td> </td><td>install-info</td><td>Install GNU-style info pages.</td></tr><tr><td> </td><td>install-include</td><td>Installs header files (also known as includes).
      </td></tr><tr><td> </td><td>install-shared-local</td><td>A catch-all for things that don't fit anywhere else.</td></tr><tr><td>install-local</td><td> </td><td><p>this is an optional target that you can define for extra
      installing, without changing the other install targets.</p></td></tr></tbody></table></div></div><br class="table-break"><p>
  Each of these dependencies is only added automatically if you do not define
  it yourself.  In other words, if you do not define a dependency with
  <code class="computeroutput">install-data</code> as a target, <span class="application">Aap</span> will add such a
  dependency internally.
  Unless you need special processing for specific kinds of items,
  you should rarely need to define any of the install
  targets yourself.
  The exceptions are
  <code class="computeroutput">install-platform-local</code>,
  <code class="computeroutput">install-shared-local</code> and
  <code class="computeroutput">install-local</code>,
  which you can define without disturbing <span class="application">Aap</span>'s normal
  mechanisms for installing the programs and libraries you create.
</p><p>
  All these dependencies that <span class="application">Aap</span> adds are at the toplevel.  Thus there is
  only one of each for all the recipes in your project.  See
  <a href="user-install.html#install-path">below</a> for an example of including the
  path of an item.  Note that this works different from the "clean" and
  "cleanmore" targets.  These can exist multiple times, each parent and child
  recipe can have one.
</p><p>
All of <span class="application">Aap</span>'s default install targets operate in
roughly the same fashion:
specific actions are invoked for each install target.
The default actions all use
top-level variables
named <code class="literal">INSTALL_<em class="replaceable"><code>target</code></em></code>
which collect filenames to install.
Other toplevel variables control where those
files are installed (<code class="literal"><em class="replaceable"><code>target</code></em>DIR</code>)
and what file mode is used (<code class="literal"><em class="replaceable"><code>target</code></em>MODE</code>).
This table shows the specific settings for each of
the default install targets:
</p><div class="table"><a name="installvar"></a><p class="title"><b>Table 17.2. Settings for the install target</b></p><div class="table-contents"><table summary="Settings for the install target" border="0"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th>target</th><th>variable</th><th>action</th><th>directory</th><th>default directory</th><th>mode</th><th>default mode</th></tr></thead><tbody><tr><td>install-exec</td><td>$INSTALL_EXEC</td><td>installexec</td><td>$EXECDIR</td><td>bin/</td><td>$EXECMODE</td><td>0755</td></tr><tr><td>install-sbin</td><td>$INSTALL_SBIN</td><td>installsbin</td><td>$SBINDIR</td><td>sbin/</td><td>$EXECMODE</td><td>0755</td></tr><tr><td>install-lib</td><td>$INSTALL_LIB</td><td>installlib</td><td>$LIBDIR</td><td>lib/</td><td>$LIBMODE</td><td>0644</td></tr><tr><td>install-dll</td><td>$INSTALL_DLL</td><td>installdll</td><td>$DLLDIR</td><td>lib/</td><td>$DLLMODE</td><td>0755</td></tr><tr><td>install-ltlib</td><td>$INSTALL_LTLIB</td><td colspan="5">
    No default settings for libtool libraries have been
    added to <span class="application">Aap</span> yet. It seems likely that DLLDIR and DLLMODE will be used.
    </td></tr><tr><td>install-conf</td><td>$INSTALL_CONF</td><td>installconf</td><td>$CONFDIR</td><td>etc/</td><td>$CONFMODE</td><td>0644</td></tr><tr><td>install-data</td><td>$INSTALL_DATA</td><td>installdata</td><td>$DATADIR</td><td>share/
    <sup>[<a name="id2644889" href="#ftn.id2644889">a</a>]</sup></td><td>$DATAMODE</td><td>0644</td></tr><tr><td>install-man</td><td>$INSTALL_MAN</td><td>installman</td><td>$MANDIR</td><td>man/
    <sup>[<a name="id2644920" href="#ftn.id2644920">b</a>]</sup></td><td>$MANMODE</td><td>0644</td></tr><tr><td>install-info</td><td>$INSTALL_INFO</td><td>installinfo</td><td>$INFODIR</td><td>info/</td><td>$INFOMODE</td><td>0644</td></tr><tr><td>install-include</td><td>$INSTALL_INCLUDE</td><td>installinclude</td><td>$INCLUDEDIR</td><td>include/</td><td>$INCLUDEMODE</td><td>0644</td></tr></tbody><tbody class="footnotes"><tr><td colspan="7"><div class="footnote"><p><sup>[<a name="ftn.id2644889" href="#id2644889">a</a>] </sup>
    A subdirectory will be added with the name $PKGNAME.  You must set this
    variable to the name of your application!  In the rare situation that you
    need to install into multiple directories you may set $PKGNAME to an empty
    string and prepend the directory name to your data files.
    </p></div><div class="footnote"><p><sup>[<a name="ftn.id2644920" href="#id2644920">b</a>] </sup>
    A subdirectory will be added that uses the extension of the file.  For
    "foo.1" the directory is "man1", for "foo.2" it is "man2", and so on.
    </p></div></td></tr></tbody></table></div></div><br class="table-break"><p>
  The
  <a href="ref-commands.html#cmd-program">:program</a> command adds its target to the $INSTALL_EXEC variable.
  The
  <a href="ref-commands.html#cmd-lib">:lib</a> command adds its target to the $INSTALL_LIB variable.
  The
  <a href="ref-commands.html#cmd-dll">:dll</a> command adds its target to the $INSTALL_DLL variable.
  The
  <a href="ref-commands.html#cmd-ltlib">:ltlib</a> command adds its target to the $INSTALL_LTLIB variable.
</p><p>
The "installexec" action will strip the program by default, if the "strip"
program can be found.  If you don't want this add the {nostrip} attribute to
the program or set $STRIP to an empty value.
</p><p>
You can also overrule the default actions by one of your own.  The
<a href="ref-python.html#python-install-files">install_files()</a> function can be
useful then.  See the default.aap recipe for examples.
</p><h2><a name="install-dirs"></a>Destination Directories</h2><p>
All the install targets prepend a path to the directory they install into.
The directory mentioned above is appended.

</p><div class="informaltable"><table border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>$DESTDIR</td><td>Normally empty, which means that the root directory is
                      used.  Set this when you don't want to install to the
                      local machine, but still pretend to install in the root.
                      Examples: "~/dummyroot", "scp://foo.org/".
                      Yes, you can do remote installing this way!  Although not
                      everything that works locally will work remotely.
                      </td></tr><tr><td>$PREFIX</td><td>Default is "/usr/local/" on Unix.  This specifies where
                      to install to.  The installed program is aware of being
                      installed here, $PREFIX may be put in configuration
                      files.</td></tr></tbody></table></div><p>
</p><p>
The variables are concatenated.  For example, programs are installed in
$DESTDIR$PREFIX$EXECDIR.  Slashes are added in between where needed.
</p><p>
The directories that are used are automatically created when needed.  Note
that "uninstall" does not delete the directories!
</p><p>
When installing the path to a file is normally removed.  Thus when you
produced a program "results/myprog" it will be installed as "myprog".  If you
need to keep the path use the "keepdir" attribute on the file name.
</p><pre class="programlisting">
          INSTALL_INCLUDE += sys/myheader.h {keepdir}
</pre><p>
As an alternative to {keepdir},
there is the {installdir} attribute,
which explicitly sets the relative path of the file to be installed.
Files with an {installdir} attribute are
installed in
<code class="literal">$DESTDIR$PREFIX$<em class="replaceable"><code>target</code></em>DIR$installdir</code>.
The above setting could also be done as:
</p><pre class="programlisting">
          INSTALL_INCLUDE += sys/myheader.h {installdir=sys}
</pre><p>
The advantage of {installdir} over {keepdir} is that
the relative paths (from toplevel recipe to file and from
install directory to the desired install location)
need not be the same.
For instance:
</p><pre class="programlisting">
          INSTALL_INCLUDE += api/2.2/c/myheader.h {installdir=sys}
</pre><p>
</p><p>
For additional flexibility, the source and target <span class="emphasis"><em>filenames</em></span>
need not be the same, either. For this you can use the attribute
{installname} which is similar to {installdir}. If {installname}
is set, this is used as the filename instead of the name of the source file,
thus:
</p><pre class="programlisting">
          INSTALL_INCLUDE += api/2.2/c/myheader.h {installname=header.h}
</pre><p>
This will install the source file "myheader.h" as "header.h".
You can combine {installname} with {keepdir} or {installdir}
to install a source file to an arbitrarily-named destination.
In summary:
</p><div class="informaltable"><table border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>(none)</td><td>
        Source file name is preserved.
        Path to source file is not preserved,
        install to target directory determined by <span class="application">Aap</span>.
        The source file "api/2.2/c/myheader.h" is installed as "myheader.h"
        in the $INCLUDEDIR directory.
      </td></tr><tr><td>{installname}</td><td>
        Source file name is not preserved; source file is installed
        under name given by {installname} attribute.
        Path to source file is not preserved,
        install to target directory determined by <span class="application">Aap</span>.
        The source file "api/2.2/c/myheader.h" with attribute {installname=header.h}
        is installed as "header.h"
        in the $INCLUDEDIR directory.
      </td></tr><tr><td>{keepdir}</td><td>
        Source file name is preserved.
        Path to source file is preserved,
        install to subdirectory under target directory determined by <span class="application">Aap</span>.
        Subdirectory is the relative path to the source file.
        The source file "api/2.2/c/myheader.h" with attribute {keepdir}
        is installed as "myheader.h"
        in $INCLUDEDIR/api/2.2/c/ .
      </td></tr><tr><td>{installdir}</td><td>
        Source file name is preserved.
        Path to source file is replaced by the value of {installdir}
        and the file installs to a subdirectory under 
        the target directory determined by <span class="application">Aap</span>.
        Subdirectory is the value of {installdir}
        The source file "api/2.2/c/myheader.h" with attribute {installdir=myinclude}
        is installed as "myheader.h"
        in $INCLUDEDIR/myinclude/ .
      </td></tr><tr><td>{installdir} {installname} or {keepdir} {installname}</td><td>
        The path to the source file is either kept or replaced
        by the value of {installdir}, and the name
        of the file is replaced by the value of {installname}.
        The source file "api/2.2/c/myheader.h" with attributes {keepdir} {installname=header.h}
        is installed as "header.h"
        in $INCLUDEDIR/api/2.2/c/ .
        The source file "api/2.2/c/myheader.h" with attributes {installdir=myinclude} {installname=header.h}
        is installed as "header.h"
        in $INCLUDEDIR/include/ .
      </td></tr></tbody></table></div><p>
The mode variable mentioned above is used to set the mode bits of the file
after installing.  If this is not wanted, use the {keepmode} attribute.
Example:
</p><pre class="programlisting">
          INSTALL_DATA += myscript.sh {keepmode}
</pre><p>
To use another mode for a specific file add the {mode = 0555} attribute:
</p><pre class="programlisting">
          INSTALL_DATA += myscript.sh {mode = 0750}
</pre><p>
Installing to a remote machine should work, although setting the file mode may
not always work properly, depending on the transfer method used.
</p><p><a name="install-path"></a>
Keep in mind that installation is done from the top directory.
In a child recipe that is located in another directory you need to specify
the path to the file to install relative to the top directory.
Using the $TOPDIR variable and rc-style expansion should work.
Example:
</p><pre class="programlisting">
    # Filenames relative to the child directory
    child_INSTALL_DATA = myscript.sh myicon.png

    # Now add those filenames, relative to the top
    INSTALL_DATA += $TOPDIR/$*child_INSTALL_DATA
</pre><p>
If you hard code the paths from the parent to the files to install,
say by writing <code class="literal">INSTALL_DATA += child/myscript.sh</code>,
then you cannot execute the child recipe by itself (as if it were
a toplevel recipe), since the paths will be wrong.
Using <code class="literal">$TOPDIR</code>, or equivalently
the <code class="literal">topdir</code> function, is the safe way to do so.
</p><h2><a name="id2645611"></a>Uninstall</h2><p>
"aap uninstall" deletes the file that "aap install" has installed.  All the
targets and actions have the same name with "install" replaced with
"uninstall".  The same variables are used.
</p><p>
Files that do not exist are silently skipped.  Files that do exist but cannot
be deleted will cause a warning message.
</p><p>
Sometimes your recipe offers installing optional files.  You probably want to
uninstall those optional files as well, without requiring the user the
specify the same options again.  For this you can set the $UNINSTALL_*
variables.  For example, if you install either the "foo" or "bar" program:
</p><pre class="programlisting">
        :variant What
             foo
                  Target = foo
                  UNINSTALL_EXEC = bar$EXESUF
             bar
                  Target = bar
                  UNINSTALL_EXEC = foo$EXESUF

        :program $Target : $Sources
</pre><h2><a name="id2645629"></a>Installing in non-standard places</h2><p>
  When you need to install in other directories than the ones <span class="application">Aap</span> provides
  there are several alternatives.  First of all, you could use $INSTALL_DATA
  and set $DATADIR to the installation directory.  This works if you are
  otherwise not using $INSTALL_DATA.
</p><p>
  If you have several different directories you could use this scheme:
</p><pre class="programlisting">
  INSTALL_ITEM1 = file1.txt file2.txt
  INSTALL_DIR1 = somewhere
  INSTALL_ITEM2 = file3.txt file4.txt
  INSTALL_DIR2 = elsewhere

  install-local:
      @install_files(_no.INSTALL_DIR1, _no.INSTALL_ITEM1, '0644')
      @install_files(_no.INSTALL_DIR2, _no.INSTALL_ITEM2, '0644')

  uninstall-local:
      @uninstall_files(_no.INSTALL_DIR1, _no.INSTALL_ITEM1)
      @uninstall_files(_no.INSTALL_DIR2, _no.INSTALL_ITEM2)
</pre><p>
  In the Python reference chapter you can find explanations for
  <a href="ref-python.html#python-install-files">install_files()</a> and
  <a href="ref-python.html#python-uninstall-files">uninstall_files()</a>
</p><p>
  You could also add a command to set the protection flags of the installed
  files: <code class="literal">:chmod $INSTALL_DIR1/$*INSTALL_ITEM1</code>.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="user-fetch.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="user-version.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 16. Fetching </td><td width="20%" align="center"><a accesskey="h" href="index.html">
		    Contents</a></td><td width="40%" align="right" valign="top"> Chapter 18. Version Control</td></tr></table></div></body></html>