| release - Perform a project release for projects. |
release - Perform a project release for projects.
release [options] [version]
release is a Perl program to automate project releases from CVS. This program is typically called from a project-specific release script with the proper options. Example:
#/bin/sh
exec perl /home/projects/release/devtools/latest/bin/release \
-cvsroot /home/cvs/root \
-project someapp \
-mailto earl@earlhood.com \
${1+"$@"}
The ${1+"$@"} is Bourne shell construct that safely passes any
options specified to the script to the program being called.
If the script is called, ``release-someapp'', then sample invocation would be:
shell> release-someapp -create 1.0.0
Every project must define a top-level makefile that defines the
release target. The target should at a minimum compile/build the
project.
The following basic tasks are performed during a project release:
A test build of the project in a ``clean'' environment. I.e. Only basic environment variables are set when executing the build. This is to insure there are no indirect influences in caller's environment that can affect the release process.
The test build can be skipped by using the -notest option.
Automatic tagging of the project in CVS -- if -create option
specified -- to allow source code recovering for a specified release
version. If -create is not specified, the project must already
be tagged for the specified version.
Export of project into project release directory. This provides a browsable version of files for a release.
Tar-gzipping of the built project, unless the project itself creates its own distribution bundles (see NOTES).
Update of latest symlink to point to release just make (unless
the -notlatest option is specified).
The version number of the release can be specified on the command-line. If it is not, this program will prompt you for a release number giving a default value as the next version number increment. If you specify a version that already exists, you will be prompted for confirmation that you want override an existing release.
Version numbers must conform to the following Perl regular expression:
/^\d+\.\d+(?:\.\d+)?$/.
Examples: 1.0, 0.10.4, 23.0.1. Arbitrary version number
formats can be done by use the -noversion-check option.
-arch
Perform an architectural-specific release. This option should be used
for projects that will create machine-executable code (however, see
the -rhost option for an alternative). The released
project will be placed in an architecture identifiable directory and
the tar-gz bundle will include the architecture in the name.
The name to identify the architecture is the return value of the following
command: uname -s -p.
-conf pathname
Pathname of configuration file to use. See SITE CONFIGURATION for more information.
-create
Tag the project in CVS. If not specified, it is assumed that the
project has been tagged for the specified version. If this option is
specified, a cvs rtag will be performed on the project. The tag
name used is the release version specified modified as follows:
dots are converted to hyphens and the letter ``v'' is prepended.
For example, if the version number is 0.5.1, the tag wil be
v0-5-1. The translation is done since CVS does not support dots
in tag names, and tag names must start with an alpha character.
In most usage cases, the -create option is always specified.
Examples of when it is not specified is if a manual CVS tagging
was performed; or multiple architectural releases of a project are
being done, and after the first architectural release, the other
releases do not need -create since the first release already did
the tagging (see -rhost option for an alternative for multiple
architecture releases). -create is also not required if doing an
override release: the specified version already exists and the new
release will override the existing one.
-cvsroot pathname
The CVS repository root for the project. If not specified, the value
of the CVSROOT environment variable is used or the root specified
in the site-wide configuration file. If no cvs root is specified,
then the program terminates with an error.
-keeptest
Do not delete test files. Useful for debugging problems and
when -test-only is specified.
-force-tag
Force tagging of repository, regardless. Forcing is automatic when an overriding release is detected.
-help
Display help message.
-mailprg prgname
Mail program to use to send mail notification if -mailto options
are specified. The program must be able to take a valid RFC 822 formated
message with the destination receipients specifed in the To: message
header field. The default value is /usr/lib/sendmail -t.
-mailto address
Address(es) to mail when release is done. This option can be
specified multiple times inorder to provide multiple recipients.
-makefile filename
The name of the project makefile. This option allows one to
specify a makefile to invoke when performing a release if
the makefile is not one of the default filenames searched for
by make.
-makeprg prgname
make program. If not specified, the value of the MAKE
environment variable is used. If this is not specified,
gmake is used.
-man
Display manpage.
-n
Echo to stdout what would be done, but do not do it. This option is useful to see what actions will be performed without them being executed; useful for debugging.
-news filename
Filename of file (relative to project root) that provides a summary
of changes for this release. This option is used if -mailto
is specified. Contents of filename will be included in the mail
message sent. To minimize the size of the message, an attempt is
made to only include the comments only for the release. To do this,
a check is made for separators lines composed of the '=' character.
Example:
======================================================================
The first occurrence is ignored. All text up to the next occurrence will be included in the mail message sent. If no occurrences of a separator is detected, then the entire contents of the file will be included in the message.
If this option is not specified, the file called NEWS in the
released project's root directory will be used.
-noversion-check
Do not validate the version number. This is useful if the project does not following the normal versioning format.
-project name
Name of project to release. This is a required option.
-notest
Skip performing a test build.
-notlatest
Not latest release, so do not update latest link. Normally, the
latest symlink will be updated to point to the release just made.
This option supresses the update. This is useful for cases when
older releases are redone.
-rhost hostname
Build project on specified hostname. This option can be specified multiple times to specify multiple hosts to build against. The build process is invoked for each remote host in the order specified. This option is useful for providing a build for multiple OS/hardware platforms.
Note: It is assumed that the hosts specified NFS mount
the release directory so that /home/projects/release exists
on all hosts specified, including localhost.
Note: Using this option assumes that the project makefiles are
configured to support compilation under multiple platforms. If not,
use the -arch option instead for creating separate releases for
each platform.
-rshprg prgname
Specify the remote shell program to use when invoking make
for hostnames specified with -rhost. The program specified must
follow the calling sematics of rsh. Note, depending on
system configuration, authentication may need to be prompted for each
remote host, like for ssh.
The default value is rsh.
-snapmode
Run in snapshot mode. Instead of doing a versioned release, a release is done on the latest source within CVS.
-test-only
Only perform the test build. After the test build, the program exits. The test build directory is still removed.
-url url
URL to include in mail message if -mailto is specified.
release supports site-wide configuration to allow for sites to customize to the behavior of release to suit local preferences. The following files are checked for when release starts:
The pathname specified by the -conf option.
$HOME/.release.conf
/usr/local/etc/devtools/release.conf
/etc/devtools/release.conf
The first file found is used, and any subsequent files will be ignored.
The following example shows what configuration settings are supported, the default values for those settings, and the syntax of the configuration file:
# Site configuration file for devtools release program # # The syntax of this file is Perl and it should return a reference # to a hash when required.
+{
# Pathname to CVS respository: Overridden by -cvsroot option
# or CVSROOT envariable. The value can be any legal cvs root
# specification, including external repositories like ":ext:..."
CVS_ROOT => '/home/cvs/root',
# Name of directory under a project's directory containing releases of
# the project.
DIST_DIRNAME => 'tar',
# Mail program: Overridden by -mailprg option.
MAIL_PRG => '/usr/lib/sendmail -t',
# Make program: Overridden by -makeprg option or MAKE envariable.
MAKE_PRG => 'gmake',
# Make target name to invoke to create a release.
MK_TARGET_RELEASE => 'release',
# Program search path to use when performing release. This
# should contain the absolute minimum required to build a project.
PATH => join(':',
'/usr/local/bin',
'/opt/sfw/bin', # Solaris
'/usr/ccs/bin', # Solaris
'/usr/bin',
'/bin',
'/usr/X11R6/bin',
'/usr/openwin/bin'), # Solaris
# Pathname to project releases.
REL_DIR => '/home/projects/release',
# Remote shell program (for multi-architecture releases): Overridden
# by RSHELL envariable. Use ssh if security is a concern.
RSH_PRG => 'rsh',
# File creation umask. Notice how there is NO quotes used.
UMASK => 002,
# List of environment variables to preserve from calling process
ENV_KEEP => [ ],
};
CVSROOT
Pathname to CVS repository. Overridden by -cvsroot option.
MAKE
Name of make program. Overridden by -makeprg option.
RSHELL
Name of remote shell program. Overridden by -rshprg option.
_RELEASE_MODE
Envariable set by release. This variable can be referenced by
a project's makefile if it needs to know if it is being invoked by
this program. The value of _RELEASE_MODE is 1.
_RELEASE_VERSION
Envariable set by release containing the release version number of
the project. This variable can be referenced by a project's makefile
if it needs to know the version number when executing the makefile's
release target.
If -snapmode is specified, the release version will be in the
format YYYY-MM-DD-snap.
_SNAP_MODE
Envariable set by release. This variable can be referenced by
a project's makefile if it needs to know if it is being invoked by
this program with -snapmode. The value of _SNAP_MODE is 1.
Note: The _RELEASE_VERSION envariable will still be set to
1 when -snapmode is specified.
/home/projects/release
Root directory where all releases are placed.
/home/projects/release/<project>
Root directory containing releases for <project>.
NOTE: This directory must be manually created before any releases can be done for a given <project>. The reasons for this are as follows:
Allows one to explicitly control when releases can be performed for a project. When a project is first started, it may be desirable to prevent any releases to be performed until some initial milestone is reached.
Allows explicit review of who is allowed to perform releases. I.e. The directory ownership and permissions can be properly set to reflect who is allowed to invoke the release process.
/home/projects/release/<project>/<version>
Directory where a given version of a project is placed by this program.
/home/projects/release/<project>/<version>/<platform>
Directory where a given version of a project is placed by this
program when -arch has been specified to do platform-specific release.
/home/projects/release/<project>/tar
Directory where tar-gz bundles are placed for project.
Projects can define their own distribution bundles to be placed
into /home/projects/release/<project>/tar, overriding
the bundle creation of this program. To do this, the project can
create the bundle (or bundles if multiple, alternative bundles are
relevant for the project) within a directory called dist under
the project root. Any filename that ends in the following
extensions, .tar, .tar.gz, .tar.bz2, .tar.Z, .zip,
.dep, .rpm,
will be copied into /home/projects/release/<project>/tar.
The dist directory will then be removed once the files are
copied.
NOTE: It is important that any bundles created by the project
itself have filenames that reflect the version of the project
being released to avoid overwritting past version bundles in
/home/projects/release/<project>/tar. To assist in this,
this program defines the environment variable _RELEASE_VERSION
to contain the release version number for use within the project's
makefile.
If an override release is being performed, the existing release directory
is moved to ,version where version is the version of the
release as a backup. If the backup is no longer required, or another
override release is to be done for the specified version, the backup
directory must be manually removed.
If ssh is the prefered, or required, mode for communicating with a remote repository, performing automated snapshots can be a problem since a password is required, unless you decide to use passwordless key authentication. An option is to utilize ssh-agent(1). release preserves ssh-agent related environment variables when creating the clean environment.
Earl Hood, earl@earlhood.com
This program comes with ABSOLUTELY NO WARRANTY and may be copied only under the terms of the GNU General Public License.
| release - Perform a project release for projects. |