Merged silc_1_0_branch to trunk.

[silc.git] / apps / autodist / doc / autodist.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename autodist.info
@settitle autodist
@setchapternewpage off
@c %**end of header

@include version.texi

@copying

This manual is for SILC Autodist (version @value{VERSION},
@value{UPDATED}), a program which is used to manage and create source
distributions.

Copyright @copyright{} 2004 - 2005 Pekka Riikonen, SILC Project

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @acronym{GNU} Free Documentation License,
Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
(a) below.  A copy of the license is included in the section entitled
``@acronym{GNU} Free Documentation License.''

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and
modify this @acronym{GNU} Manual, like @acronym{GNU} software.  Copies
published by the Free Software Foundation raise funds for
@acronym{GNU} development.''
@end quotation
@end copying

@dircategory Software development
@direntry
* autodist: (autodist).         Managing and creating source distributions.
@end direntry

@dircategory Individual utilities
@direntry
* makedist: (autodist)Invoking makedist.          Creating distribution
@end direntry

@titlepage
@title SILC Autodist
@subtitle For version @value{VERSION}, @value{UPDATED}
@author Pekka Riikonen
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex
@node Top
@comment  node-name,  next,  previous,  up
@top SILC Autodist

@insertcopying

@menu
* Introduction::                Purpose of Autodist
* Integrating Autodist::        Integrating Autodist into your project
* Invoking Autodist::           Running Autodist
* Examples::                    Examples using Autodist

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Motivation::                  Reasons for using Autodist

Integrating Autodist

* Creating distdir::            Creating distributions directory
* autodist.conf::               Configuring Autodist
* Creating new distribution::   Adding new distribution
* Distribution file format::    Detailed document for distfile format
* configure.ad files::          configure script for creating configure.ac
* Makefile.ad files::           Makefile.ad for creating Makefile.am
* Other .ad files::             Other files with .ad suffix
* Distdefines::                 Using distdefs in files

Invoking Autodist

* Preparing source tree::       Preparing source tree with Autodist
* Creating distribution::       Creating distribution with Autodist

Examples

* Single distribution tree::    Single distribution example
* Multiple distribution tree::  Multiple distributions example

@end detailmenu
@end menu

@end ifnottex


@node Introduction
@chapter Introduction

The Autodist is a source distribution management system that allows
powerful mechanisms to define what is included in and excluded from a
distribution, and what license the distribution is released under.  It is
also used to create the actual distribution source packages.  Autodist
allows distribution management in file, directory and file content level.
Different distributions may include different portions of files, for
example, excluding certain features from certain distributions.  It is
always guaranteed that anything not defined for the distribution, is
removed automatically (files, file content, directories), thus ensuring
that nothing is accidentally included in the distribution.

The Autodist creates 'Makefile.am' files from 'Makefile.ad' files and
'configure.ac' file from one or more 'configure.ad' files.  Any other file
ending with '.ad' suffix will also be processed.  The processed file will
have the '.ad' suffix removed (@pxref{Preparing source tree, , , , }).
Autodist also creates and packages the distribution using common GNU
distribution creation process, specificly `make dist'.  Autodist, however,
controls this process and during packaging phase the Autodist processes
all files in the distribution (other than '*.ad' files, which has already
been processed earlier by Autodist).  The resulted package is a processed
source distribution package, processed according to the rules specified
in the distribution file(s) (@pxref{Creating distribution, , , , }).

Any file in the source tree may use distdefs (distribution defines (@pxref{Distdefines, , , , })) which are defined in the distributions.  When distribution
is packaged only the files, directories and file content that is either
outside of any distdef, or inside the defined distdefs will be included
in the distribution.  Any other file, directory or content in the file
will be removed.  It is guaranteed, if a file, a directory or a piece of
file content is not inside a defined distdef it will not be delivered to
the distribution.

Any file, 'Makefile.am', 'configure.ac', or source file processed with
Autodist is always compliant with the tools needed to process them.  All
files can also be processed with the corresponding tools even before
processing them with Autodist.  This makes it possible, for example, to
compile sources before they have been processed, and undefined lines
are removed.  The distdefs are respected in source files by the
preprocessor.

Autodist is not a binary packaging system.  It is specificly used to
create source distributions.  A binary packaging system, however can be
hooked to the distribution creation process, if needed.

@menu
* Motivation::                  Reasons for using Autodist
@end menu


@node Motivation
@section Reasons for using Autodist

Autodist is closely related to the Autoconf and Automake tools, and
complements the features Autoconf and Automake provides.  It is especially
targeted into circumstances where multiple distributions are created from
one source tree.  The Autoconf and Automake environment is mainly designed
for one distribution (one application) per one source tree situations.
Autodist provides mechanisms to create all kinds of distributions that can
be created from one source tree.  To be able to use Autodist, the Autoconf
and Automake must be installed into the system (@pxref{Integrating Autodist, , , , }).
Autoconf version must be at least 2.52g.

Small software projects usually do very well with Autoconf and Automake
and their distribution management features.  Often these projects do not
need Autodist, though they can benefit from it.  However, if your software
project is large, you need to create multiple distributions from one source
tree, you have complex licensing terms for different distributions, you
have different target users or customers that may require different
feature set or licenses in different distributions, you have need to
continue concurrent development in the main source tree and still be able
to create stable distributions, and/or you have need to control file
content in different distributions (to avoid distributing code or features
that aren't supposed to be distributed, or to avoid leaking information
to your competitors on what new features you are working on), then Autodist
is a tool you may find usefull.

The motivation behind Autodist stems from need to be able to create
multiple distributions from one large source tree in a precise and
controllable manner, and guarantee that anything that is not part of the
distribution is removed from the distribution.  The Autoconf and Automake
provides mere basic control what is included in and excluded from
distributions and how the distributions are created.  They also do not
provide mechanism to define different licensing conditions for different
distributions, or changing the license automatically for different user
or customer purposes.  Many large software projects, companies and
corporations have commonly been using Autoconf and Automake tools, but
have had the need to create their own ad-hoc mechanisms to control
distribution creation.  The Autodist attempts to provide a tool that any
size software project can effectively use to manage their distributions.

Without a tool like Autodist, large software projects usually has to be
split into separate source trees, which may not always be possible because
they may share large portions of common code (which may further make
concurrent development of the applications hard), or multiple Autoconf and
Automake environments (multiple configure scripts) needs to be created
in one source tree.  In this case the source tree usually gets very
complicated and controlling what is compiled and what is included in
distributions becomes harder, especially when different parts code is shared
between applications and libraries.


@node Integrating Autodist
@chapter Integrating Autodist

Integrating Autodist into existing software project can be a very simple
task or a fairly complicated task.  It depends on the size and complexity
of the software project.  Generally speaking, integrating Autodist into
software project is fairly straightforward process:

1. The distributions directory and 'default' distribution are created

2. The 'configure.ad' is created

3. If needed, 'Makefile.ad' file(s) are created

After this the Autodist can already be used to prepare the source tree
for configuration and compilation (@pxref{Preparing source tree, , , , }).
Adding a new distribution would then allow the actual distribution
packaging also.

If the software project has had own ad-hoc distribution system already in
place, it may take some work to move from that system into the Autodist.
If there are multiple applications and distributions created from the
source tree, the distributions and distribution defines for them need to
be created.  While this may be unthankful job, it only needs to be done
once.

Integrating Autodist into a new software project is a very simple task as
renaming 'configure.ac' and possibly 'Makefile.am' files are not required,
as they may not exist yet.


@menu
* Creating distdir::            Creating distributions directory
* autodist.conf::               Configuring Autodist
* Creating new distribution::   Adding new distribution
* Distribution file format::    Detailed document for distfile format
* configure.ad files::          configure script for creating configure.ac
* Makefile.ad files::           Makefile.ad for creating Makefile.am
* Other .ad files::             Other files with .ad suffix
* Distdefines::                 Using distdefs in files
@end menu


@node Creating distdir
@section Creating distributions directory

The distributions directory is 'distdir', which is expected to be
located in the root of the source tree.  This directory will hold all
the distribution files, and the Autodist configuration file 'autodist.conf' (@pxref{autodist.conf, , , , }).
If this directory does not exist it can be created with the Autodist.

@example
  autodist -i
@end example

This will create the 'distdir' and copy the default 'autodist.conf'
configuration file and the 'default' distribution into the directory.
The 'default' distribution will be used by default by the Autodist
unless other distribution is specified.

After this the Autodist has effectively been integrated into the
software project.  However, usually after this, one would create new
distributions, the 'configure.ad' and possibly 'Makefile.ad' file(s).
Without 'configure.ad' file a distribution package cannot be created.
However, even without 'configure.ad' file the source tree can be
prepared for configuration and compilation (@pxref{Preparing source tree, , , , }).

@menu
* autodist.conf::               Configuring Autodist
@end menu


@node autodist.conf
@section Configuring Autodist

After the Autodist has been integrated into the software by creating
the 'distdir', the 'autodist.conf' configuration file was added to the
'distdir' also.  Usually software projects will want to modify some of
the 'autodist.conf' options, mainly specifying the distdef prefix.

The 'autodist.conf' is a text file.  The following options are available
in 'autodist.conf':


@example
DISTPREFIX=""
@end example

By default the distdef prefix is '_DIST_'.  To add own software package
specific prefix the 'DISTPREFIX' can be defined.

Example:
@example
DISTPREFIX="SILC"
@end example

Will set the distdef prefix as 'SILC_DIST_'.


@example
DISTDEFS="distdefs.h"
@end example

The 'DISTDEFS' option specifies the file name of the distdef header file
which Autodist will create.  The software project should '#include' the
header file in order for the preprocessor to respect the distdef
conditionals (@pxref{Distdefines, , , , }).  By default the file name
is 'distdefs.h' and is created at the root of source tree.  Other location
may be specified if needed.

Example:
@example
DISTDEFS="include/distdefs.h"
@end example


@example
ACLOCAL="aclocal"
@end example

The 'ACLOCAL' specifies the location of the 'aclocal' tool.  If Autodist
should not run 'aclocal' this option may be removed or set to empty value.
User need to then run it manually.


@example
AUTOHEADER="autoheader"
@end example

The 'AUTOHEADER' specifies the location of the 'autoheader' tool.  If
Autodist should not run 'autoheader' this option may be removed or set
to empty value.  User need to then run it manually.

@example
AUTOCONF="autoconf"
@end example

The 'AUTOCONF' specifies the location of the 'autoconf' tool.  If
Autodist should not run 'autoconf' this option may be removed or set
to empty value.  User need to then run it manually.


@example
AUTOMAKE="automake -a -c"
@end example

The 'AUTOMAKE' specifies the location of the 'automake' tool.  If
Autodist should not run 'automake' this option may be removed or set
to empty value.  User need to then run it manually.  By default, the
'-a'  and '-c' options are given to 'automake' to add any missing required 
files.


@example
LIBTOOLIZE="libtoolize --automake -c"
@end example

The 'LIBTOOLIZE' specifies the location of the 'libtoolize' tool.
This option should be removed or ste to empty value if 'libtool' is not
used in the source tree.


@example
MAKE=make
@end example

The 'MAKE' specifies the location of the 'make' program.  This option must
be set to valid value in order to create distributions.


@menu
* Creating new distribution::   Adding new distribution
@end menu


@node Creating new distribution
@section Creating new distribution

After the Autodist has been integrated into the software project by
creating the 'distdir' and 'default' distribution, the source tree
can be prepared for configuration and compilation (@pxref{Preparing source tree, , , , }).  However, the 'default' distribution should be used only as
a development distribution.  Usually it is used to prepare the raw source
tree (such as a tree just checkout
from CVS) for configuration and compilation.  By default, the 'default'
distribution cannot be packaged.  However, if the software project is
small (one distribution), it may be convenient to edit the 'default'
distribution to be as the distribution that is packaged from the source
tree.  In software project where multiple distributions are created using
the 'default' only as a development distribution is recommended.  The
real distributions should be defined as separate distributions.

Creating a new distribution is a simple process.  Each distribution
is placed in the 'distdir' and the file name of the distribution file is
used to reference to it.  By default, the distribution name is the
file name of the distribution file.  The actual distribution file is
a simple text file with various directives that define the distribution.

If the 'default' distribution is used as a development distribution it
might be desired to inherit some or all of the created distributions in
it, so that development becomes possible with the 'default' distribution.
Adding 'inherit' directive into the 'distdir/default' will inherit the
specified distribution.


@menu
* Distribution file format::    Detailed document for distfile format
@end menu


@node Distribution file format
@section Distribution file format in detail

The distribution file, or distfile from now on, defines your distribution,
distribution defines, options, included and excluded files and
directories, license, and additional processing.  Each distribution is
defined in a separate file and the distributions are referenced by
their file name.

The distfile is a text file that contains various directives that define
the actual distribution.  Lines starting with '#' are considered comments
and are ignored.


@section Directive: name <name>

The 'name' directive defines the name of the distribution.  It is optional
directive, and if omitted the distribution name will be the name of the
distfile.

Example:
@example
name FOO Application
@end example

Will set your distribution name as 'Foo Application'.


@section Directive: package <package>

The 'package' directive defines the name of the distribution package.  It is
optional directive, and if omitted the distribution package name will
be the name of the distribution, if defined, or if omitted, then the name
of the distfile.  If this directive is omitted then normal GNU convention
is used to decide the package name, derived from the distribution name.

Example:
@example
package foo-client
@end example

Will create distribution packages named, for example, as
'foo-client-1.0.tar.gz'.


@section Directive: bug-report <email address>

The 'bug-report' directive can be used to define the email address where
the bug-reports for the distribution should be sent.  The directive is
optional.  The 'bug-report' email address will be set for the Autoconf
which will deliver it via AC_INIT macro.


@section Directive: license <filename>

The 'license' directive can be used to define the license file for the
distribution.  This directive is optional.  The license file will be
copied into the distribution in the name 'COPYING'.  If the 'COPYING'
file already exist it will be replaced.

Example:
@example
license license/GPL
@end example

Will include the file 'license/GPL' into the distribution in the file
name 'COPYING'.


@section Directive: license-header <current-license> <new-license>

The 'license-header' can be used to re-license your files into a new
license.  This directive is optional.  There may be zero or more
'license-header' directives in distribution.  The 'license-header'
directive will compare the license header that usually appear at the
start of a file to the <current-license>.  If it matches it will
be replaced with the <new-license>.  The license header in the file
will be replaced and the file will have effectively been re-licensed.

Example:
@example
license-header license/BSD-header license/GPL-header
@end example

Will replace all appearances of the license header in 'license/BSD-header'
file to the license header in 'license/GPL-header' in any file in the
distribution.  Note that, the header change will be performed when
the distribution is packaged (@pxref{Creating distribution, , , , }).

With 'license-header' directive you may initially set your files in the
source tree into what ever license you prefer.  However, if you need to
re-license parts of the source tree in certain distributions the
'license-header' will achieve this automatically.  For example, suppose
one wants to create two different versions of a library distribution, with
different feature sets, in two different licenses.

There are several limitations in the current implementation of Autodist
with the 'license-header' directive:

First limitation is that the header files must have equal amount of lines.
If the new header file has fewer lines that the current header file, all
of the lines from the current header will not be replaced.  If the new header
has fewer lines, empty lines must be added to it.  If the new header file
has more lines than the current header file, the extra lines will not appear
in the replaced header.  Basic rule is to always make sure the header file
has equal amount of lines in them.

Second limitation is in indentation of the header files.  It is suggested,
though not mandatory, that the header files have the same indentation as
is commonly used in the source tree; if the license header text in a file
starts at the second character instead of at the start of the line, then
the header file should start the license text at the second character also.
If same indentation is not used the appearance of the replaced header
may not be perfect.  While this is a cosmetic issue, one still to remember.

Example current header:
@example
--- Start example
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; version 2 of the License.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
--- end example
@end example

Example new header:
@example
--- Start example
  All rights reserved.

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the conditions listed in the
  COPYING file are met.



--- end example
@end example

In this example, if the text in the current header file is found in any
file in the distribution it will be replaced with the new header file.
Notice that, both header files has same amount of lines (8 lines).

Note that, the current header must match exactly the header used in 
files.  Otherwise the replacement will not be complete.


@section Directive: inherit <distfile>

The Autodist provides inheritance of distributions.  The 'inherit'
directive is used to define the distribution which will be inherited
into the distribution.  The <distfile> specifies the name of the
inherited distribution.  If the distribution cannot be inherited Autodist
will give an error.

The 'inherit' will inherit the following information from the distribution:
distdefs, undefines, includes, excludes and noprocess.  Other information
will not be inherited.  If the inherited distribution inherits other
distributions, they will also be inherited automatically.  User should be
careful when inheriting distributions as it may be possible to create an
infinite recursion.  The Autodist would allow for this and not detect this
error.  Zero or more 'inherit' directives may be set for distribution.

Example:
@example
inherit common
inherit client
inherit toolkit
@end example

Will inherit distributions 'common', 'client' and 'toolkit' into this
distribution.  All distdefs, undefines, includes, excludes and noprocesses
from these distributions are now also part this distribution.


@section Directive: define <symbol>

The 'define' directive is used to define the distdef symbols for the
distribution.  This directive is optional, however, all distributions
should define at least one distdef so that the distribution may be
controlled with the distdef conditionals in files in the source tree (@pxref{Distdefines, , , , }).  By default, the distdef prefix is '_DIST_'.  Many
software projects will want to set their own prefix for the distdefs
for consistency.  The prefix may be defined in the 'autodist.conf' file
(@pxref{autodist.conf, , , , }).

Example:
@example
define _DIST_FOO
define _DIST_FEATURE_X
define _DIST_LIBRARY_Y
@end example

Will define the following distdefs for the distribution: '_DIST_FOO',
'_DIST_FEATURE_X' and '_DIST_LIBRARY_Y'.  These distdefs may then be
used in the source tree and source code to control what is included in
or excluded from this distribution.


@section Directive: undef <symbol>

The 'undef' directive may be used to explicitly undefine a distdef.
When inheriting distributions it may be desired to be able undefine
certain distdefs.  This directive is optional.

Example:
@example
undef _DIST_FEATURE_Y
@end example

Will undefine '_DIST_FEATURE_Y' distdef.  This distdef will not be part
of this distribution anymore, even if it is defined in some inherited
distribution.


@section Directive: option <option> [...]

The 'option' directive is used to define various options for the
distribution.  The options can change the behavior of the distribution.
This directive is optional.  One or more options may be defined in one
'option' directive.  Zero or more 'option' directives may be set for
distribution.  The following options are available.

@example
template
@end example

When set, the distribution is a template distribution.  Templates are
special distributions which cannot be prepared or packaged with Autodist.
Templates can only be inherited.  Usually, templates are used to define a
common template distribution for other distributions.  Templates may set
distdefs, undefines, includes and excludes.  A large software project
could have several distributions that share a common base.  In this case
defining the common base as a template distribution and then inheriting
that distribution makes it easier to manage the distfiles.

@example
no-dist
@end example

Distributions with the 'no-dist' option are similar to templates, except
that they can be prepared with Autodist, but they cannot be packaged.
These are usually used as a common development distribution, such as the
'default' distribution created with 'autodist -i'.

@example
no-inherit
@end example

If this option is set to normal distributions or distributions with
'no-dist' option, the distribution cannot be inherited.  For template
this option has no effect.  If distribution with this option is inherited
the Autodist will give an error.


@section Directive: include <source> [<destination>]

The 'include' directive can be used to include files or directories into
the distribution.  Sometimes it may be desired to specify included
files and directories in distribution instead of Makefile.am and
EXTRA_DIST, especially if there are many distributions that need to
include specific files and directories.  While it would be possible
to define them in Makefile.ad and use distdef conditionals to define
which will be included in which distribution, if there are many different
distributions it may pollute the Makefile.ad unnecessarily.

This directive is optional.  The <source> may be a single file, a  single
directory or a regular expression which will match several files and/or
directories.  The <destination> is optional.  If it is omitted then
the <source> will be copied into the same location in the distribution.
If the <destination> is provided the <source> will be copied into the
specified location.

Example:
@example
include apps/foobar/README README
include lib/libfoo
include lib/libfoobar lib/foobarlib
include doc/foo*
include scripts/foobar.sh foo.sh
@end example

Will include the file 'apps/foobar/README' into the top distribution
directory in the name 'README', the directory 'lib/libfoo' into same
location in distribution, the directory 'lib/libfoobar' into
'lib/foobarlib' changing the name of the directory into 'foobarlib',
the files and directories that match 'doc/foo*' into the same locations
in distribution, and finally the 'scripts/foobar.sh' into the top
distribution directory changing the name of the file into 'foo.sh'.

Note that, the 'include' directives will be processed by the Autodist
only when the distribution is packaged (@pxref{Creating distribution, , , , }).  When preparing the source
tree for configuration and compilation (@pxref{Preparing source tree, , , , })
the 'include' directives are ignored.  This is same behavior as with
Makefile.am's EXTRA_DIST.

If the included file or directory does not exist the Autodist will
give an error and stop the distribution creation.  If the destination
file exist, it will be replaced with the included file.  If the
destination directory already exists, the contents of the source
directory will be copied into the directory.  Note that, the directory
will not be copied into the directory; if the <destination> is specified,
also the name of the <source> file or directory must be specified,
otherwise the 'include' will change the name into the one specified.

Example:
@example
include lib/libfoo lib
@end example

In this example the 'lib/libfoo' will be included as 'lib'.  If the 'lib'
already exists, this effectively copies the contents of the 'lib/libfoo'
into 'lib'.  In order to include the directory with same name, the
name must be specified.

Example:
@example
include lib/libfoo lib/libfoo
include lib/foobar new_lib/foobar
@end example

This will include the 'lib/libfoo' into 'lib/libfoo' in distribution,
and 'lib/foobar' into 'new_lib/foobar' in distribution.


@section Directive: exclude <filename> [...]

The 'exclude' directive can be used to exclude files and directories from
the distribution.  This directive is optional.  This directive is
processed before processing the 'include' directive.  The <filename>
can be a single file, a single directory or a regular expression that
will match several files and/or directories.

Example:
@example
exclude README
exclude doc/client*
@end example

This will exclude the file 'README' and anything that match 'doc/client*'.


@section Directive: noprocess <filename> [...]

The 'noprocess' directive can be used to tell Autodist specificly not to
process a file.  The Autodist will not process the file during
preparation or during distribution packaging.  This directive is optional.
One or more file can be specified in the 'noprocess' directive.  Zero or
more 'noprocess' directives can be used in distribution.  The <filename>
can be a single file, a single directory or a regular expression that
will match several files and/or directories.  If directory is specified
then all files inside the directory will not be processed.

Example:
@example
noprocess autodist.texi
@end example

Autodist will not process 'autodist.texi' file.

Note that, 'noprocess' directive cannot be used to disallow processing
of any file with '.ad' suffix.


@section Directive: pre-hook <filename> [...]

The 'pre-hook' directive can be used define additional scripts that
will be run before the source tree is prepared.  This directive is
optional.  One or more scripts may be defined in one 'pre-hook' directive.
Zero or more 'pre-hook' directives may be set for distribution.  The
'pre-hook' hook will be run immediately after invoking Autodist to start
preparing the source tree for configuration and compilation (@pxref{Preparing source tree, , , , }).

The scripts will get three (3) command line arguments when Autodist
executes the script: distribution name, distribution version and package
name of distribution.  The script may use these arguments if it needs them.


@section Directive: post-hook <filename> [...]

The 'post-hook' directive can be used define additional scripts that
will be run after the source tree is prepared.  This directive is
optional.  One or more scripts may be defined in one 'post-hook' directive.
Zero or more 'post-hook' directives may be set for distribution.  The
'post-hook' hook will be run immediately after the Autodist has finished
preparing the source three for configuration and compilation (@pxref{Preparing source tree, , , , }).  The Autodist will exit after it has run the
'post-hook' scripts.

The scripts will get three (3) command line arguments when Autodist
executes the script: distribution name, distribution version and package
name of distribution.  The script may use these arguments if it needs them.


@section Directive: pre-dist-hook <filename> [...]

The 'pre-dist-hook' directive can be used define additional scripts that
will be run when Autodist has started distribution creation.  This directive
is optional.  One or more scripts may be defined in one 'pre-dist-hook'
directive.  Zero or more 'pre-dist-hook' directives may be set for
distribution.  The 'pre-dist-hook' hook will be run immediately after
the Autodist has created the distribution directory but has not yet
started any distribution processing.

The scripts will get four (4) command line arguments when Autodist
executes the script: distribution name, distribution version, package
name of distribution and destination distribution directory name.  The
script may use these arguments if it needs them.


@section Directive: post-dist-hook <filename> [...]

The 'post-dist-hook' directive can be used define additional scripts that
will be run when Autodist has finished distribution processing.  This
directive is optional.  One or more scripts may be defined in one
'post-dist-hook' directive.  Zero or more 'post-dist-hook' directives may
be set for distribution.  The 'post-dist-hook' hook will be run immediately
after the Autodist has finished processing the destination distribution
directory but has not yet created the distribution package.

The scripts will get four (4) command line arguments when Autodist
executes the script: distribution name, distribution version, package
name of distribution and destination distribution directory name.  The
script may use these arguments if it needs them.


@section Example distfile

The following is a simple distfile example.  The example assumes that the
distdefs prefix is 'SILC'.

@example
# SILC Client distribution
name SILC Client
package silc-client
bug-report silc-client-bugs@@silcnet.org
inherit common
inherit platform-unix
inherit platform-win32
define SILC_DIST_CLIENT
define SILC_DIST_CLIENTLIB
define SILC_DIST_IRSSI
undef SILC_DIST_MPI
exclude doc/draft*
pre-hook scripts/client-pre-run
post-dist-hook scripts/client-post-dist-run
post-dist-hook scripts/client-post-dist-kludge
@end example

@menu
* configure.ad files::          configure script for creating configure.ac
@end menu


@node configure.ad files
@section configure.ad files

Autodist creates 'configure.ac' file from the 'configure.ad' file.  The
'configure.ad' file is a rather normal 'configure.ac' except that it accepts
also Autodist macros.  Autodist also supports configure script fragments,
also named as 'configure.ad'.  Any 'configure.ad' file in the source tree
can be incorporated into the the top 'configure.ad' file.  Sometimes it may
be useful to split a large configure script into smaller fragments.
Especially in multi distribution system where certain libraries or features
can be excluded from certain distributions it may be useful to handle
their configuration from a configure fragment.  If the library is
excluded then also its configuration can be excluded.

If the software project already has a 'configure.ac' or 'configure.in'
file, the 'configure.ad' can be created by simply renaming the current
file to 'configure.ad'.  In this case the current configure script
must be edited to support Autodist.  This is done by replacing the
'AC_INIT' to 'AD_INIT'.  After specifying the 'AD_INIT' as the first
macro in the 'configure.ad', the Autodist support has been fully
integrated into the software project.

If your software project is going to use configure fragments, then
also Autodist macro 'AD_INCLUDE_CONFIGURE' must be used.  Autodist will
automatically combine the fragments with the top 'configure.ac' script.
To exclude a 'configure.ad' fragment from a distribution use the distdef
conditionals inside the 'configure.ad' fragment file.  If the distdef is
not defined the fragment will be excluded automatically.

The following macros are available in current Autodist version.

@defmac AD_INIT

The 'AD_INIT' macro is used in place of Autoconf macro 'AC_INIT'.  The
'AD_INIT' must be the first macro in the 'configure.ad', just like the
'AC_INIT' macro in 'configure.ac'.  The AD_INIT macro is used to deliver
the distribution names, distribution version, package name and bug-report
email address to the 'configure.ac' file that Autodist will create.
The 'AC_INIT' macro must not be used in 'configure.ad' file.

This macro is mandatory and Autodist will exit with error if it is not
specified in 'configure.ad'.  This macro has no arguments.
@end defmac


@defmac AD_INCLUDE_CONFIGURE

This macro is used to tell Autodist that it should include any other
'configure.ad' fragment that is found from the source tree into the
top 'configure.ad' file.  Note that, the 'configure.ad' fragments will
be incorporated at the location where this macro is used in the
'configure.ad'.  Usually this macro is placed just before the Autoconf
macro 'AC_OUTPUT'.  This macro has no arguments.

Note that, the 'configure.ad' fragments are not real full featured
configure scripts.  They must not use 'AD_INIT', 'AD_INCLUDE_CONFIGURE',
'AC_INIT' or any other initialization macros.

@end defmac

@menu
* Makefile.ad files::           Makefile.ad for creating Makefile.am
@end menu


@node Makefile.ad files
@section Makefile.ad files

Autodist creates 'Makefile.am' files from 'Makefile.ad' files.  A software
project do not need to use 'Makefile.ad' files if there is no need to
use distdef conditionals inside makefiles.  Usually a multi distribution
software project, however will need to define certain things to different
distributions.  In these cases 'Makefile.ad' file needs to be created.

Even though it would be possible to use distdef conditionals also inside
'Makefile.am' files, Autodist does not process 'Makefile.am' files when
preparing the source tree for configuration and compilation (@pxref{Preparing source tree, , , , }).  Thus, the prepared environment would not be
identical to the created distribution package (when the 'Makefile.am'
will be processed), and configuration and compilation would be inconsistent.
Basic rule is, if you need distdefs (@pxref{Distdefines, , , , }) inside
makefiles, put them inside 'Makefile.ad' file.


@menu
* Other .ad files::             Other files with .ad suffix
@end menu


@node Other .ad files
@section Other .ad files

Any file in the source tree can have the '.ad' suffix appended.  Autodist
will process any file that has the suffix when the source tree is
prepared for configuration and compilation (@pxref{Preparing source tree, , , , }).  If the files have distdef conditionals the Autodist will process them.
The files will have the '.ad' suffix removed.

Basic rule is, if you need to process some file when preparing the
source tree for configuration and compilation, add '.ad' suffix to it.
Distdefs (@pxref{Distdefines, , , , }) can be used in any file in source
tree but without '.ad' suffix Autodist will not process those files during
preparation.  They will be processed when creating the distribution package.
If you need processed files during configuration or compilation then they
need to have '.ad' suffix.

@menu
* Distdefines::                 Using distdefs in files
@end menu


@node Distdefines
@section Using distribution defines (distdefs)

Distribution defines, or distdefs from now on, are used to define inside
a file what will be included in the distribution.  Distribution may define
many different distdefs, for example, based on feature sets, platforms, or
for other similar reasons.  If distdef is not defined for the distribution
but is used in a file, anything inside the distdef in that file will be
removed when the distribution is packaged (@pxref{Creating distribution, , , , }).  This guarantees that only the files, directories and file content
(such as source code) that is supposed to be delivered with the distribution
are delivered.  Delivering files or code accidentally in the distribution
cannot happen.

All other files, except files ending with '.ad' suffix are processed for
distdefs only when the distribution is packaged.  Files ending with '.ad'
suffix are processed for distdefs when preparing the source tree for
configuration and compilation (@pxref{Preparing source tree, , , , }).

By default the distdefs are named '_DIST_XXX', where 'XXX' is the name of
distdef.  However, many projects will want to define their own prefix
for distdefs in the 'autodist.conf' configuration file (@pxref{autodist.conf, , , , }).
In the following examples a prefix 'SILC' is used, hence the prefix for 
the distdefs are 'SILC_DIST_'.

The basic format for the distdefs are as follows:

@example
#ifdef SILC_DIST_DEFINE
#endif SILC_DIST_DEFINE

#ifndef SILC_DIST_DEFINE
#endif SILC_DIST_DEFINE

#ifdef SILC_DIST_DEFINE
#else !SILC_DIST_DEFINE
#endif SILC_DIST_DEFINE

#ifndef SILC_DIST_DEFINE
#else SILC_DIST_DEFINE
#endif SILC_DIST_DEFINE
@end example

This format should be used only in non-source files, as for example C and
C++ compilers will not like this format inside a file.  In source files
a compiler friendly format, defined below, should be used.

@example
#ifdef SILC_DIST_DEFINE
#endif /* SILC_DIST_DEFINE */

#ifndef SILC_DIST_DEFINE
#endif /* SILC_DIST_DEFINE */

#ifdef SILC_DIST_DEFINE
#else /* !SILC_DIST_DEFINE */
#endif /* SILC_DIST_DEFINE */

#ifndef SILC_DIST_DEFINE
#else /* SILC_DIST_DEFINE */
#endif /* SILC_DIST_DEFINE */
@end example

Note that, only the format defined above is supported.  Other more complex
use of the preprocessor directives such as using '&&' and '||' in the '#ifdef'
or '#ifndef' are not supported, and neither is '#elif'.  Also note, that in
the compiler friendly format the name of the distdef in comments and the
use of '!' character in the '#else' branch of '#ifdef' are mandatory.  Also
note, that the distdef conditionals must be placed at the start of the line,
they must not be indented.

The following example shows the use of non-source format:

@example
SUBDIRS =                        \
#ifdef SILC_DIST_SERVER
       server                    \
       server-foobar             \
#endif SILC_DIST_SERVER
#ifndef SILC_DIST_CLIENT
       tests                     \
#endif SILC_DIST_CLIENT
#ifdef SILC_DIST_TOOLKIT
       toolkit                   \
       toolkit-docs              \
#else !SILC_DIST_TOOLKIT
       doc                       \
       lib                       \
#ifdef SILC_DIST_CLIENT
       client                    \
#endif SILC_DIST_CLIENT
#endif SILC_DIST_TOOLKIT
@end example

Say, in this example, your distribution has the SILC_DIST_CLIENT and
SILC_DIST_SERVER defined, but not the SILC_DIST_TOOLKIT, the end result
would be:

@example
SUBDIRS =                        \
       server                    \
       server-foobar             \
       doc                       \
       lib                       \
       client                    \
@end example

The lines defined specificly for the SILC_DIST_TOOLKIT, which in our
example was not defined, were removed.  Also lines that specificly
expected certain distdefs not to be defined ('#ifndef') were removed.
(Note the last remaining '\' in example above would be removed by the
Autodist automatically to avoid errors with Automake.)

The following example shows the use of source code format:

@example
  initialize_lib();
#ifdef SILC_DIST_MPI
  init_mpi();
  mpi = mpi_alloc();
#else /* !SILC_DIST_MPI */
  init_gmp();
#endif /* SILC_DIST_MPI */

#ifndef SILC_DIST_FOOBAR
  foobar_replacement();
#else /* SILC_DIST_FOOBAR */
  real_foobar();
#endif /* SILC_DIST_FOOBAR */
@end example

Say, you have both SILC_DIST_MPI and SILC_DIST_FOOBAR defined, the end result
would be:

@example
  initialize_lib();
  init_mpi();
  mpi = mpi_alloc();

  real_foobar();
@end example

Even before processing the source files with Autodist, the preprocessor 
will respect the preprocessor directives if the code use '#include' to 
include the distdef header file created by the Autodist (see 
'autodist.conf' (@pxref{autodist.conf, , , , })).  When the distribution 
is packaged (@pxref{Creating distribution, , , , }) the Autodist will 
process the files, and will remove any line not defined to be included.  
The preprocessor directives will also be removed.

Because the software project includes the header file with '#include' the 
distdef header file needs to be present in the distribution, unless it is 
placed inside some other '#ifdef' conditional.  If the distribution is
prepared but not compiled (it is packaged after preparation without
compilation) then including the distdef header in the source is not 
necessary.  Including it then in the distribution is not necessary either.
 
The software project should not use the same name space that distdef
conditionals use for other than distribution usage.  The Autodist will
process any line that uses the formats above and has the specified prefix
(eg. 'SILC_DIST_') in those lines.  Using same prefix for other purposes
will produce unexpected results and invalid distributions.

The following suffixes will be considered as source files by the Autodist:

@example
    .c
    .C
    .cc
    .cp
    .cpp
    .CPP
    .cxx
    .CXX
    .c++
    .m
    .h
    .H
    .hh
@end example

Using distdefs in any other file must follow the non-source format.


@node Invoking Autodist
@chapter Invoking Autodist

The Autodist has two basic functions:

    1. Preparing source tree for configuration and compilation (@pxref{Preparing source tree, , , , })

    2. Creating distribution packages (@pxref{Creating distribution, , , , })

The 'autodist' accepts the following options:

@table @samp

@item -h
@itemx --help
Prints the help for the Autodist and exits.

@item -V
@itemx --version
Prints version number and exits.

@item -v
@itemx --verbose
Verbosely report processing.

@item -d
@itemx --distdir <dir>
Search distributions from <dir> instead of default 'distdir'.

@item -s
@itemx --distdefs [<dist>]
Prints distribution defines of <dist> and exits.

@item -i
@itemx --init
Initializes Autodist environment.  Creates the default distribution
directory 'distdir', 'autodist.conf' configuration file and the
default distribution 'default', then exits.

@item -m
@itemx --makedist
Creates and packages distribution

@itemx --gzip
Create package compressed with gzip (default)

@itemx --bzip2
Create also package compressed with bzip2

@itemx --compress
Create also package compressed with compress

@itemx --zip
Create also package compressed with zip


@end table

@menu
* Preparing source tree::       Preparing source tree with Autodist
* Creating distribution::       Creating distribution with Autodist
@end menu


@node Preparing source tree
@section Preparing source tree for configuration and compilation

Before distribution can be created from the source tree, the source tree
must be prepared for configuration and compilation.  If your project is
not using Autodist, then you would do this by running perhaps 'aclocal',
'autoconf', 'autoheader' and 'automake' tools manually, or you would run an
'autogen.sh' script that prepares your raw source tree.  With Autodist
this process is performed by Autodist, and running these tools manually
or using 'autogen.sh' script is not necessary.

By default the 'autodist.conf' (@pxref{autodist.conf, , , , }) has defined 
the tools that will be run by the Autodist when preparing the source tree.  
These are 'aclocal', 'autoheader', 'autoconf', 'automake' and 
'libtoolize'.  If you do not whish that Autodist runs some or any of these 
tools automatically, do not set them in the 'autodist.conf'.  You would 
then need to run them manually. However, this is not recommended.  If you 
need to run additional preparation scripts you may set your scripts either 
in the 'pre-hook' and/or 'post-hook' where you can run what ever 
additional processing you may need to prepare your source tree.

By default the Autodist creates a 'default' distribution when you
initialize your project by running 'autodist -i'.  The 'default'
distribution should be used when you are developing in your source
tree.  By default, the 'default' distribution cannot be packaged,
however, if your project creates only one distribution you may find
it more convenient to define your distribution inside the 'default'
distribution and allow it to be packaged also.  If your source tree
will create multiple distributions, the 'default' should be used only
as development distribution.  You would use it when you, for example,
checkout your source tree from CVS and prepare it for configuration
and compilation.  To prepare your source tree with the 'default'
distribution run Autodist without any arguments.

@example
  autodist
@end example

The Autodist will prepare your source tree.  After that you may run
'./configure' and continue to compile with 'make'.

If you do not whish to use the 'default' distribution, or you whish
to do the development in a tree specificly prepared for some specific
distribution, or you are preparing to create a new distribution package,
you will need to run the Autodist with the distribution you whish to
prepare.

@example
  autodist example-distribution 1.0.3
@end example

This prepares your source tree for 'example-distribution' of version
'1.0.3'.  After that you may run './configure' and continue to compile
with 'make'.  If the version is omitted the version will be '0.0'.

Note that, running Autodist for preparation merely prepares your source
tree for the distribution, it does not create an actual distribution
package.  When preparing source tree for configuration and compilation
the Autodist will process any file that ends with '.ad' suffix.  It will
process all 'configure.ad' and 'Makefile.ad' files for that distribution.
When you run './configure' your tree will be configured for that
distribution, and when you compile with 'make' it will compile for that
distribution.

However, the source files, or any other file (except files ending with
'.ad' suffix) are not processed by the Autodist.  When compiling
your sources the preprocessor, however, will respect your distdef
conditionals inside your source files if you include the distdef header
file.  This way, even the compiled binaries will be compiled for that
distribution, even though the source files has not yet been processed
by the Autodist.  Rest of the files in the distribution will be processed
when you create the actual distribution package.  It is guaranteed that
the distribution you have prepared will behave in your source tree exactly
the same way as if it was already packaged with Autodist (providing that
you remember to include the distdef header file in your code).

@menu
* Creating distribution::       Creating distribution with Autodist
@end menu


@node Creating distribution
@section Creating distribution package(s)

Before creating a new distribution package, you will need to prepare
the source tree for the distribution you want to create.  After preparing
your source tree you will be ready to create a new distribution.  The
Autodist package provides a simple helper script 'makedist' that may
be used to create the distribution.  However, if you whish, you may
run the Autodist yourself, as the 'makedist' will call Autodist anyway.

To create a new distribution for the distribution you have prepared for
run makedist.

@example
  makedist
@end example

This will run the Autodist and create a new distribution package that
is archived with 'tar' and compressed with 'gzip'.  If you whish to
create packages also compressed with 'bzip2', 'compress' and/or 'zip'
you may give one or all of the following options:

@example
  makedist --bzip2 --compress --zip
@end example

This example would create, in addition of 'tar.gz' package, also a
'tar.bz2', 'tar.Z' and '.zip' packages.  Current version of Autodist does
not support archiving with 'shar'.

If you whish to run additional processing for your distributions when
they are being packaged you may set 'pre-dist-hook' and/or 'post-dist-hook'
in your distribution file.  Also note that any hooks provided by Automake
in Makefiles will be run in normal manner.

For additional help, you may give:

@example
  makedist --help
@end example


@node Examples
@chapter Examples

@menu
* Single distribution tree::    Single distribution example
* Multiple distribution tree::  Multiple distributions example
@end menu

@node Single distribution tree
@section Single distribution tree example, start to finish

Lets suppose you have a simple source tree with one application,
called 'foozbar' you whish to release.  While you would probably suffice
using Autoconf and Automake features you may still use Autodist.

First, you create the default 'distdir' into your software package:

@example
  autodist -i
@end example

Then, you create the 'configure.ad' file from your existing 'configure.ac'
or 'configure.in' file.  If you don't have configure script written yet,
please refer to the Autoconf manual.  In the 'autodist.ad' you add as
first macro in the file:

@example
  AD_INIT
@end example

Then, you create distribution file for your application:

@example
# Foozbar distribution
name Foozbar
package foozbar
bug-report foozbar-bugs@@foo.z.bar
define _DIST_FOOZBAR
@end example

This distribution file go into 'distdir/foozbar'.

And there you go.  You have succesfully integrated Autodist into your
source tree.  If you need to do development and you whish to use the
'default' distribution for that, you should inherit the new 'foozbar'
distribution in it.  Add the following line in 'distdir/default':

@example
  inherit foozbar
@end example

After that, you can prepare the source tree for configuration and
compilation by giving:

@example
  autodist
@end example

After this command you can give './configure' and 'make'.

If you want to do development directly in a tree prepared for the
'foozbar' distribution, or you are ready to start creating a new
distribution package, you give:

@example
  autodist foozbar 1.0
@end example

After this command you can give './configure' and 'make'.

To create the distribution package, you will give:

@example
  makedist
@end example

The end result will be a 'foozbar-1.0.tar.gz' package.


@node Multiple distribution tree
@section Multiple distribution tree example, start to finish

Lets suppose you have a source tree from which you create multiple
distributions, say three.  If you really have a such source tree you
must have by now noticed the difficulty of maintaining such a source tree
and problems with controlling the distributions.  Maybe you have sufficed
with Autoconf and Automake, or perhaps you have created your own scripts
that carry out the kludges.  No more, for Autodist is here.

First, you integrate Autodist into your tree by creating the distributions
directory 'distdir':

@example
  autodist -i
@end example

Then, you create the 'configure.ad' file from your existing 'configure.ac'
or 'configure.in' file.  If you don't have configure script written yet,
please refer to the Autoconf manual.  In the 'autodist.ad' you add as
first macro in the file:

@example
  AD_INIT
@end example

You then continue with creating the distribution files for your three
distributions.  Let's name them 'foozbar', 'libfoozbar' and 'nomad'.
We will also create a common template that all distributions inherit.

@example
# Foozbar distribution
name Foozbar
package foozbar
bug-report foozbar-bugs@@foo.z.bar
inherit common
define _DIST_FOOZBAR
@end example

@example
# libfoozbar distribution
name libfoozbar
bug-report libfoozbar-bugs@@foo.z.bar
inherit common
define _DIST_LIBFOOZBAR
@end example

@example
# Nomad distribution
name Nomad
package nomad-the-server
bug-report nomad-bugs@@foo.z.bar
inherit common
include doc/nomad
define _DIST_NOMAD
define _DIST_NOMAD_LIB
undef _DIST_CRYPTO
@end example

@example
# Common template
define _DIST_DOC
define _DIST_LIB
define _DIST_MATH
define _DIST_CRYPTO
define _DIST_UNIX
define _DIST_MACOSX
define _DIST_WIN32
@end example

You put the distribution files in the 'distdir' directory.  In addition
you will be doing development in the source tree using the 'default'
distribution, you will add the new distributions to the 'distdir/default':

@example
inherit foozbar
inherit libfoozbar
inherit nomad
@end example

To prepare the source tree for configuration and compilation you would
simply give:

@example
autodist
@end example

This will prepare your source tree for configuration and compilation.  Since
the 'default' distribution inherits all distributions your development
source tree will have all of them included.  If you do not want to do this
then don't inherit them in the 'default', but run the autodist specificly
for the distributions, for example:

@example
autodist foozbar
@end example

Since all the distributions inherit the 'common' distribution they get
all the distdefs that the 'common' defines.  In this example various distdefs
has been defined.  You would use them in your code and in your makefiles
to control various things.  For example, let's say the 'common' distdefs
control what directories distributions have.  An example 'Makefile.ad'
file:

@example
SUBDIRS =                       \
#ifdef _DIST_LIB
       lib                      \
#endif _DIST_LIB
#ifdef _DIST_DOC
       doc                      \
#endif _DIST_DOC
@end example

Perhaps the 'Makefile.ad' in 'lib' subdirectory could define something
like this:

@example
SUBDIRS =                       \
        util                    \
#ifdef _DIST_MATH
        mathlib                 \
#endif _DIST_MATH
#ifdef _DIST_CRYPTO
        cryptolib               \
#endif _DIST_CRYPTO
#ifdef _DIST_NOMAD_LIB
        nomadlib                \
#endif _DIST_NOMAD_LIB
#ifdef _DIST_LIBFOOZBAR
        foozbarlib               \
#endif _DIST_LIBFOOZBAR
@end example

Since the 'nomad' distribution undefined the '_DIST_CRYPTO' distdef it
would not have the 'cryptolib' in its distribution.  Clearly Nomad
don't need it.  In addition of using the distdefs just in the makefiles
you may want to use them in the source code as well:

@example
     ...some code...

#ifdef _DIST_MATH
  /* Initialize math library */
  math_init();
#endif /* _DIST_MATH */

     ...some code...
@end example

After an intensive development period you're ready to create new releases.
Let's say you're going to release all distributions:

First you release Foozbar 0.5.1:

@example
autodist foozbar 0.5.1
makedist --bzip2
@end example

The end result is two files: 'foozbar-0.5.1.tar.gz' and
'foozbar-0.5.1.tar.bz2'.

Then you continue with libfoozbar and Nomad:

@example
autodist libfoozbar 1.0.5
makedist

autodist nomad 2.0
makedist
@end example

The end results are: 'libfoozbar-1.0.5.tar.gz' and 'nomad-2.0.tar.gz'.

@page
@contents
@bye