summaryrefslogtreecommitdiffstats
path: root/scripts/debc.1
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--scripts/debc.1131
1 files changed, 131 insertions, 0 deletions
diff --git a/scripts/debc.1 b/scripts/debc.1
new file mode 100644
index 0000000..b043ee5
--- /dev/null
+++ b/scripts/debc.1
@@ -0,0 +1,131 @@
+.TH DEBC 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
+.SH NAME
+debc \- view contents of a generated Debian package
+.SH SYNOPSIS
+\fBdebc\fP [\fIoptions\fR] [\fIchanges file\fR] [\fIpackage\fR ...]
+.SH DESCRIPTION
+\fBdebc\fR figures out the current version of a package and displays
+information about the \fI.deb\fR and \fI.udeb\fR files which have been generated
+in the current build process. If a \fI.changes\fR file is specified
+on the command line, the filename must end with \fI.changes\fR, as
+this is how the program distinguishes it from package names. If not,
+then \fBdebc\fR has to be called from within the source code directory
+tree. In this case, it will look for the \fI.changes\fR file
+corresponding to the current package version (by determining the name
+and version number from the changelog, and the architecture in the
+same way as \fBdpkg-buildpackage\fR(1) does). It then runs
+\fBdpkg-deb \-I\fR and \fBdpkg-deb \-c\fR on every \fI.deb\fR and
+\fI.udeb\fR archive listed in the \fI.changes\fR file to display
+information about the contents of the \fI.deb\fR / \fI.udeb\fR files.
+It precedes every \fI.deb\fR or \fI.udeb\fR file with the name of the
+file. It assumes that all of the \fI.deb\fR / \fI.udeb\fR archives
+live in the same directory as the \fI.changes\fR file. It is
+useful for ensuring that the expected files have ended up in the
+Debian package.
+.PP
+If a list of packages is given on the command line, then only those
+debs or udebs with names in this list of packages will be processed.
+.SH "Directory name checking"
+In common with several other scripts in the \fBdevscripts\fR package,
+\fBdebc\fR will climb the directory tree until it finds a
+\fIdebian/changelog\fR file. As a safeguard against stray files
+causing potential problems, it will examine the name of the parent
+directory once it finds the \fIdebian/changelog\fR file, and check
+that the directory name corresponds to the package name. Precisely
+how it does this is controlled by two configuration file variables
+\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR and \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR, and
+their corresponding command-line options \fB\-\-check-dirname-level\fR
+and \fB\-\-check-dirname-regex\fR.
+.PP
+\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR can take the following values:
+.TP
+.B 0
+Never check the directory name.
+.TP
+.B 1
+Only check the directory name if we have had to change directory in
+our search for \fIdebian/changelog\fR. This is the default behaviour.
+.TP
+.B 2
+Always check the directory name.
+.PP
+The directory name is checked by testing whether the current directory
+name (as determined by \fBpwd\fR(1)) matches the regex given by the
+configuration file option \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR or by the
+command line option \fB\-\-check-dirname-regex\fR \fIregex\fR. Here
+\fIregex\fR is a Perl regex (see \fBperlre\fR(3perl)), which will be
+anchored at the beginning and the end. If \fIregex\fR contains a '/',
+then it must match the full directory path. If not, then it must
+match the full directory name. If \fIregex\fR contains the string
+\'PACKAGE', this will be replaced by the source package name, as
+determined from the changelog. The default value for the regex is:
+\'PACKAGE(-.+)?', thus matching directory names such as PACKAGE and
+PACKAGE-version.
+.SH OPTIONS
+.TP
+\fB\-a\fIdebian-architecture\fR, \fB\-t\fIGNU-system-type\fR
+See \fBdpkg-architecture\fR(1) for a description of these options.
+They affect the search for the \fI.changes\fR file. They are provided
+to mimic the behaviour of \fBdpkg-buildpackage\fR when determining the
+name of the \fI.changes\fR file.
+.TP
+\fB\-\-debs\-dir\fR \fIdirectory\fR
+Look for the \fI.changes\fR, \fI.deb\fR and \fI.udeb\fR files in
+\fIdirectory\fR instead of the parent of the source directory.
+This should either be an absolute path or relative to the top of the
+source directory.
+.TP
+\fB\-\-check-dirname-level\fR \fIN\fR
+See the above section \fBDirectory name checking\fR for an explanation of
+this option.
+.TP
+\fB\-\-check-dirname-regex\fR \fIregex\fR
+See the above section \fBDirectory name checking\fR for an explanation of
+this option.
+.TP
+\fB\-\-list-changes\fR
+List the filename of the .changes file, and do not display anything else. This
+option only makes sense if a .changes file is NOT passed explicitly in the
+command line. This can be used for example in a script that needs to reference
+the .changes file, without having to duplicate the heuristics for finding it
+that debc already implements.
+.TP
+\fB\-\-list-debs\fR
+List the filenames of the .deb packages, and do not display their contents.
+.TP
+\fB\-\-no-conf\fR, \fB\-\-noconf\fR
+Do not read any configuration files. This can only be used as the
+first option given on the command-line.
+.TP
+\fB\-\-help\fR, \fB\-\-version\fR
+Show help message and version information respectively.
+.SH "CONFIGURATION VARIABLES"
+The two configuration files \fI/etc/devscripts.conf\fR and
+\fI~/.devscripts\fR are sourced in that order to set configuration
+variables. Command line options can be used to override configuration
+file settings. Environment variable settings are ignored for this
+purpose. The currently recognised variables are:
+.TP
+.B DEBRELEASE_DEBS_DIR
+This specifies the directory in which to look for the \fI.changes\fR,
+\fI.deb\fR and \fI.udeb\fR files, and is either an absolute path or
+relative to the top of the source tree. This corresponds to the
+\fB\-\-debs\-dir\fR command line option. This directive could be
+used, for example, if you always use \fBpbuilder\fR or
+\fBsvn-buildpackage\fR to build your packages. Note that it also
+affects \fBdebrelease\fR(1) in the same way, hence the strange name of
+the option.
+.TP
+.BR DEVSCRIPTS_CHECK_DIRNAME_LEVEL ", " DEVSCRIPTS_CHECK_DIRNAME_REGEX
+See the above section \fBDirectory name checking\fR for an explanation of
+these variables. Note that these are package-wide configuration
+variables, and will therefore affect all \fBdevscripts\fR scripts
+which check their value, as described in their respective manpages and
+in \fBdevscripts.conf\fR(5).
+.SH "SEE ALSO"
+.BR debdiff (1),
+.BR dpkg-deb (1),
+.BR devscripts.conf (5)
+.SH AUTHOR
+Julian Gilbey <jdg@debian.org>, based on an original script by
+Christoph Lameter <clameter@debian.org>.