.\"  $HeadURL$ $LastChangedRevision$
.\" vim: filetype=nroff
.\"
.TH ADEBUN 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
adebun \- release builder
.br
.ne 5
.SH SYNOPSIS
.B adebun
\*[ade_standard_synopsis_component]
[
.B \-\-author\-name=\fIname\fR
] 
[
.B \-\-author\-email=\fIaddr\fR
] 
[
.B \-\-package\-name=\fIpkg\fR
] 
[
.B \-o
.I file
|
.B \-\-output\-file=\fIfile\fR
] 
[
.B \-m
.I cmd
|
.B \-\-make=\fIcmd\fR
] 
.I srcdir
.br
.ne 5
.SH DESCRIPTION
.B Adebun
prepares .tar.gz files for release from a source directory. It
does this according to the following procedure:
.IP 1 10
Copy 
.I srcdir
to a temporary location.
.IP 2 10
Substitute occurrences of the following symbols in
the temporary copy of the sources for the text 
described:
.RS 10
.TP 25
.fam C
.\" the next line contains a backslash to prevent the releaser (adebun)
.\" from substituting it. We really do want this text here!
ADE_APP_TO\KEN_RELEASE_ID
.fam T
release id, as specified in the doc/ChangeLog file under
.I srcdir\fR,
.TP
.fam C
.\" same here!
ADE_APP_TO\KEN_RELEASE_YEAR
.fam T
The year of release, as determined by current time
.TP
.fam C
.\" same here!
ADE_APP_TO\KEN_AUTHOR_NAME
.fam T
The name of the author, as specified by command line options,
.TP
.fam C
.\" same here!
ADE_APP_TO\KEN_AUTHOR_EMAIL
.fam T
the email address of the author, as specified by command
line options.
.TP
.fam C
.\" same here!
ADE_APP_TO\KEN_RELEASE_YEAR_MAN
.fam T
The date of release, as determined by the current time, in
the format required for the
.B \.TH
directive (see 
.B man\fR(7)
in manual page sources).
.RE
.\" This is to continue the indented paragraph. The '.RE'
.\" seems to make it fall back to the left more than I 
.\" wanted it to.
.IP "" 10
It is not an error for there to be no occurrences of the
symbols which are specified by options, but it is an error
for there to be occurrences of these symbols without the corresponding
options.
.IP 3 10
Clean the temporary copy of the sources by running the command
.B make clean distclean
in the top directory of the temporary copy. No output is produced
from this stage. 
.IP 4 10
Pack the remaining files up using
.B tar\fR(1), creating the file 
.I pkg\fB-\fIreleaseid\fB.tar.gz\fR, 
where
.I pkg
is determined from the last component of the directory referred
to by
.I srcdir\fR.
.IP 5 10
Delete the temporary copy of the sources.
.ne 5
.SH CONFIGURATION
Make sure that your top-level Makefile (see
.B make\fR(1))
includes targets
.B clean
and
.B distclean\fR.
Often the target 
.B distclean
depends on the 
.B clean
target. Its effect should be to 
remove any build configuration files or cache files.
.PP
.B Adebun
expects that the first line of the file
.I srcdir\fB/doc/ChangeLog
be of the format:
.IP
.B Release \fIrelease-id\fB (\fIdate\fB)
.PP
If it is not in this format
.B adebun
will complain.
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP 25
.B \-\-author\-email=\fIaddr
Sets the author's email address to 
.I addr\fR.
.TP
.B \-\-author\-name=\fIname
Sets the author's name to 
.I name\fR.
.TP
.B \-m \fIcmd\fR, \fB\-\-make=\fIcmd\fR
Specify the location of 
.B make\fR(1), 
used when running
.B make clean distclean\fR.
.TP
.B \-o \fIfile\fR, \fB\-\-output\-file=\fIfile
Specify the name of the output file. The default is
.I pkg\fB-\fIreleaseid\fB.tar.gz\fR,
where
.I pkg
is the last component of the source directory hierarchy,
as defined by the command line argument
.I srcdir\fR.
.TP
.B \-\-package\-name=\fIpkg
Specify an alternative name for the packaged software. The
default is the last component of the source directory.
.br
.ne 5
.SH EXIT STATUS
On success
.B adebun
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
The following command executed one directory above \(oqfoo' would
generate a file \(oqfoo-1.0.tar.gz':
.IP
.nf
.fam C
.B { 
.B \ \ \ \ echo "Release 1.0 ($(date))"
.B \ \ \ \ echo
.B \ \ \ \ cat foo/doc/ChangeLog
.B } > /tmp/blah
.B mv /tmp/blah foo/doc/ChangeLog
.B adebun foo
.fam T
.fi
.br
.PP 
If you were already in the directory \(oqfoo', and the sources contained
the above optional symbols, and the above commands to prepare the
ChangeLog had been executed, then this might be useful:
.IP
.nf
.fam C
.B adebun -o ../foo-1.0.tgz --author-email=blobber@blobber.com \(rs
.B --author-name=\(dqBobby Blobber\(dq .
.fam T
.fi
.br
.ne 5
.SH CAVEATS
Don't try to create the tar file inside the source directory; the
output file is opened before the source hierarchy is copied.
.PP
Regardless of the name of the output specified with the
.B \-o
option,
the output file will contain paths based on the package name
(in turn determined by the
.B \-\-package\-name
option or the last component of the directory referenced
by
.I srcdir\fR) and the release id.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B adebun\fR.
.br
.ne 5
.SH SEE ALSO
tar(1), make(1), perl(1), ade-config(1), date(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1997-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]