-----------------------------------------------------------------------------
Copyright (c) 2001-2007 OpenSS7 Corporation
Copyright (c) 1997-2000 Brian F. G. Bidulock
All Rights Reserved.
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.
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.
-----------------------------------------------------------------------------
U.S. GOVERNMENT RESTRICTED RIGHTS. If you are licensing this Software on
behalf of the U.S. Government ("Government"), the following provisions apply
to you. If the Software is supplied by the Department of Defense ("DoD"), it
is classified as "Commercial Computer Software" under paragraph 252.227-7014
of the DoD Supplement to the Federal Acquisition Regulations ("DFARS") (or any
successor regulations) and the Government is acquiring only the license rights
granted herein (the license rights customarily provided to non-Government
users). If the Software is supplied to any unit or agency of the Government
other than DoD, it is classified as "Restricted Computer Software" and the
Government's rights in the Software are defined in paragraph 52.227-19 of the
Federal Acquisition Regulations ("FAR") (or any successor regulations) or, in
the cases of NASA, in paragraph 18.52.227-86 of the NASA Supplement to the FAR
(or any successor regulations).
-----------------------------------------------------------------------------
Commercial licensing and support of this software is available from OpenSS7
Corporation at a fee. See http://www.openss7.com/
-----------------------------------------------------------------------------
Automake has many targets, not all of which are obvious to the causal user.
In addition, OpenSS7 automake files have additional rules added to make
maintaining and releasing a package somewhat easier. This list of targets
provides some help with what targets can be invoked, what they do, and what
they hope to acheive. The available targets are as follows:
User Targets:
-------------
The following are normal targets intended to be invoked by installers of the
package. They are concerned with compiling, checking the compile,
installing, checking the installation, and uninstalling the package.
[all]:
Compiles the package. This si performed after configuring the source
with 'configure'. We provide a makefile stub so that if the package has
not had autoreconf run (such as when checked out from CVS, the package
will attempt to run 'autoreconf -fiv'.
All openss7 packages are configured without maintainer mode and without
dependency tracking by default. This speeds compiling of the package for
one-time builds. This also means that if you are developing using the
source package (edit-compile-test cycle), changes made to source files
will not cause the automatic rebuilding due to dependencies. There are
two ways to enable dependency tracking: specify --enable-maintainer-mode
to 'configure'; or, specify --enable-dependency-tracking to 'configure'.
I use the former during my edit-compile-test cycle.
This target does not require root privilege.
check:
All openss7 packages provide check scripts for the check target. This
step is performed after compiling the package and will run all of the
check programs against the compiled binaries. Which checks are performed
depends on whether --enable-maintainer-mode was specified to configure.
If in maintainer mode, checks that assist with the release of the package
will be run (such as checking that all manual pages load properly and
that they have required sections.) We recommend running the check stage
before installing, because it catches problems that might keep the
installed package from functioning properly.
Another way to enable the greater set of checks, without invoking
maintainer mode, is to specify --enable-checks to 'configure'.
This target does not require root privilege.
install:
The install target installs the package. This target also performs some
actions similar to the pre- and post-install scripts used by packaging
tools such as rpm or deb.
This target requires root privilege.
installcheck:
All openss7 packages provide test scripts for the installcheck target.
Test scripts are created and run using autotest (part of the autoconf
package). Which test suites are run and how extensive they are depends
on whether --enable-maintainer-mode was specified to 'configure'. When
in maintainer mode, all test suites will be run. When not in maintainer
mode, only a few post-install checks will be performed, but the test
suites themselves will be installed in ${exec_prefix}/libexec/strbcm for later
use.
This target might require root privilege. Tests requiring root privilege
will be skipped when run as a regular user. Tests requiring regular
account privileges will be skipped when run as root.
retest:
To complement the installcheck target above, all openss7 packages provide
the retest target as a means to rerun failed conformance testsuite test
cases. The retest target is provided because some test cases in the
testsuites have delicate timing considerations that allow them to fail
sporadically. Invoking this target will retest the failed cases until
no cases that are not expected failures remain.
As with installcheck, this target might require root privilege. Tests
requiring root privilege will be skpped when run as a regular user.
Tests requiring regular account privileges will be skipped when run as
root.
uninstall:
This target will reverse the steps taken to install the package. This
target also performs pre- and post- erase scripts used by packaging tools
such as rpm or deb. You need to have a configured build directory from
which to execute this target, however, you do not need to have compiled
any of the files in that build directory.
This target requires root privilege.
remove:
This target is like `uninstall' with the exception that it uninstalls in
the reverse order that installation was performed.
Configure Options:
------------------
There are also some configure script options that change the behaviour of
some of the targets. These options are as follows:
Maintainer Targets:
-------------------
The following targets are targets intended for use by maintainers of the
package, or those responsible for rerelease and packaging of a derivative
work of the package. Some of these targets are only effective when
maintainer mode has been invoked (--enable-maintainer-mode specified to
'configure'.)
dist:
Creates a distribution package (tarball) in the top level build
directory. OpenSS7 packages distribute two archives: a gzip tar archive
and a bzip tar archive. These archives will have the name
strbcm-0.9.2.4.tar.gz and strbcm-0.9.2.4.tar.bz2
This target does not require root privilege.
distcheck:
This target is intended for use when releasing the package. It creates
the tar archives above and then unpacks the tarball in a source
directory, configures in a separate build directory, compiles the
package, installs the package in a separate install directory, tests the
install package to ensure that some components work, and, finally, uses
the unpacked source tree to build another tarball. If you have added or
removed files from the package, this is a good way to ensure that
everything is still kosher for release.
This target does not require root privilege.
Clean Targets:
--------------
mostlyclean:
Cleans out most of the files from the compile stage. This target is
helpful if you have not enabled dependency tracking and need to recompile
with changes.
clean:
Cleans all the files from the build directory generated during the `make
[all]' phase. It does not, however, remove files from the directory left
there from the `configure' run. Use the `distclean' target to remove
those too.
distclean:
This target cleans out the directories left behind by distcheck and
removes all the `configure' and generated files from the build directory.
This will effectively remove all the files in the build directory, with
the except of files that belong to you or some other process.
maintainer-clean:
This target not only removes files from the build directory, it removes
generated files from the source directory as well. Care should be taken
when invoking this target, because it removes files generated by the
maintainer and distributed with the archive that might require special
tools to regenerate. These special tools might only be available to the
maintainer (but they aren't). It also means that you probably need a
full blown Linux system to rebuild the package.
check-clean:
This target removes log files left behind by the `check' target. By
default, the check scripts append to log files in the top level build
directory. This target can be used to clean out those log files before
the next run.
Manual Page Targets
-------------------
The following targets are used to build, install and uninstall just the
manual pages from the distribution. These targets are good for creating a
distribution of just the manual pages. When building atop multiple
packages, these targets recurse down through each package.
mans:
Build all of the manual pages. This involves performing parameter
substitutions on manual pages and optionally cooking the manual pages
if `--with-cooked-manpages' was requested during configuration.
install-mans:
Installs the manual pages under DESTDIR. Specify DESTDIR to place the
manual pages wherever you see fit. If DESTDIR is not specified on the
command line, the manual pages will be installed in the normal
installation directory.
uninstall-mans:
Uninstalls the manual pages from DESTDIR. Specify DESTDIR to indicate
where to remove the manual pages from. If DESTDIR is not specified on
the command line, the manual pages will be removed from the normal
installation directory.
Release Targets:
----------------
The following are targets used to generate complete releases into the package
distribution directory. These are good for unattended and NFS builds, which
is what I use them for. Also, when building from atop multiple packages,
these targets also recurse down through each package.
release:
Build all of the things necessary to generate a release. On an rpm
system this is the distribution archives, the source rpm, and the
architecture dependent and architecture independent binary rpms. All
items are placed in the package distribution directory that can be
specified with the `--with-pkg-distdir=DIR' option to `configure'.
forced-release:
The release target will not regenerate any files that already exist in
the package distribution directory. This forced target will.
release-files:
This target automagically updates release files when in maintainer mode.
release-sign:
You will be prompted for a password, unless to specify it to make with
the GNUPGPASS variable. For unattended or non-interactive builds with
signing, you can do that as: 'make GNUPGPASS=mypasswd release-sign'
forced-release-sign:
The release-sign target will not regenerate any files that already exist
in the package distribution directory. This forced target will.
release-clean:
This target will remove all distribution files for the current package
from the package distribution directory.
Logging targets:
----------------
For convenience, to log the output of a number of targets to a file, log
targets are defined. The log file itself is used as the target to make, but
make invokes the target minus a .log suffix. So, for example, to log the
results of target 'foo', invoke the target 'foo.log'. The only target that
this does not apply to is 'compile.log'. When you invoke the target
'compile.log' a simple 'make' is invoked and logged to the file
'compile.log'. The 'foo.log' rule applies to all other targets. This does
not work for all targets, just a selected few. Following are the logging
targets:
First the common ones:
compile.log, check.log, install.log, installcheck.log, uninstall.log,
remove.log
and the maintainer mode ones:
dist.log, distcheck.log, srpm.log, rpms.log, sign.log, rebuild.log,
resign.log, release.log, release-sign.log
If you want to add one, simply add it to LOGGING_TARGETS in Makefile.am
Problem Report targets:
-----------------------
To ease problem report generation, all logging targets will automatically
generate a problem report suitable for mailing in the file 'target'.pr for
target 'target.log'. This problem report file is in the form of an email
and can be sent directly.
There are two additional problem report targets:
pr:
The pr target is for independently generating a problem report outside
of the build or installation process. The target will automatically
generate a problem report skeleton suitable for editting and mailing in
the file 'problem.pr'. This problem report file is in the form of an
email and can be sent directly.
finish-pr:
The finish-pr target is for finalizing a problem report. The problem
report will not be mailed but will simply have the comment lines removed
from the problem report. The target will automatically finalize the
problem report in 'problem.pr'.
send-pr:
The send-pr target is for finalizing and mailing a problem report
generated either inside or outside the build and installation process.
The target will automatically finalize and mail the 'problem.pr' problem
report if it has changed since the last time that send-pr was run.
Release Archive Targets:
------------------------
The following targets are used to generate and clean distribution archive and
signature files. Whereas the `dist' target affects archives in the top build
directory, the release-archive targets affects archives in the package
distribution directory, `/u6/releaseF'.
You can change the directory to which packages are distributed by using the
--with-pkg-distdir=DIR option to 'configure'. The default directory is the
top build directory `/u5/rel/strbcm'.
release-archives:
This target creates the distribution archive files if they have not
already been created. This not only runs the `dist' target, but also
copies the files to the distribution directory, which in this case is
/u6/releaseF.
The files generated are named:
strbcm-0.9.2.4.tar.gz and strbcm-0.9.2.4.tar.bz2
You can change this distribution directory with the --with-pkg-distdir
option to 'configure'. See './configure --help' for more details on
options.
release-sign-archives:
This target is like `release-archives', except that it also signs the
archives using a GPG detached signature. You will be prompted for a
password unless you pass the GNUPGPASS variable to make. For automated
or unattended builds, pass the GNUPGPASS variable like so:
make GNUPGPASS=mypasswd release-sign-archives
Signature files will be named:
strbcm-0.9.2.4.tar.gz.asc and strbcm-0.9.2.4.tar.bz2.asc
These files will be moved to the package distribution directory
/u6/releaseF with the plaintext archives.
release-clean-archives:
This target will clean the release archives and signature files from the
package distribution directory /u6/releaseF.
RPM Build Targets:
------------------
On rpm systems, or systems sporting rpm packaging tools, the following i
targets are used to generate rpm release packages. The epoch and release
number can be controlled by the contents of the .rpmepoch and .rpmrelease
files, or with the --with-rpm-epoch=EPOCH and --with-rpm-release=RELEASE
options to 'configure'. See 'configure --help' for more information on
options. We always use release number 1. You can use release numbers
above 1.
srpm:
This target generates the source rpm for the package (without signing the
source rpm). The source rpm will be named: strbcm-0.9.2.4-1.srpm
rpms:
This target is responsible for generating all of the package binary rpms
for the architecture. The binary rpms will be named:
strbcm-*-0.9.2.4-1.*.rpm
where the stars indicate the subpackage and the architecture. Both the
architecture specific subpackages (binary objects) and the architecture
independent (.noarch) subpackages will be built unless the the former was
disabled with the option `--disable-arch', or the later with the option
`--disable-indep', passed to `configure'.
sign srpm-sign:
These two targets are the same. When invoked, they will add a signature
to the source rpm file, provided that the file does not already have a
signature. You will be prompted for a password if a signature is
required. Automated or unattended builds can be acheived by using
the `emake' expect script, included in `/u6/os7/strbcm/scripts/emake'.
rebuild:
This target accepts searches out a list of kernel names from the
@DESTDIR@/lib/modules directory and builds rpms for those kernels and for
each of a set of architectures given in the AM_RPMTARGETS variable to
make. This is convenience target for building a group of rpms on a given
build machine.
resign:
This target will search out and sign, with a GPG signature, the source
rpm, and all of the binary rpms for this package that can be found in the
package distribution directory. This target will prompt for a GPG
password. Automated or unattended builts can be acheived with the
`emake' expect script loccated here: `/u6/os7/strbcm/scripts/emake'.
Debian Build Targets:
---------------------
On debian systems, or systems sporting debian packaging tools, the following
targets are used to generate debian release packages. The release number can
be controlled by the contents of the .debrelease file, or with the
--with-debrelease=RELEASENUMBER option to 'configure'. See 'configure
--help' for more information on options.
dsc:
This target will build the debian source change package (.dsc file). We
use release number 0 so that the entire tarball is included in the dsc
file. You can use release number 1 for the same purposes. Release
numbers above 1 will not include the entire tarball. The .dsc file will
be named: strbcm_0.9.2.4-0.dsc
sigs:
This target signs the .deb files. You will be prompted for a password,
unless to specify it to make with the GNUPGPASS variable.
debs:
This target will build the debian binary package (.deb file) from the
.dsc created above. (This target will also create the .dsc if it has not
been created already.) The subpackage .deb files will be named:
strbcm-*_0.9.2.4-0_*.deb, where the stars indicate the subpackage and
the architecture.
csig:
This target signs the .dsc file. You will be prompted for a password,
unless to specify it to make with the GNUPGPASS variable.