 -----------------------------------------------------------------------------

 Copyright (c) 2001-2007  OpenSS7 Corporation <http://www.openss7.com/>
 Copyright (c) 1997-2000  Brian F. G. Bidulock <bidulock@openss7.org>

 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/strutil 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
     strutil-0.9.2.6.tar.gz and strutil-0.9.2.6.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/rel2/strutil'.

 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:
         strutil-0.9.2.6.tar.gz and strutil-0.9.2.6.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:
         strutil-0.9.2.6.tar.gz.asc and strutil-0.9.2.6.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: strutil-0.9.2.6-1.srpm

 rpms:
     This target is responsible for generating all of the package binary rpms
     for the architecture.  The binary rpms will be named:

         strutil-*-0.9.2.6-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/strutil/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/strutil/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: strutil_0.9.2.6-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:
     strutil-*_0.9.2.6-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.

