<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 25. Automatic Package Install</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-autoconf.html" title="Chapter 24. Using Autoconf"><link rel="next" href="user-debug.html" title="Chapter 26. Debugging a Recipe"></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-autoconf.html">Prev</a></td><td align="center" class="center">User Manual</td><td align="right" class="right"><a accesskey="n" href="user-debug.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="user-package"></a>Chapter 25. Automatic Package Install</h2></div></div></div><p>
<span class="application">Aap</span> provides a very powerful feature: When a program is required and it does
not exist on the system, it can be installed automatically.
</p><p>
Suppose a recipe specifies that a file is to be uploaded to a server with
secure copy. This requires the "scp" command. When <span class="application">Aap</span> cannot find this
command it offers you the choice to install it. <span class="application">Aap</span> will check what kind of
system you have and find a recipe for it. This recipe is executed and it will
install the package for you. Either by obtaining an executable program or by
fetching the sources and building them. Then the original recipe continues
and uses the "scp" command that has just been installed.
</p><p>
Note: This requires an internet connection!
</p><h2><a name="id2656173"></a>How Does It Work?</h2><p>
The first step is to detect if a required program is present on the system.
This is done internally when "scp" or "cvs" is to be used. You can also check
explicitly in a recipe with the
<a href="ref-commands.html#cmd-assertpkg">:assertpkg</a> command.
This uses the $PATH environment variable. <span class="application">Aap</span> will also look in its own
directory, because this is where previously installed programs are sometimes
located. Also see the
<a href="ref-commands.html#cmd-progsearch">:progsearch</a> command and the
<a href="ref-python.html#python-program-path">program_path()</a>
function.
</p><p>
When the program is not found, the user is asked what is to be done:
</p><div class="literallayout"><p> Cannot find package "scp"!<br>
1. Let Aap attempt installing the package<br>
2. Retry (install it yourself first)<br>
q. Quit<br>
Choice: <br>
</p></div><p>
When the user types "1" the automatic install will be invoked. That will be
explained below. An alternative is to install the package yourself. This is
useful if you know how to do this or when you don't think the automatic
mechanism will work. After the package has been installed you can enter "2"
and <span class="application">Aap</span> continues executing the recipe. The last choice is "a", which means
you give up and abort executing the recipe.
</p><p>
In situations where the package name differs from the command name, or there
are more complicated requirements, you can write a check yourself. When a
package needs to be installed the
<a href="ref-commands.html#cmd-installpkg">:installpkg</a> command can be used to have
<span class="application">Aap</span> install the package.
</p><p>
To install a package automatically <span class="application">Aap</span> will download a recipe and execute
it. To be able to execute the recipe in a proper environment a directory is
created. On Unix this will be "~/.aap/packages/{package-name}/".
The "boot.aap" recipe is downloaded from the A-A-P web site. This uses a
simple PHP script that selects the recipe to use. Example:
</p><pre class="programlisting">
http://www.a-a-p.org/package.php?package=scp&osname=posix
</pre><p>
The downloaded recipe contains further instructions for building and/or
installing the package. This can be anything, thus it is very flexible.
Usually the recipe finds out what kind of system you are using and selects
another recipe to be used for it. Or it uses the standard package mechanism
of your system.
</p><p>
If you are running a BSD system you probably have the BSD ports system
installed (if not, you should install it!). This is a very well maintained
system that takes care of installing almost any software you can think of.
The only disadvantage is that you need to be super-user to use it. <span class="application">Aap</span> will
ask you if you want to do this:
</p><div class="literallayout"><p> The devel/templ port appears to exist.<br>
Do you want to become root and use the port? (y/n) <br>
</p></div><p>
If you respond with "y" you will be asked to type the root password and <span class="application">Aap</span>
will invoke the commands to build and install the BSD port. If you respond
with "n" the generic Unix method will be used (if there is one).
</p><p>
On MS-Windows it will often be possible to download an executable file.
This works without asking questions. Since there is no standard directory for
executables, they are often placed in the <span class="application">Aap</span> directory. You might want to
move them to a directory in $PATH if you want to use them at the command
line.
</p><p>
On generic Unix systems (Posix, Linux) the recipe will attempt to download a
source archive, unpack it and build and install it. This mostly works, but
may fail on some systems. You may have to do some steps manually then,
possibly by running "configure" with specific arguments.
You can find the downloaded files in "~/.aap/packages/{package-name}/".
The <span class="application">Aap</span> message log "AAPDIR/log" may contain hints about what went wrong.
If you know the solution, please report this to the maintainer of the recipe,
so that it can be made to work automatically.
</p><h2><a name="id2657867"></a>Adding Support For a Package</h2><p>
To make it possible to automatically install a package at least one recipe
needs to be written. This recipe is placed on the A-A-P website, so that every
<span class="application">Aap</span> user can find it without typing a URL. You need to e-mail this recipe
to the maintainer of the A-A-P website: webmaster AT a-a-p.org. Chose the
package name carefully, because it must be unique. Mostly it is the name
of the command that was to be executed, such as "scp" or "cvs".
</p><p>
If there is only one recipe it must take care of all systems. This is useful
for a Python module, for example. Or when you want to redirect to another
site where the recipes for this specific package are stored. Here is an
example:
</p><pre class="programlisting">
all install:
:execute generic.aap {fetch = http://www.foo.org/recipes/%file%} $buildtarget
</pre><p>
This recipe redirects everything to another recipe, which is downloaded from
the URL specified with the "fetch" attribute. Note that the "all" and
"install" targets are supported. "all" is used to build the package (as the
current user) and "install" to install it (possibly requiring root
privileges).
</p><h2><a name="id2657891"></a>Installing on MS-Windows</h2><p>
For MS-Windows you often have a different method to install a package.
Especially when the command to be installed is available as one executable
program. Here is an example for the "scp" command:
</p><pre class="programlisting">
# Package recipe for SCP on MS-Windows.
# Maintainer: Bram Moolenaar <Bram@a-a-p.org>
# Last Update: 2003 May 1
install:
# We use the scp command from PuTTY, it appears to work well.
# For info about PuTTY see:
# http://www.chiark.greenend.org.uk/~sgtatham/putty/
:print This will install SCP on MS-Windows.
dir = "`Global.aap_bindir`"
:mkdir {force} $dir
:fetch {fetch = http://the.earth.li/~sgtatham/putty/latest/x86/pscp.exe
ftp://ftp.chiark.greenend.org.uk/users/sgtatham/putty-latest/x86/pscp.exe}
$dir/scp.exe
# That's all, it doesn't need to be installed.
</pre><p>
The actual work is done with one
<a href="ref-commands.html#cmd-fetch">:fetch</a> command. It specifies two locations
where the program can be downloaded. Specifying several locations is useful,
because servers may be down or unreachable from behind a firewall (some
companies disable
access to ftp servers).
</p><p>
Note the use of "Global.aap_bindir". This is the directory where <span class="application">Aap</span>
itself is located with "bin" added. Putting the executable there avoids
asking the user to make a choice. This directory is always searched for
executable commands, it does not have to be in $PATH. Double quotes are used
for the case the directory contains a space (e.g., "C:\Program Files").
</p><h2><a name="id2657921"></a>Building and Installing on Unix</h2><p>
For Unix things are generally a bit more complicated.
The best is to use the package mechanism of the system. Using a BSD port was
mentioned above. Most systems have an equivalent mechanism. When this is
not available you need to fall back to compiling from sources. Here is an
example for "cvs":
</p><pre class="programlisting">
# Package recipe for CVS on Posix.
# Maintainer: Bram Moolenaar <Bram@a-a-p.org>
# Last Update: 2003 May 1
PREFIX =
name = cvs-1.11.5
tarname = $(name).tar.gz
all install:
# There is no check for a BSD port here, because BSD systems should have a
# cvs command already.
# Ask the prefix before compiling.
@if not _recipe.PREFIX:
@_recipe.use_asroot, _recipe.PREFIX = ask_prefix("cvs")
@if not _recipe.PREFIX:
:error No prefix given
# Should use a port recipe for this...
@if buildtarget == "all":
# Get the sources and build the executable.
# This can be done by an ordinary user.
:print This will build "cvs" on Posix machines.
:update get-tar
:sys tar xfz $tarname
:cd $name
:sys ./configure --prefix=$PREFIX
# The GSSAPI stuff breaks the build for me on FreeBSD. If we can find
# a solution it can work on other systems..
:cat config.h | :eval re.sub('#define HAVE_GSSAPI\\b', '', stdin) >! config.h
:sys make
@else:
# Install the executable.
# This may need to be done by root.
:cd $name
@if _recipe.use_asroot:
# Assume the directories already exist...
:asroot make $buildtarget
@else:
:sys make $buildtarget
get-tar {virtual}: $tarname {fetch = http://ftp.cvshome.org/$name/%file%}
</pre><p>
Note that this recipe specifically mentions the version "1.11-5". This is a
bit unusual. Better is to refer to the latest stable version. Unfortunately,
for CVS the proper link is not available. This means the recipe has to be
updated every time a new stable version is released.
</p><p>
The user has the choice of installing CVS for himself or for everybody on the
system. <span class="application">Aap</span> has a build-in function for this: <a href="ref-python.html#python-ask-prefix">ask_prefix()</a>. When the
user is root it will return "1" and "/usr/local/" without asking, assuming the
super-user will want to install for everybody (why else would he be doing this
as root?). Normal users will be asked to make a choice:
</p><div class="literallayout"><p> Select where to install cvs:<br>
1. become root and install in "/usr/local/"<br>
2. become root and install in specified location<br>
3. install in your home directory "/home/mool/"<br>
4. install in a specified location<br>
a. abort<br>
choice: <br>
</p></div><p>
It is obvious what the choices will do. The "cvs" recipe then continues to
obtain the sources, using ":update get-tar" to allow using a cached file. The
archive is unpacked with "tar" and "configure" is run before invoking "make".
This is the standard way how most Unix programs are build.
</p><p>
There is one extra step: While testing the recipe it was discovered that the
configuration makes a mistake and defines "HAVE_GSSAPI", but that doesn't
work. The recipe modifes "config.h" to fix this. This is not a nice
solution, but it makes the building work. This kind of porting would actually
better be done in a separate recipe. And by reporting the problem to the
maintainers of the CVS configure script.
</p><p>
When the recipe is invoked with the "install" target the choice to install as
root or not is used. This was stored in "_recipe.use_asroot" to avoid having
to make the choice again when invoked a second time (the recipe is first
invoked with "all" to build the program as the current user and then with
"install" to do the actuall install, possibly as super-user). The
<a href="ref-commands.html#cmd-asroot">:asroot</a>
command passes the command to a separate shell with root privileges. The
user is asked confirmation for every executed command for safety.
</p><h2><a name="id2658246"></a>Installing a Specific Package</h2><p>
This automatic package installation system is a nice way of installing a
program without the need to know how it's done. You can also use it to
install a package directly:
</p><div class="literallayout"><p> % <strong class="userinput"><code>aap --install scp</code></strong><br>
</p></div><p>
This will attempt to install the "scp" package on your system. It works just
like when <span class="application">Aap</span> discovered that the "scp" command was needed for executing a
recipe.
</p><p>
Obviously not just any package is available. Quite a few currently, but
hopefully this will grow when people submit their packages. When a package
cannot be found you get an error message:
</p><div class="literallayout"><p> % <strong class="userinput"><code>aap --install foobar</code></strong><br>
Aap: Creating directory "/home/mool/.aap/packages/foobar"<br>
Aap: Entering directory `/home/mool/.aap/packages/foobar'<br>
Aap: Attempting download of "http://www.a-a-p.org/package.php?package=foobar&osname=posix"<br>
Aap: Downloaded "http://www.a-a-p.org/package.php?package=foobar&osname=posix" to "boot.aap"<br>
Aap: Error in recipe "/home/mool/.aap/packages/foobar/boot.aap" line 3: Sorry, package 'foobar' is not available.<br>
%<br>
</p></div><h2><a name="id2658290"></a>Cleaning Up</h2><p>
Currently <span class="application">Aap</span> does not delete the files downloaded and generated while
installing a package. This is useful especially when something fails, so that
you can read the log file "AAPDIR/log" and/or do part of the installation
manually. But this does mean disk space is used.
</p><p>
In the comments produced while installing the package you can see which
directory is used for the files. This depends on the system and environment
variables. It should be one of these:
</p><table class="simplelist" border="0" summary="Simple list"><tr><td> $HOME/.aap/packages </td></tr><tr><td> $HOME/aap/packages </td></tr><tr><td> $HOMEDRIVE$HOMEPATH/aap/packages </td></tr><tr><td> C:/aap/packages </td></tr></table><p>
It is fairly safe to delete the "packages" directory and everything it
contains.
</p><p>
In case you are really low on disk space, you might want to check the <span class="application">Aap</span>
install directory for any programs that you no longer want to use. This is
only relevant on MS-Windows.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="user-autoconf.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-debug.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 24. Using Autoconf </td><td width="20%" align="center"><a accesskey="h" href="index.html">
Contents</a></td><td width="40%" align="right" valign="top"> Chapter 26. Debugging a Recipe</td></tr></table></div></body></html>
