summaryrefslogtreecommitdiffstats
path: root/man/dsc.pod
diff options
context:
space:
mode:
Diffstat (limited to 'man/dsc.pod')
-rw-r--r--man/dsc.pod287
1 files changed, 287 insertions, 0 deletions
diff --git a/man/dsc.pod b/man/dsc.pod
new file mode 100644
index 0000000..9e6f916
--- /dev/null
+++ b/man/dsc.pod
@@ -0,0 +1,287 @@
+# dpkg manual page - dsc(5)
+#
+# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
+# Copyright © 2015 Guillem Jover <guillem@debian.org>
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dsc - Debian source package control file format
+
+=head1 SYNOPSIS
+
+I<filename>B<.dsc>
+
+=head1 DESCRIPTION
+
+Each Debian source package is composed of a .dsc control file, which
+contains a number of fields, in L<deb822(5)> format.
+
+Each field begins with a tag, such as
+B<Source>
+or
+B<Binary>
+(case insensitive), followed by a colon, and the body of the field
+(case sensitive unless stated otherwise).
+Fields are delimited only by field tags.
+In other words, field text may be multiple lines in length, but the
+installation tools will generally join lines when processing the body
+of the field (except in case of the multiline fields
+B<Package-List>, B<Files>, B<Checksums-Sha1> and B<Checksums-Sha256>,
+see below).
+
+The control data might be enclosed in an OpenPGP ASCII Armored signature,
+as specified in RFC4880.
+
+=head1 FIELDS
+
+=over
+
+=item B<Format:> I<format-version> (required)
+
+The value of this field declares the format version of the source package.
+The field value is used by programs acting on a source package to
+interpret the list of files in the source package and determine how
+to unpack it.
+The syntax of the field value is a numeric major revision (“0-9”), a
+period (“.”), a numeric minor revision (“0-9”), and then an optional
+subtype after whitespace (“ \t”), which if specified is a lowercase
+alphanumeric (“a-z0-9”) word in parentheses (“()”).
+The subtype is optional in the syntax but may be mandatory for particular
+source format revisions.
+
+The source formats currently supported by B<dpkg> are B<1.0>,
+B<2.0>, B<3.0 (native)>, B<3.0 (quilt)>, B<3.0 (git)>,
+B<3.0 (bzr)> and B<3.0 (custom)>.
+See L<dpkg-source(1)> for their description.
+
+=item B<Source:> I<source-name> (required)
+
+The value of this field determines the package name, and is used to
+generate file names by most installation tools.
+
+=item B<Binary:> I<binary-package-list>
+
+This folded field lists binary packages which this source package can produce,
+separated by commas.
+
+This field has now been superseded by the B<Package-List> field, which
+gives enough information about what binary packages are produced on which
+architecture, build-profile and other involved restrictions.
+
+=item B<Architecture:> I<arch-list> (recommended)
+
+A list of architectures and architecture wildcards separated by spaces
+which specify the type of hardware this package can be compiled for.
+Common architecture names and architecture wildcards are B<amd64>,
+B<armel>, B<i386>, B<linux-any>, B<any-amd64>, etc.
+
+Note that the B<all> value is meant for packages that are architecture
+independent, and B<any> for packages that are architecture dependent.
+The list may include (or consist solely of) the special value B<all>.
+When the list contains the architecture wildcard B<any>, the only
+other value allowed in the list is B<all>.
+
+The field value is generally generated from B<Architecture> fields
+from in the I<debian/control> in the source package.
+
+=item B<Version:> I<version-string> (required)
+
+Typically, this is the original package's version number in whatever form
+the program's author uses.
+It may also include a Debian revision number (for non-native packages).
+The exact format and sorting algorithm are described in
+L<deb-version(7)>.
+
+=item B<Origin:> I<name>
+
+The name of the distribution this package is originating from.
+
+=item B<Maintainer:> I<fullname-email> (recommended)
+
+Should be in the format “Joe Bloggs E<lt>jbloggs@foo.comE<gt>”, and is
+typically the person who created the package, as opposed to the author
+of the software that was packaged.
+
+=item B<Uploaders:> I<fullname-email-list>
+
+Lists all the names and email addresses of co-maintainers of the package,
+in the same format as the B<Maintainer> field.
+Multiple co-maintainers should be separated by a comma.
+
+=item B<Description> I<short-description>
+
+=item S< >I<long-description>
+
+The format for the source package description is a short brief summary on the
+first line (after the B<Description> field).
+The following lines should be used as a longer, more detailed description.
+Each line of the long description must be preceded by a space, and blank
+lines in the long description must contain a single ‘B<.>’ following
+the preceding space.
+
+=item B<Homepage:> I<url>
+
+The upstream project home page I<url>.
+
+=item B<Standards-Version:> I<version-string> (recommended)
+
+This documents the most recent version of the distribution policy standards
+this package complies with.
+
+=item B<Vcs-Browser:> I<url>
+
+The I<url> of a web interface to browse the Version Control System
+repository.
+
+=item B<Vcs-Arch:> I<url>
+
+=item B<Vcs-Bzr:> I<url>
+
+=item B<Vcs-Cvs:> I<url>
+
+=item B<Vcs-Darcs:> I<url>
+
+=item B<Vcs-Git:> I<url>
+
+=item B<Vcs-Hg:> I<url>
+
+=item B<Vcs-Mtn:> I<url>
+
+=item B<Vcs-Svn:> I<url>
+
+These fields declare the I<url> of the Version Control System repository
+used to maintain this package.
+See L<deb-src-control(5)> for more details.
+
+=item B<Testsuite:> I<name-list>
+
+This field declares that the source package contains the specified test suites.
+The value is a comma-separated list of test suites.
+If the B<autopkgtest> value is present, a I<debian/tests/control> is
+expected to be present, if the file is present but not the value, then
+B<dpkg-source> will automatically add it, preserving previous values.
+
+=item B<Testsuite-Triggers:> I<package-list>
+
+This field declares the comma-separated union of all test dependencies
+(B<Depends> fields in I<debian/tests/control> file), with all
+restrictions removed, and OR dependencies flattened (that is, converted to
+separate AND relationships), except for binaries generated by this source
+package and its meta-dependency equivalent B<@>.
+
+B<Rationale>: this field is needed because otherwise to be able to get the
+test dependencies, each source package would need to be unpacked.
+
+=item B<Build-Depends:> I<package-list>
+
+=item B<Build-Depends-Arch:> I<package-list>
+
+=item B<Build-Depends-Indep:> I<package-list>
+
+=item B<Build-Conflicts:> I<package-list>
+
+=item B<Build-Conflicts-Arch:> I<package-list>
+
+=item B<Build-Conflicts-Indep:> I<package-list>
+
+These fields declare relationships between the source package and packages
+used to build it.
+They are discussed in the L<deb-src-control(5)> manual page.
+
+=item B<Package-List:>
+
+=item S< >I<package> I<package-type> I<section> I<priority> I<key-value-list>
+
+This multiline field contains a list of binary packages generated by this
+source package.
+
+The I<package> is the binary package name.
+
+The I<package-type> is the binary package type, usually B<deb>, another
+common value is B<udeb>.
+
+The I<section> and I<priority> match the binary package fields of the
+same name.
+
+The I<key-value-list> is a space separated I<key>B<=>I<value> list,
+and the currently known optional keys are:
+
+=over
+
+=item B<arch>
+
+The architecture restriction from the binary package B<Architecture>
+field, with spaces converted to ‘,’.
+
+=item B<profile>
+
+The normalized build-profile restriction formula from the binary package
+B<Build-Profile> field, with ORs converted to ‘+’ and ANDs to
+‘,’.
+
+=item B<protected>
+
+If the binary package is protected, this key will contain the value of the
+B<Protected> field, that is a B<yes> value.
+
+Supported since dpkg 1.20.1.
+
+=item B<essential>
+
+If the binary package is essential, this key will contain the value of the
+B<Essential> field, that is a B<yes> value.
+
+=back
+
+=item B<Files:> (required)
+
+=item B<Checksums-Sha1:> (required)
+
+=item B<Checksums-Sha256:> (required)
+
+=item S< >I<checksum> I<size> I<filename>
+
+These multiline fields contain a list of files with a checksum and size
+for each one.
+These fields have the same syntax and differ only in the checksum algorithm
+used: MD5 for B<Files>, SHA-1 for B<Checksums-Sha1> and SHA-256 for
+B<Checksums-Sha256>.
+
+The first line of the field value (the part on the same line as the field
+name followed by a colon) is always empty.
+The content of the field is expressed as continuation lines, one line per file.
+Each line consists of the checksum, a space, the file size, a space, and the
+file name.
+
+These fields list all files that make up the source package.
+The list of files in these fields must match the list of files in the
+other related fields.
+
+=back
+
+=head1 BUGS
+
+The B<Format> field conflates the format for the B<.dsc> file itself
+and the format of the extracted source package.
+
+=head1 SEE ALSO
+
+L<deb822(5)>,
+L<deb-src-control(5)>,
+L<deb-version(7)>,
+L<dpkg-source(1)>.