.\"  $HeadURL$ $LastChangedRevision$
.\"
.TH ADEREL 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
aderel \- release builder
.br
.ne 5
.SH SYNOPSIS
.B aderel
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel\fR
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
] 
[
.B \-\-author\-name=\fIname\fR
] [
.B \-\-author\-email=\fIaddr\fR
] [
.B \-\-package\-name=\fIpkg\fR
] 
[
.B \-f
.I file
|
.B \-\-output\-file=\fIfile\fR
] 
[
.B \-m
.I cmd
|
.B \-\-make=\fIcmd\fR
] 
.I srcdir
.br
.ne 5
.SH DESCRIPTION
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of 
.B aderel\fR.
.PP 
.B Aderel
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 (aderel)
.\" from substituting it. We really do want this text here!
SP\PSYM_RELEASE_ID
.fam T
release id, as specified in the doc/ChangeLog file under
.I srcdir\fR,
.TP
.fam C
.\" same here!
SP\PSYM_RELEASE_YEAR
.fam T
The year of release, as determined by current time
.TP
.fam C
.\" same here!
SP\PSYM_AUTHOR_NAME
.fam T
The name of the author, as specified by command line options,
.TP
.fam C
.\" same here!
SP\PSYM_AUTHOR_EMAIL
.fam T
the email address of the author, as specified by command
line options.
.TP
.fam C
.\" same here!
SP\PSYM_RELEASE_YEAR_MAN
.fam T
The date of release, as determined by the current time, in
the format 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 occurences without using the corresponding
option to supply a value for it.
.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,
such as produced by GNU configure, or
.B adeconf\fR(1).
.PP
.B Aderel
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 aderel
will complain.
.br
.ne 5
.SH OPTIONS
.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 \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B aderel
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP
.B \-f \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 \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B aderel
uses.
.TP
.B \-\-package\-name=\fIpkg
Specify an alternative name for the packaged software. The
default is the last component of the source directory.
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.br
.ne 5
.SH EXIT STATUS
On success
.B aderel
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
.TP 25 
.B PATH
.B Aderel
uses  
.B PATH
to locate
.B perl\fR(1).
.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 { echo "Release 1.0 (`date`)"; echo; cat foo/doc/ChangeLog; } > /tmp/blah
.B cat /tmp/blah > foo/doc/ChangeLog
.B rm /tmp/blah
.B aderel 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 aderel -f ../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 \-f
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 SEE ALSO
adeconf(1), tar(1), make(1), perl(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
.PP
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; either version 2 of the License, or
(at your option) any later version.
.PP
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.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.