<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 15. Publishing</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-variant.html" title="Chapter 14. Variants"><link rel="next" href="user-fetch.html" title="Chapter 16. Fetching"></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-variant.html">Prev</a></td><td align="center" class="center">User Manual</td><td align="right" class="right"><a accesskey="n" href="user-fetch.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="user-publish"></a>Chapter 15. Publishing</h2></div></div></div><p>
Publishing means distributing the files of your project.
This is a generic mechanism. You can use it to maintain a web site or to
release a new version of your application.
</p><p>
The most straightforward way to publish a file is with the
<code class="literal">:publish</code> command:
</p><pre class="programlisting">
:attr {publish = ftp://ftp.my.org/upload/%file%} myfile
:publish myfile
</pre><p>
This uses the "publish" attribute on each of the files. When the "publish"
attribute is missing the "commit" attribute is used. If both are missing this
is an error.
</p><p>
When a file didn't change since the last time it was published, it won't be
published again. This works with signatures, like building a target. The
remote file is the target in this case. But <span class="application">Aap</span> won't read the remote file
to compute the signature, it will remember the signature from when the file
was last uploaded (otherwise checking for outdated files would be slow).
</p><p>
In the example %file% is used. This is replaced with the name of the file
being published, including the directory. This means you can use the same
attribute for several files:
</p><pre class="programlisting">
Files = myfile yourfile hisfile
:attr {publish = ftp://ftp.my.org/upload/%file%} $Files
:publish $Files
</pre><p>
Including the directory is sometimes not what you want. To only use the
last part of the path use %basename%.
</p><pre class="programlisting">
Files = one/myfile two/yourfile three/hisfile
:attr {publish = ftp://ftp.my.org/common/%basename%} $Files
:publish $Files
</pre><p>
The three files will be uploaded to the "common" directory. The directory
names "one", "two" and "three" will not be used on the ftp server.
</p><p>
To publish all files with a "publish" attribute start <span class="application">Aap</span> like this:
</p><div class="literallayout"><p> <strong class="userinput"><code>aap publish</code></strong><br>
</p></div><p>
If the "publish' target is defined explicitly it will be executed. Otherwise,
all files with the "publish" attribute are given to the
<a href="ref-commands.html#cmd-publish">:publish</a>
command, just like using the
<a href="ref-commands.html#cmd-publishall">:publishall</a> command.
</p><p>
The "publish" attribute may consist of several items. Publishing will use
all these items. This means a file can be distributed to several sites at
once. This is unlike fetching, which stops as soon as the file could be
obtained from one of the items.
</p><p>
When publishing fails for one of the sites, e.g., because the server is down,
this is remembered. When you publish again, uploading is done only for that
site. The destinations for which pusblishing worked will be skipped then.
</p><h2><a name="id2641828"></a>Using Secure Copy</h2><p>
Uploading files requires write access to the server. There are several
methods for this, but some have the disadvantage that your password is sent as
normal text over the internet. Or someone in between can change the files
that you send out. There is one that provides sufficient security: scp
or secure copy.
</p><p>
To publish a file to a server through secure copy use a URL in this form:
</p><pre class="programlisting">
:publish file {publish = scp://myname@the.server.com/dir/%file%}
</pre><p>
"myname" is your login name on the server "the.server.com". The "file" will
be written there as "dir/file", relative to your login directory.
</p><p>
This requires the "scp" command, which is not a standard item. If it does not
appear to exist then Aap will offer you to install it for you. If the
automatic mechanism fails you will have to install it yourself. You might
also want to do this if you have specific preferences for how the scp command
is to be installed (versions of scp exist with different kinds of encryption).
</p><p>
To avoid having to type a password each time you need to use public keys. For
MS-Windows you can find information here:
</p><div class="literallayout"><p> <a href="http://the.earth.li/~sgtatham/putty/0.53b/htmldoc/Chapter8.html" target="_top"><br>
http://the.earth.li/~sgtatham/putty/0.53b/htmldoc/Chapter8.html<br>
</a><br>
</p></div><p>
This is for the PuTTY version of scp, which is what Aap installs for you if
you let it. For Unix try <strong class="userinput"><code>man ssh-keygen</code></strong>. Use "SSH protocol
version 2" if possible.
</p><p>
You can specify the command to be executed with the <code class="literal">$SCP</code> variable,
see <a href="ref-variables.html#var-scp">the reference manual</a>.
Example:
</p><pre class="programlisting">
SCP = scp -i c:/private/keyfile
</pre><h2><a name="id2642030"></a>Using Another Method</h2><p>
Using "rsync" has an advantage if you have files with only a few changes. The
rsync program will only transfer the differences. This adds a bit of
overhead to find out what changed, thus it's a bit slower when copying whole
files.
</p><p>
<span class="application">Aap</span> uses the same secure channel as with "scp" by default. This can be
changed with the <code class="literal">$RSYNC</code> variable, see
<a href="ref-variables.html#var-rsync">the reference manual</a>.
</p><p>
If your server does not support "scp", you might want to use "rcp". However,
this is insecure, information is transferred unencoded over the internet and
making a connection is not secure. Only use this when "scp" is not possible.
</p><p>
Using "rcp" means changing the "scp://" part of the URL to "rcp://".
The $RCP variable holds the name of the command, see
<a href="ref-variables.html#var-rcp">the reference manual</a>.
</p><p>
You can also use "ftp". Some web servers require this, even though ftp
sends your password as plain text over the internet, thus it is insecure.
<span class="application">Aap</span> uses the Python ftp library, thus an external command is not needed
and there is no variable to specify the command.
</p><h2><a name="id2642076"></a>Changing A Url</h2><p>
When you switch to another server you need to change the "publish" attribute.
The next time you invoke <span class="application">Aap</span> for publishing it will automatically upload all
the files to the new server.
</p><p>
If you didn't actually change to another server, but the URL used for the
server changed, invoke Aap once with the "--contents" argument:
</p><div class="literallayout"><p> <strong class="userinput"><code>aap publish --contents</code></strong><br>
</p></div><p>
This will cause only files that changed to be published. It avoids that all
the files with a changed "publish" attribute are published again. It will
still upload files that you changed since the last upload and newly added
files. But be careful: files that you once uploaded, deleted from the list of
files and now added will NOT be uploaded!
</p><h2><a name="id2642107"></a>Distributing Generated Files</h2><p>
When publishing a new version of an application, you might want to include a
number of generated files. This reduces the number of tools someone needs to
use when installing the application. For example, the "configure" script
that "autoconf" produces from "configure.in" can be included.
</p><p>
To avoid these generated results to be generated again when the user runs aap,
explicitly specify a signature file to be used and distribute this signature
file together with the generated files. For example, suppose you have a
directory with these files you created:
</p><div class="literallayout"><p> main.aap<br>
prog.c<br>
</p></div><p>
Additionally there is the file "version.c" that is generated by the "main.aap"
recipe. It contains the date of last modification. To avoid it being
generated again, include the "mysign" file in the distribution. The files to
be distributed are:
</p><div class="literallayout"><p> mysign<br>
main.aap<br>
prog.c<br>
version.c<br>
</p></div><p>
In the "main.aap" recipe the "signfile" attribute is used for the dependency
that generates version.c:
</p><pre class="programlisting">
version.c {signfile = mysign} : prog.c
:print char *timestamp = "$TIMESTR"; >! $target
</pre><p>
The result is that "version.c" will only be generated when "prog.c" has
changed. When the "signfile" attribute would not have been used, "version.c"
would have been generated after unpacking the distributed files.
</p><h2><a name="id2642216"></a>Copying All Files At Once</h2><p>
The "finally" target is always executed after the other targets have been
successfully built. Here is an example that uses the "finally" target to copy
all files that need to be uploaded with one command.
</p><pre class="programlisting">
Source = *.html
all: remote/$*Source {virtual} {remember}
CFile =
:rule remote/% : %
_recipe.CFile += $source
finally:
@if _recipe.CFile:
:copy $_recipe.CFile ftp://my.org/www
</pre><p>
Warning: When the
<a href="ref-commands.html#cmd-copy">:copy</a> command fails, aap doesn't know the
targets were not
made properly and won't do it again next time. Using the "publish" attribute
works better.
</p><h2><a name="publish-images"></a>Publishing images for HTML files</h2><p>
When publishing HTML files you most likely also want to publish the image
files referenced by them. You can use a wildcard to select the images files,
but this may include images that are not actually used. You can explicitly
specify the images, but if you miss one your locally tested web site won't
work properly on the server.
</p><p>
A good solution is to parse the HTML files and figure out what images are used
in them. However, only image files that can be found locally should be
included, not ones that are on other web sites. The
<a href="ref-python.html#python-get-html-images">get_html_images()</a> function can
be used for this, as shown in an example:
</p><pre class="programlisting">
Files = index.html
contact.html
forward.html
Files += `get_html_images(Files)`
:attr {publish = scp://user@ftp.foo.org/public_html/%file%} $Files
all: publish
</pre><p>
Note that this still isn't perfect. Only images in plain "IMG" tags will be
found and only when they use a relative path name. Thus images from
Javascript or PHP code will not be included.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="user-variant.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-fetch.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. Variants </td><td width="20%" align="center"><a accesskey="h" href="index.html">
Contents</a></td><td width="40%" align="right" valign="top"> Chapter 16. Fetching</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6d417e36f6bb1154f4c003e6717e298
>
files
>
162
