| Russ Allbery > Software > Scripts | release Changes > |
(Release a software package)
release [-hsv] [-b | -d] package
release -u
Python 2.5 or later, GnuPG for signing releases, and the revision control program for whatever revision control software is used for the source. Building Debian packages additionally requires pbuilder be installed and properly configured. Git is used to commit changes to the .verisons file.
This program is very likely to require customization if used by anyone other than its author.
release automates portions of the process of releasing a new version of a software package or script. It's actions and all relevant paths are controlled by a configuration file (see CONFIG FILE below). It understands a variety of revision control systems and build systems and attempts to determine the correct thing to do automatically with a minimum of configuration. It updates a .versions file for use by spin for generating web pages.
The default action, if no arguments but package are given, is to create a detached GnuPG signature of the package if it is a tarball release (not a script), copy it to its copy location, create or update symlinks without the embedded version to point to the latest version, archive old versions if appropriate, and update .versions. In this mode, it expects the tarball or script to have already been prepared for a release, although for a script it may export the final version from CVS.
If the -d option is given, release instead generates a tarball release by running the appropriate build actions. It currently understands how to do exports from CVS, Subversion, bzr, and Git and how to generate tarball releases for packages using Automake, Perl's build system, or a dist Makefile target, with or without a configure script.
If the -b option is given, release instead builds Debian packages. It knows how to combine a tarball release with a debian directory stored in CVS or Subversion to build a package. All package builds are done with pdebuild. This mode is no longer tested.
If the -u option is given, release does not expect a package on the command line. Instead, it scans the .versions file and checks the release version against the current version information, as best as it is able to determine, for each package listed there. For any that appear to have a newer release than is recorded in the .versions file, it prints out the package and its current version. Currently, it only checks scripts.
Build a Debian package as described above. This option is no longer tested and is not used by the author, who has switched to git-buildpackage and separate repository branches for Debian package builds.
Rather than release software, generate the release tarball. release
first exports the package from its revision control system and then runs
the appropriate build system commands to generate a release tarball. It
understands CVS, Subversion, bzr, and Git for revision control systems and
Perl, Automake, Autoconf, and simple makefiles with a dist target for
generating the release tarball.
Prints basic usage information for release.
When building a Debian package with -b, force inclusion of the full source in the *.changes file by passing -sa to pbuilder in the --debuildopts argument.
Rather than release software, scan the .versions file and check all scripts listed there to see if they have a different version than the one recorded in .versions.
Print out the version of release and exit.
release uses a configuration file for most of the information it
needs. This configuration file is in the format parsed by the standard
Python ConfigFile class (similar to a Windows INI file) and should have
one section per package, as used for command-line arguments. It also must
have a section entitled PATHS that configures some global variables.
Blank lines and lines beginning with # are ignored.
Sections start with the section title between []. A variable setting
is the variable name, a colon, whitespace, and then the value. For
example:
[PATHS]
distdir: /home/eagle/data/dist
versions: /home/eagle/web/eagle/.versions
[kstart]
tarball: /home/eagle/data/dist
prefix: kstart
copy: /afs/ir/users/r/r/rra/public/software/kerberos
archive: /afs/ir/users/r/r/rra/public/software/ARCHIVE/kstart
package: kstart
giturl: /home/eagle/dvl/kstart
Variables for the PATHS section:
Specifies where to put Debian packages built using the -b option. Required only if -b is used.
Specifies where to put tarballs built using the -d option. This location will then generally be named in the tarball parameter of the relevant package configuration section. Required only if -d is used.
Specifies the location of the .versions file for spin that release should update. Required.
Variables for each package section:
When copying a new tarball release, look for any older files from previous
versions and move them to this directory, which is created if it doesn't
already exist. Older files are recognized by looking for files starting
with prefix and matching the file name pattern for a tarball with a
version or its MD5 checksum or PGP signature. Only used if tarball is
set; there is no way to archive old versions of scripts.
The URL to the bzr repository for the package. When -d is given, it is
used with the bzr branch command to generate an exported copy of the
repository, which is then used to run the appropriate command to generate
a distribution tarball.
The location into which to copy the release, either a script or a tarball.
For tarballs, files from previous versions in that location will be left
there unless archive is also set. For scripts, any existing version
will be overwritten.
The path to the CVS module for the Debian build rules within a CVS repository. This is only used when building a Debian package for a script using the -b option and is no longer tested.
The path to the CVS module for the package within a CVS repository. When
-d is given, it is used with the cvs export command to generate an
exported copy of the repository, which is then used to run the appropriate
command to generate a distribution tarball. It is also used to locate the
script in the CVS repository to generate a CVS export when the export
variable is set instead of copy. If cvsroot is not also set, the
default CVS root is used, which may be unpredictable.
Specifies the root of the CVS repository for use with cvspath. Setting
this variable is strongly recommended, even if you have CVS configured to
use a default repository and all packages are in that repository, since it
removes potential future ambiguity.
Normally, scripts are copied from the location specified by script to
the location specified by copy. If this variable is set instead of
copy, the script is instead exported from its CVS repository, expanding
CVS keywords (the -kv option). cvspath must be set. This is only
used when script is set and should not be set for the same package as
copy.
The branch to export when generating a distribution tarball, instead of
master. Only used with -d and if giturl is set.
The URL, which may be a file system path, to the Git repository for the
package. When -d is given, it is used with the git archive command
to generate an exported copy of the repository, which is then used to run
the appropriate command to generate a distribution tarball. By default,
the master branch is exported, but a different branch may be specified
with gitbranch. Only used if tarball is set.
If set, names PGP key IDs to use when signing tarball releases. Setting
this causes the -u option and this value to be passed to gpg when
creating signatures. The value will be split on whitespace and each word
will be taken to be a separate key. If more than one key is listed, the
resulting detached signature file will contain multiple signatures. Only
used if tarball is set.
The make target to use to generate a distribution tarball. This overrides
the default of distcheck for Automake package and dist for any other
package with a Makefile or configure script. This is only used if
tarball is set and when the -d option is given.
The name of the Debian source package. Only used when building Debian
packages with -b. This need not match the package name in the tarball,
which should be given with prefix. It should patch the package name in
debian/changelog.
The prefix for tarballs of this package. Release tarballs are expected to
be named prefix-version.tar.gz. Only used if tarball is also
set.
Specifies the location of a script to release. release will determine
the version of the script by searching the file for either a CVS Id string
or a variable VERSION or $VERSION within the first 50 lines of the file.
The latter overrides the former. The presence of this variable indicates
that the package is a script, as opposed to tarball which indicates
tarball releases.
The URL to the Subversion repository for the package. When -d is
given, it is used with the svn export command to generate an exported
copy of the repository, which is then used to run the appropriate command
to generate a distribution tarball.
Specifies the location searched for the tarball to release. The resulting
directory will be searched for tarballs starting with prefix and the
version number of the release extracted from the file name. The presence
of this variable indicates that this package has tarball releases (as
opposed to script, which indicates a script.
Only one of bzrurl, cvspath, giturl, or svnurl should be
given.
The default configuration file location, set at the top of this script.
release hard-codes all sorts of details about the package layout, export preferences, and version control methods of its author. It will likely require extensive customization to work for someone else. This is particularly true of the Debian package building (-b), which relies on a particular way of storing Debian package build information alongside a package in a CVS or Subversion repository.
Debian package builds (-b) are no longer used by the author and no longer tested. The same is true for all tarball support for revision control systems other than Git, although it's simple enough that it's unlikely to break significantly.
bzr(1), cvs(1), git(1), pdebuild(1), spin(1), svn(1)
The current version of this script is available from Russ Allbery's script page at <http://www.eyrie.org/~eagle/software/scripts/>.
Russ Allbery <rra@stanford.edu>
Copyright 2001, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2012 Russ Allbery <rra@stanford.edu>.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
| Russ Allbery > Software > Scripts | release Changes > |