Chapter 14. Publishing

Publishing means distributing a version of your project and giving it a
version number.

	:publish file ...

This uses the "publish" attribute on each of the files.  When it is missing
the "commit" attribute is used.  If both are missing this is an error.

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.

To publish all files with a "publish" attribute use the command:

	aap publish

If the "publish' target is defined explicitly it will be executed.  Otherwise,
all files with the "publish" attribute are given to the ":publish" command,
just like using ":publishall".

:publishall
:publishall {attr = val}
		Publish all the files in the recipe (and child recipes) that
		have the "publish" attribute and changed since the last time
		they were published.
		Note that this doesn't fall back to the "commit" attribute
		like ":publish" does.

Publishing will use all the items in the "publish" attribute.  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.
When publishing fails for one of the sites, it is considered to have failed
for all sites.  When you publish again, uploading is done to all of the
mentioned sites again (this may change in a future version).


CHANGING A URL

When you switch to another server, change the "publish" attribute.  The next
time you invoke Aap will automatically upload all the files to the new server.

If you didn't actually change to another server, but the URL used for the
server changed, invoke Aap once with the "--contents" argument:

      aap publish --contents

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!


DISTRIBUTING GENERATED FILES

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
produced by "autoconf" from "configure.in" can be included.

To avoid these generated results to be generated again when the user runs aap,
specify a special signature file and distribute this signature file together
with the generated files.  For example, suppose you have a directory with
these files you created:

	main.aap
	prog.c

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:

	mysign
	main.aap
	prog.c
	version.c

In the "main.aap" recipe the "signfile" attribute is used for the dependency
that generates version.c:

	version.c {signfile = mysign} : prog.c
		:print char *timestamp = "$TIMESTR"; >! $target

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.


FINALLY

The "finally" target is always executed after the other targets have been
successfully build.  Here is an example that uses the "finally" target to copy
all files that need to be uploaded with one command.

	SOURCE = `glob("*.html")`
	TARGET = remote/$*SOURCE
	CFILE =
	:rule remote/% : %
		CFILE += $source
		:export CFILE

	finally:
		@if CFILE:
			:copy $CFILE ftp://my.org/www

Warning: When the ":copy" 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.