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 16. Fetching</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-publish.html" title="Chapter 15. Publishing"><link rel="next" href="user-install.html" title="Chapter 17. Installing"></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-publish.html">Prev</a></td><td align="center" class="center">User Manual</td><td align="right" class="right"><a accesskey="n" href="user-install.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="user-fetch"></a>Chapter 16. Fetching</h2></div></div></div><h2><a name="id2641440"></a>Fetching And Updating</h2><p>
A convention about using the "update" and "fetch" targets makes it easy for
users to know how to use a recipe.  The main recipe for a project should be
able to be used in three ways:
</p><div class="orderedlist"><ol type="1"><li><p>Without specifying a target.</p><p>
        This should build the program in the usual way.  Files with a
        "fetch" attribute are obtained when they are missing.
</p></li><li><p>With the "fetch" target.</p><p>
        This should obtain the latest version of all the files for the
        program, without building the program.
</p></li><li><p>With the "update" target.</p><p>
        This should fetch all the files for the program and then build it.
        It's like the previous two ways combined.
</p></li></ol></div><p>
</p><p>
Here is an example of a recipe that works this way:
</p><pre class="programlisting">
        Status = status.txt
        Source = main.c version.c
        Header = common.h
        Target = myprog

        $Target : $Source $Status
            :cat $Status
            :do build $source

        # specify where to fetch the files from
        :attr {fetch = cvs://:pserver:anonymous@myproject.cvs.sourceforge.net:/cvsroot/myproject} $Source $Header
        :attr {fetch = ftp://ftp.myproject.org/pub/%file%} $Status
</pre><p>
Note that the header file "common.h" is given a "fetch" attribute, but it is
not specified in the dependency.  The automatic dependency checking will
notice the file is used and fetch it when it's missing.
</p><p>
When using files that include a version number in the file name, fetching
isn't needed, since these files will never change.  To reduce the overhead
caused by checking for changes, give these files a "constant" attribute (with
a non-empty non-zero value).  Example:
</p><pre class="programlisting">
        PATCH = patches/fix-1.034.diff {fetch = $FTPDIR} {constant}
</pre><p>
To fetch all files that have a "fetch" attribute start <span class="application">Aap</span> with this command:
</p><div class="literallayout"><p>        <strong class="userinput"><code>aap fetch</code></strong><br>
</p></div><p>

When the "fetch" target is not specified in the recipe or its children, it
is automatically generated.  Its build commands will fetch all nodes with
the "fetch" attribute, except ones with a "constant" attribute set
(non-empty non-zero).  To do the same manually:
</p><pre class="programlisting">
        fetch:
                :fetch $Source $Header $Status
</pre><p>
Or use the <a href="ref-commands.html#cmd-fetchall">
<code class="literal">:fetchall</code></a> command.
</p><p>
NOTE: When any child recipe defines a "fetch" target no automatic fetching
is done for any of the recipes.  This may not be what you expect.
</p><p>
When there is no "update" target it is automatically generated.  It will
invoke the "fetch" target and the default target(s) of the recipe.  To do
something similar manually:
</p><pre class="programlisting">
        update: fetch $Target
</pre><h2><a name="id2643053"></a>The Fetch Attribute</h2><p>
The "fetch" attribute is used to specify a list of locations where the file
can be fetched from.  The word at the start defines the method used to
fetch the file:

</p><div class="informaltable"><table border="0"><colgroup><col width="130"><col></colgroup><tbody><tr><td>ftp</td><td>from ftp server</td></tr><tr><td>http</td><td>from http (www) server</td></tr><tr><td>scp</td><td>secure copy</td></tr><tr><td>rcp</td><td>remote copy (aka insecure copy)</td></tr><tr><td>rsync</td><td>remote sync</td></tr><tr><td>file</td><td>local file system</td></tr><tr><td>cvs</td><td>from CVS repository
                        For a module that was already checked out the part
                        after "cvs://" may be empty, CVS will then use the
                        same server (CVSROOT) as when the checkout was
                        done.</td></tr><tr><td>other</td><td>user defined</td></tr></tbody></table></div><p>


These kinds of locations can be used:

</p><div class="literallayout"><p>        ftp://ftp.server.name//full/path/file<br>
        ftp://ftp.server.name/relative/path/file<br>
        http://www.server.name/path/file<br>
        scp://host.name/path:path/file<br>
        rcp://host.name/path:path/file<br>
        rsync://host.name/path:path/file<br>
        cvs://:METHOD:[[USER][:PASSWORD]@]HOSTNAME[:[PORT]]/path/to/repository<br>
        file:~user/dir/file<br>
        file:///etc/fstab<br>
</p></div><p>

For a local file there are two possibilities: using "file://" or "file:".
They both have the same meaning.  "file:" is preferred, because the double
slash is usually used before a machine name: "method://machine/path".  A file
is always local, thus leaving out "//machine" is the logical thing to do.
</p><p>
Note that for an absolute path, relative to
the root of the file system, you use either one or three slashes, but not two.
Thus "file:/etc/fstab" and "file:///etc/fstab" are the file "/etc/fstab".  A
relative path has two or no slashes, but keep in mind that moving the recipe
will make it invalid.  You can also use "file:~/file" or "file://~/file" for a
file in your own home directory, and "file:~jan/file" or "file://~jan/file"
for a file in the home directory of user "jan".
</p><p>
In the "fetch" attribute the string "%file%" can be used where the path of
the local target is to be inserted.  This is useful when several files have a
common directory.  Similarly "%basename%" can be used when the last item in the
path is to be used.  This removes the path from the local file name, thus can
be used when the remote directory is called differently and only the file name
is the same.  Examples:
</p><pre class="programlisting">
        :attr {fetch = ftp://ftp.foo.org/pub/foo/%file%} src/include/bar.h
</pre><p>
Gets the file "src/include/bar.h" from
"ftp://ftp.foo.org/pub/foo/src/include/bar.h".
</p><pre class="programlisting">
        :attr {fetch = ftp://ftp.foo.org/pub/foo/src-2.0/include/%basename%}
                          src/include/bar.h
</pre><p>
Gets the file "src/include/bar.h" from
"ftp://ftp.foo.org/pub/foo/src-2.0/include/bar.h".
</p><h2><a name="id2643187"></a>Defining Your Own Method</h2><p>
To add a new fetch method, define a Python function with the name
"fetch_method", where "method" is the word at the start.  The function will be
called with four arguments:
</p><div class="informaltable"><table border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>dict</td><td>a dictionary with references to all variable scopes (for expert
        users only)</td></tr><tr><td>machine</td><td>the machine name from the url: what comes after the "scheme://"
          upto the first slash</td></tr><tr><td>path</td><td>the path from the url: what comes after the slash after
          "machine"</td></tr><tr><td>fname</td><td>the name of the file where to write the result</td></tr></tbody></table></div><p>

The function should return a non-zero number for success, zero for failure.
Or raise an IOError exception with a meaningful error.
Here is an example:
</p><pre class="programlisting">
    :python
        def fetch_foo(dict, machine, path, fname):
            from foolib import foo_the_file, FooError
            try:
                foo_the_file(machine, path, fname)
            except FooError, e:
                raise IOError, 'fetch_foo() failed: %s' % str(e)
            return 1
</pre><p>
  Note that a version control function overrules a fetch function.  Thus if
  "foo_command()" is defined "fetch_foo" will not be called.
</p><h2><a name="cache-update"></a>Caching</h2><p>
Remote files are downloaded when used.  This can take quite a bit of time.
Therefore downloaded files are cached and only downloaded again when outdated.
</p><p>
The cache can be spread over several directories.  The list is specified
with the $CACHE variable.
</p><p>
NOTE: Using a global, writable directory makes it possible to share the cache
with other users, but only do this when you trust everybody who can login to
the system!  Someone who wants to do harm or make a practical joke could put a
bogus file in the cache.
</p><p>
A cached file becomes outdated as specified with the "cache_update" attribute
or the $CACHEUPDATE variable.  The value is a number and a name.  Possible
values for the name:
</p><div class="informaltable"><table border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>day</td><td>number specifies days</td></tr><tr><td>hour</td><td>number specifies hours</td></tr><tr><td>min</td><td>number specifies minutes</td></tr><tr><td>sec</td><td>number specifies seconds</td></tr></tbody></table></div><p>
The default is "12 hour".
</p><p>
When a file becomes outdated, its timestamp is obtained.  When it differs
from when the file was last downloaded, the file is downloaded again.  When
the file changes but doesn't get a new timestamp this will not be noticed.
</p><p>
When fetching files the cached files are not used (but may be updated).
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="user-publish.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-install.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15. Publishing </td><td width="20%" align="center"><a accesskey="h" href="index.html">
		    Contents</a></td><td width="40%" align="right" valign="top"> Chapter 17. Installing</td></tr></table></div></body></html>