ubuntu-dev-tools/doc/backportpackage.1

.TH BACKPORTPACKAGE "1" "December 2010" "ubuntu-dev-tools"
.SH NAME
backportpackage \- helper to test package backports
.SH SYNOPSIS
.TP
.B backportpackage \fR[\fIadditional options\fR]
\-\-upload <\fIupload target\fR>
.br
<\fIsource package name or .dsc URL/file\fR>
.PP
.B backportpackage \-h
.SH DESCRIPTION
\fBbackportpackage\fR fetches a package from one distribution release
or from a specified .dsc path or URL and creates a no-change backport
of that package to one or more Ubuntu releases release, optionally
doing a test build of the package and/or uploading the resulting
backport for testing.
.PP
Unless a working directory is specified, the backported package is
fetched and built in a temporary directory in \fB/tmp\fR, which is
removed once the script finishes running.
.PP
\fBbackportpackage\fR is only recommended for testing backports in a
PPA, not uploading backports to the Ubuntu archive.
.SH OPTIONS
.TP
.B \-d \fIDEST\fR, \fB\-\-destination\fR=\fIDEST\fR
Backport the package to the specified Ubuntu release. If this option
is unspecified, then \fBbackportpackage\fR defaults to the release on
which it is currently running.
.TP
.B \-s \fISOURCE\fR, \fB\-\-source\fR=\fISOURCE\fR
Backport the package from the specified release, which can be any
release of your distribution or any of your distribution's parent
distributions. If neither this option nor \fB\-\-version\fR are
specified, then \fBbackportpackage\fR defaults to the current
development release for your distribution.
.TP
.B \-S \fISUFFIX\fR, \fB\-\-suffix\fR=\fISUFFIX\fR
Add the specified suffix to the version number when
backporting. \fBbackportpackage\fR will always append
~\fIDESTINATION\fR1 to the original version number, and if
\fISUFFIX\fR is specified, it is appended to that, to get version
numbers of the form
\fIORIGINAL_VERSION\fR~\fIDESTINATION\fR1\fISUFFIX\fR. If the
backported package is being uploaded to a PPA, then \fISUFFIX\fR
defaults to \fB~ppa1\fR, otherwise the default is blank.
.TP
.B \-b\fR, \fB\-\-build
Build the package with the specified builder before uploading. Note
for \fBcowbuilder\fR(8) and \fBpbuilder\fR(8) users:
This assumes the common configuration,
where the \fBARCH\fR and \fBDIST\fR environment is read by \fBpbuilderrc\fR(5)
to select the correct base image.
.TP
.B \-B \fIBUILDER\fR, \fB\-\-builder\fR=\fIBUILDER
Use the specified builder to build the package. Supported are
\fBcowbuilder\fR(8), \fBcowbuilder-dist\fR(1), \fBpbuilder\fR(8),
\fBpbuilder-dist\fR(1), and \fBsbuild\fR(1).
The default is \fBpbuilder\fR(8).
.TP
.B \-U\fR, \fB\-\-update
Update the build environment before attempting to build.
.TP
.B \-u \fIUPLOAD\fR, \fB\-\-upload\fR=\fIUPLOAD\fR
Upload to \fIUPLOAD\fR with \fBdput\fR(1) (after confirmation).
.TP
.B \-y\fR, \fB\-\-yes
Do not prompt before uploading to a PPA. For everyone's safety, this
option is ignored if \fIUPLOAD\fR is \fBubuntu\fR.
.TP
.B \-v \fIVERSION\fR, \fB\-\-version\fR=\fIVERSION\fR
If the \fB\-\-source\fR option is specified, then
\fBbackportpackage\fR verifies that the current version of \fIsource
package\fR in \fISOURCE\fR is the same as \fIVERSION\fR. Otherwise,
\fBbackportpackage\fR finds version \fIVERSION\fR of \fIsource
package\fR in your distribution's publishing history, regardless of
the release in which it was published (or if that version is still
current). This option is ignored if a .dsc URL or path is passed in
instead of a source package name.
.TP
.B \-w \fIWORKDIR\fR, \fB\-\-workdir\fR=\fIWORKDIR\fR
If \fIWORKDIR\fR is specified, then all files are downloaded,
unpacked, built into, and otherwise manipulated in
\fIWORKDIR\fR. Otherwise, a temporary directory is created, which is
deleted before \fIbackportpackage\fR exits.
.TP
.B \-m \fIMIRROR\fR, \fB\-\-mirror\fR=\fIMIRROR\fR
Use the specified mirror.
Should be in the form \fBhttp://archive.ubuntu.com/ubuntu\fR.
If the package isn't found on this mirror, \fBbackportpackage\fR
will use Launchpad.
.TP
.B \-l \fIINSTANCE\fR, \fB\-\-lpinstance\fR=\fIINSTANCE\fR
Use the specified instance of Launchpad (e.g. "staging"), instead of
the default of "production".
.TP
.B \-\-no\-conf
Do not read any configuration files, or configuration from environment
variables.
.SH ENVIRONMENT
.TP
.BR DEBFULLNAME ", " DEBEMAIL ", " UBUMAIL
Used to determine the uploader (if not supplied as options).
See
.BR ubuntu\-dev\-tools (5)
for details.
.P
All of the \fBCONFIGURATION VARIABLES\fR below are also supported as
environment variables.
Variables in the environment take precedence to those in configuration
files.
.SH CONFIGURATION VARIABLES
The following variables can be set in the environment or in
.BR ubuntu\-dev\-tools (5)
configuration files.
In each case, the script\-specific variable takes precedence over the
package\-wide variable.
.TP
.BR BACKPORTPACKAGE_BUILDER ", " UBUNTUTOOLS_BUILDER
The default value for \fB\-\-builder\fR.
.TP
.BR BACKPORTPACKAGE_UPDATE_BUILDER ", " UBUNTUTOOLS_UPDATE_BUILDER
The default value for \fB--update\fR.
.TP
.BR BACKPORTPACKAGE_WORKDIR ", " UBUNTUTOOLS_WORKDIR
The default value for \fB--workdir\fR.
.TP
.BR BACKPORTPACKAGE_UBUNTU_MIRROR ", " UBUNTUTOOLS_UBUNTU_MIRROR
The default value for \fB\-\-mirror\fR if the specified \fISOURCE\fR
release is an Ubuntu release.
.TP
.BR BACKPORTPACKAGE_DEBIAN_MIRROR ", " UBUNTUTOOLS_DEBIAN_MIRROR
The default value for \fB\-\-mirror\fR if the specified \fISOURCE\fR
release is a Debian release.
.TP
.BR BACKPORTPACKAGE_LPINSTANCE ", " UBUNTUTOOLS_LPINSTANCE
The default value for \fB--lpinstance\fR.
.SH EXAMPLES
Test-build in your PPA a backport of znc from the current development
release to your workstation's release, deleting the build products
afterwards:
.IP
.nf
.B backportpackage -u ppa:\fIuser\fR/\fIppa\fB znc
.fi
.PP
Backport squashfs-tools from Maverick to both Karmic and Lucid and
test-build both locally, leaving all build products in the current
working directory:
.IP
.nf
.B backportpackage -b -s maverick -d karmic -d lucid -w . \\\\
.B "  "squashfs-tools
.fi
.PP
Fetch a package from a PPA, backport it to Hardy, then upload it back
to the same PPA:
.IP
.nf
.B backportpackage -d hardy -u ppa:\fIuser\fR/\fIppa\fR \\\\
.B "  "https://launchpad.net/\fIsome/file.dsc\fR
.fi
.SH SEE ALSO
.BR ubuntu\-dev\-tools (5)
.SH AUTHOR
\fBbackportpackage\fR and this manpage were written by Evan Broder
<evan@ebroder.net>
.PP
Both are released under GNU General Public License, version 2.