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 Ubuntu release or
from a specified .dsc path or URL and creates a no-change backport of
that package to a previous 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 Ubuntu release. If neither
this option nor \fB\-\-version\fR are specified, then
\fBbackportpackage\fR defaults to the current Ubuntu development
release.
.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 \fBpbuilder\fR(8) users: This assumes the common configuration,
where the \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
\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, 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 \-l \fIINSTANCE\fR, \fB\-\-launchpad\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
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_LPINSTANCE ", " UBUNTUTOOLS_LPINSTANCE
The default value for \fB--launchpad\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.