FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Debian > Debian dpkg

 
 
LinkBack Thread Tools
 
Old 11-23-2010, 04:13 PM
Oxan van Leeuwen
 
Default Create manpage deb-src-control(5)

Hi,

I participate in the Google Code-In and completed the task of writing a manpage
for deb-src-control(5), the format of the debian/control files in source
packages. I've also documented some fields in the deb-control(5) manpage.

Please CC me on replies because I'm not on the list.

Thanks,
Oxan van Leeuwen

---
man/Makefile.am | 1 +
man/deb-control.5 | 26 ++++
man/deb-src-control.5 | 323 +++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 350 insertions(+), 0 deletions(-)
create mode 100644 man/deb-src-control.5

diff --git a/man/Makefile.am b/man/Makefile.am
index 7baef48..5eedfb9 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -90,6 +90,7 @@ dist-hook: man.stamp

dist_man_MANS =
deb-control.5
+ deb-src-control.5
deb-version.5
deb-shlibs.5
deb-split.5
diff --git a/man/deb-control.5 b/man/deb-control.5
index 59bc69a..1d8db3b 100644
--- a/man/deb-control.5
+++ b/man/deb-control.5
@@ -98,9 +98,35 @@ The upstream project home page URL.
List of tags describing the qualities of the package. The description and
list of supported tags can be found in the fBdebtagsfP package.
.TP
+.BR Multi-Arch: " <same|foreign|allowed>"
+This field is used to indicate how this package should behave on a multi-arch
+installations. The value same means that the package is co-installable with
+itself, but it must not be used to satisfy the dependency of any package of a
+different architecture from itself. The foreign value means that the package is
+not co-installable with itself, but should be allowed to satisfy the dependency
+of a package of a different arch from itself. The allowed value allows
+reverse-dependencies to indicate in their Depends field that they need a
package
+from a foreign architecture, but has no effect otherwise. This field should not
+be present in packages with the Architecture: all field.
+.TP
.BR Source: " <source name>"
The name of the source package that this binary package came from, if
different than the name of the package itself.
+
+.TP
+.PD 0
+.BR Subarchitecture: " <value>"
+.TP
+.PD 0
+.BR Kernel-Version: " <value>"
+.TP
+.PD
+.BR Installer-Menu-Item: " <value>"
+These fields are used by the debian-installer and are usually not needed. See
+/usr/share/doc/debian-installer/devel/modules.txt from the
+.B debian-installer
+package for more details about them.
+
.TP
.BR Depends: " <package list>"
List of packages that are required for this package to provide a
diff --git a/man/deb-src-control.5 b/man/deb-src-control.5
new file mode 100644
index 0000000..df7effe
--- /dev/null
+++ b/man/deb-src-control.5
@@ -0,0 +1,323 @@
+." Author: Oxan van Leeuwen
+." Includes text from the deb-control manapge by Raul Miller
+.TH deb-control 5 "2010-11-22" "Debian Project" "Debian"
+.SH NAME
+deb-src-control - Debian source packages' master control file format
+.
+.SH SYNOPSIS
+control
+.
+.SH DESCRIPTION
+Each Debian source package contains the master `control' file, which contains
+of at least 2 paragraphs, separated by a blank line. The first paragraph lists
+all information about the source package in general, while each following
+paragraph describes exactly one binary package the source package builds.
+Each paragraph consists of a number of fields. Each field begins with a tag,
+such as
+.B Package
+or
+.B Section
+(case insensitive), followed by a colon, and the body of the field. The
+fields are delimited by field tags or empty lines (which ends a paragraph).
+In other words, field text may be multiple lines in length, but the tools that
+handle the file will generally join lines when processing the body of the
field
+(except in the case of the
+.B Description
+field, see below). Lines starting with a fB'#'fP are treated as comments.
+.
+.SH SOURCE FIELDS
+.TP
+.BR Source: " <source package name> (required)"
+The value of this field is the name of the source package, and should
+match the name of the source package in the debian/changelog file. A package
+name must consist only of lower case letters (a-z), digits (0-9), plus (+) and
+minus (-) signs, and periods (.). Package names must be at least two characters
+long and must start with an alphanumeric character.
+
+.TP
+.BR Maintainer: " <fullname email> (required)"
+Should be in the format `Joe Bloggs <jbloggs@foo.com>', and references the
+person who currently maintains the package, as opposed to the author of the
+software or the original packager.
+
+.TP
+.BR Uploaders: " <fullname email>"
+Lists all the names and email addresses of co-maintainers of the package, in
+the same format as the Maintainer field. Multiple co-maintainers should be
+separated by a comma.
+
+.TP
+.BR Standards-Version: " <version string>"
+This documents the most recent version of the standards (which consists of the
+Policy
+Manual and referenced texts from the
+.B debian-policy
+package) this package complies to.
+
+.TP
+.BR DM-Upload-Allowed: " <yes|no>"
+This fields allows the uploading of the package by Debian Maintainers, given
+that he is included in the Maintainer or Uploaders field of the package.
+
+.TP
+.BR Homepage: " <url>"
+The upstream project home page URL.
+
+.TP
+.BR Bugs: " <url>"
+The url of the bug tracking system for this package. The current used format
+is fB<bts_type>://<bts_address>fP, like fBdebbugs://bugs.debian.orgfP. This
+field is usually not needed.
+
+.TP
+.BR Vcs-*: " <url>"
+The url of the Version Control System repository used to maintain this package.
+Currently supported are Arch, Bzr (Bazaar), Cvs, Darcs, Git, Hg (Mercurial),
+Mtn (Monotone) and Svn (Subversion). Usually this field points to the latest
+version of the package, such as the main branch or the trunk.
+
+.TP
+.BR Vcs-Browser: " <url>"
+The url of a webinterface to browse the Version Control System repository.
+
+.TP
+.BR Origin: " <name>"
+The name of the distribution this package is originating from. This field is
+usually not needed.
+
+.TP
+.BR Section: " <section>"
+This is a general field that gives the package a category based on the
+software that it installs. Some common sections are `utils', `net',
+`mail', `text', `x11' etc.
+
+.TP
+.BR Priority: " <priority>"
+Sets the importance of this package in relation to the system as a whole.
+Common priorities are `required', `standard', `optional', `extra' etc.
+

+In Debian, the
+.B Section
+and
+.B Priority
+fields have a defined set of accepted values based on the Policy Manual.
+A list of these values can be obtained from the latest version of the
+.B debian-policy
+package.
+
+.TP
+.BR Build-Depends: " <package list>"
+A list of packages that need to be installed and configured for this package
+to build the architecture dependant packages (where Architecture is not all,
+see below), for example development headers.
+
+.TP
+.BR Build-Depends-Indep: " <package list>"
+Same as Build-Depends, but for when building the architecture independent
+packages. The Build-Depends are also installed in this case.
+
+.TP
+.BR Build-Conflicts: " <package list>"
+A list of packages that should not be installed when the package is build, for
+example because they conflict with the used build system.
+
+.TP
+.BR Build-Conflicts-Indep: " <package list>"
+Same as Build-Conflicts, but for when building the architecture independent
+packages. The Build-Conflicts
+
+

+The syntax of the
+.B Build-Depends
+and
+.B Build-Depends-Indep
+fields is a list of groups of alternative packages. Each group is a list
+of packages separated by vertical bar (or `pipe') symbols, `|'. The
+groups are separated by commas. Commas are to be read as `AND', and pipes
+as `OR', with pipes binding more tightly. Each package name is
+optionally followed by a version number specification in parentheses and an
+architecture specification in square brackets.
+

+The syntax of the
+.B Build-Conflicts
+and
+.B Build-Conflicts-Indep
+fields is a list of comma-separated package names, where the comma is read
+as an `AND'. Specifying alternative packages using a `pipe' is not supported.
+Each package name is optionally followed by a version number specification in
+parentheses and an architecture specification in square brackets.
+

+A version number may start with a `>>', in which case any later version
+will match, and may specify or omit the Debian packaging revision (separated
+by a hyphen). Accepted version relationships are ">>" for greater than,
+"<<" for less than, ">=" for greater than or equal to, "<=" for less than
+or equal to, and "=" for equal to.
+

+A architecture specification consists of one or more architecture names,
+separated by whitespace. Exclamation marks may be prepended to each of the
+names, meaning `NOT'.
+

+Note that dependencies on packages in the
+.B build-essential
+set can be omitted and that declaring build conflicts against them is
+impossible. A list of these packages is in the build-essential package.
+
+
+.SH BINARY FIELDS
+
+.LP
+Note that the
+.BR Priority ", " Section
+and
+.B Homepage
+fields can also be in a binary paragraph to override the global value from the
+source package.
+
+.TP
+.BR Package: " <binary package name> (required)"
+This field is used to name the binary package name. The same restrictions as
+to a source package name apply.
+
+.TP
+.BR Architecture: " <arch|all|any> (required)"
+The architecture specifies on which type of hardware this package runs. For
+packages that run on all architectures, use the
+.B any
+value. For packages that are architecture independent, such as shell and Perl
+scripts or documentation, use the
+.B all
+value. To restrict the packages to a certain set of architectures, specify the
+architecture names, separated by a space.
+
+.TP
+.BR Package-Type: " <deb|udeb>"
+This field indicates whether this binary package is an udeb for use in the
+debian-installer. This field is not needed for normal packages.
+
+.TP
+.PD 0
+.BR Subarchitecture: " <value>"
+.TP
+.PD 0
+.BR Kernel-Version: " <value>"
+.TP
+.PD 0
+.BR Installer-Menu-Item: " <value>"
+These fields are used by the debian-installer and are usually not needed. See
+/usr/share/doc/debian-installer/devel/modules.txt from the
+.B debian-installer
+package for more details about them.
+
+.TP
+.PD 0
+.BR Essential: " <yes|no>"
+.TP
+.PD 0
+.BR Multi-Arch: " <same|foreign|allowed> "
+.TP
+.PD 0
+.BR Tag: " <tag list>"
+.TP
+.PD 0
+.BR Description: " <short description> (required)"
+These fields are described in the
+.BR deb-control (5)
+manual page, as they are copied literally to the control file of the binary
+package.
+
+.TP
+.PD 0
+.BR Depends: " <package list>"
+.TP
+.PD 0
+.BR Pre-Depends: " <package list>"
+.TP
+.PD 0
+.BR Recommends: " <package list>"
+.TP
+.PD 0
+.BR Suggests: " <package list>"
+.TP
+.PD 0
+.BR Breaks: " <package list>"
+.TP
+.PD 0
+.BR Enhances: " <package list>"
+.TP
+.PD 0
+.BR Replaces: " <package list>"
+.TP
+.PD 0
+.BR Conflicts: " <package list>"
+.TP
+.PD 0
+.BR Provides: " <package list>"
+.br
+These fields declare relationships between packages. They are discussed in
+the
+.BR deb-control (5)
+manpage and in the
+.B debian-policy
+package.
+
+.SH USER-DEFINED FIELDS
+It is allowed to add additional user-defined fields to the control file. The
+tools will ignore these fields. If you want the fields to be copied over to
+the output files, such as the binary packages, you need to use a custom naming
+scheme: the fields should start with a X, followed by one or more of the
+letters BCS and a hypen. If the letter B is used, the field will appear in the
+control file in the binary package, see
+.BR deb-control (5)
+, for the letter S in the source package control file as constructed by
+.BR dpkg-source (1)
+and for the letter C in the upload control (.changes) files. Note that the BCS
+letters are stripped when they are copied over to the output files. A field as
+XC-Approved-By will appear as X-Approved-By in the changes file and will not
+appear in the binary or source package control files.
+
+
+.SH EXAMPLE
+." .RS
+.nf
+# Comment
+Source: dpkg
+Section: admin
+Priority: required
+Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
+Origin: debian
+Bugs: debbugs://bugs.debian.org
+# this field is not used by the tools and gets only copied to the changes file
+XC-Old-Version: 1.15.8.5
+Homepage: http://wiki.debian.org/Teams/Dpkg
+Vcs-Browser: http://git.debian.org/?p=dpkg/dpkg.git
+Vcs-Git: git://git.debian.org/git/dpkg/dpkg.git
+Standards-Version: 3.7.3
+Build-Depends: pkg-config, debhelper (>= 4.1.81),
+ libselinux1-dev (>= 1.28-4) [!hurd-i386 !kfreebsd-i386 !kfreebsd-amd64]
+
+Package: dpkg-dev
+Section: utils
+Priority: optional
+Architecture: all
+# this is a (quite useless) custom field in the binary package
+XB-Used-Technology: perl
+Depends: dpkg (>= 1.14.6), perl5, perl-modules, cpio (>= 2.4.2-2), bzip2, lzma,
+ patch (>= 2.2-1), make, binutils, libtimedate-perl
+Recommends: gcc | c-compiler, build-essential
+Suggests: gnupg, debian-keyring
+Conflicts: dpkg-cross (<< 2.0.0), devscripts (<< 2.10.26)
+Replaces: manpages-pl (<= 20051117-1)
+Description: Debian package development tools
+ This package provides the development tools (including dpkg-source)
+ required to unpack, build and upload Debian source packages.
+ .
+ Most Debian source packages will require additional tools to build;
+ for example, most packages need make and the C compiler gcc.
+.fi
+." .RE
+
+
+.SH SEE ALSO
+.BR deb-control (5),
+.BR deb-version (5),
+.BR dpkg-source (1)
--
1.7.0.4


--
To UNSUBSCRIBE, email to debian-dpkg-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 1290532394-4899-1-git-send-email-oxan@oxanvanleeuwen.nl">http://lists.debian.org/1290532394-4899-1-git-send-email-oxan@oxanvanleeuwen.nl
 
Old 11-24-2010, 09:30 AM
Raphael Hertzog
 
Default Create manpage deb-src-control(5)

Hi,

On Tue, 23 Nov 2010, Oxan van Leeuwen wrote:
> I participate in the Google Code-In and completed the task of writing a manpage
> for deb-src-control(5), the format of the debian/control files in source
> packages. I've also documented some fields in the deb-control(5) manpage.

Thanks for your help!

> man/Makefile.am | 1 +
> man/deb-control.5 | 26 ++++
> man/deb-src-control.5 | 323 +++++++++++++++++++++++++++++++++++++++++++++++++

You also have to record the manual page in man/po/po4a.cfg
so that it gets translated.

> --- a/man/deb-control.5
> +++ b/man/deb-control.5
> @@ -98,9 +98,35 @@ The upstream project home page URL.
> List of tags describing the qualities of the package. The description and
> list of supported tags can be found in the fBdebtagsfP package.
> .TP
> +.BR Multi-Arch: " <same|foreign|allowed>"
> +This field is used to indicate how this package should behave on a multi-arch
> +installations. The value same means that the package is co-installable with
> +itself, but it must not be used to satisfy the dependency of any package of a
> +different architecture from itself. The foreign value means that the package is
> +not co-installable with itself, but should be allowed to satisfy the dependency
> +of a package of a different arch from itself. The allowed value allows
> +reverse-dependencies to indicate in their Depends field that they need a
> package
> +from a foreign architecture, but has no effect otherwise. This field should not
> +be present in packages with the Architecture: all field.

The values should be quoted `same', `foreign', `allowed' and you should
say "the value `foo'", because "the foreign/allowed value" is misleading...

> --- /dev/null
> +++ b/man/deb-src-control.5
> @@ -0,0 +1,323 @@
> +." Author: Oxan van Leeuwen
> +." Includes text from the deb-control manapge by Raul Miller

s/manapge/manual page/

> +.TH deb-control 5 "2010-11-22" "Debian Project" "Debian"

deb-src-control

> +.SH DESCRIPTION
> +Each Debian source package contains the master `control' file, which contains
> +of at least 2 paragraphs, separated by a blank line. The first paragraph lists

"consists of at least 2" or "contains at least"

> +all information about the source package in general, while each following
> +paragraph describes exactly one binary package the source package builds.

I would drop the "the source package builds" (the source package might not
build all of them, depending on the architecture).

> +Each paragraph consists of a number of fields. Each field begins with a tag,
> +such as
> +.B Package
> +or
> +.B Section
> +(case insensitive), followed by a colon, and the body of the field. The
> +fields are delimited by field tags or empty lines (which ends a paragraph).
> +In other words, field text may be multiple lines in length, but the tools that
> +handle the file will generally join lines when processing the body of the
> field
> +(except in the case of the
> +.B Description
> +field, see below). Lines starting with a fB'#'fP are treated as comments.

I know this is copied from the existing manpage but I find the wording so
awkward and difficult to understand. And it doesn't make it clear that
multi-line fields are allowed but they have a precise structure to follow.
(i.e. supplementary lines must start with spaces).

I wouldn't mind if you tried to improve it :-)

> +.BR Standards-Version: " <version string>"
> +This documents the most recent version of the standards (which consists of the
> +Policy
> +Manual and referenced texts from the

I would add "Debian" before "Policy manual"

> +.B debian-policy
> +package) this package complies to.
> +
> +.TP
> +.BR DM-Upload-Allowed: " <yes|no>"
> +This fields allows the uploading of the package by Debian Maintainers, given

s/fields/field/, suggestion: "indicates whether the package can be
uploaded by Debian Maintainers appearing in the Maintainer or Uploaders
field"

> +.TP
> +.BR Build-Depends: " <package list>"
> +A list of packages that need to be installed and configured for this package
> +to build the architecture dependant packages (where Architecture is not all,
> +see below), for example development headers.

Not quite true. Those packages are always needed, whatever you build.

s/for this...$/to be able to build the source package./

> +.TP
> +.BR Build-Depends-Indep: " <package list>"
> +Same as Build-Depends, but for when building the architecture independent
> +packages. The Build-Depends are also installed in this case.

s/for/they are only needed/

> +.BR Build-Conflicts: " <package list>"
> +A list of packages that should not be installed when the package is build, for

s/build/built/

> +example because they conflict with the used build system.

s/conflict/interfere/

> +.TP
> +.BR Build-Conflicts-Indep: " <package list>"
> +Same as Build-Conflicts, but for when building the architecture independent

s/for/it must be taken into account only/

> +packages. The Build-Conflicts
> +
> +


Something forgotten here?

And "
" looks weird to me. At least I haven't seen anything like that in
the current manual pages.

> +.TP
> +.BR Package: " <binary package name> (required)"
> +This field is used to name the binary package name. The same restrictions as
> +to a source package name apply.
> +
> +.TP
> +.BR Architecture: " <arch|all|any> (required)"
> +The architecture specifies on which type of hardware this package runs. For
> +packages that run on all architectures, use the
> +.B any
> +value. For packages that are architecture independent, such as shell and Perl
> +scripts or documentation, use the
> +.B all
> +value. To restrict the packages to a certain set of architectures, specify the
> +architecture names, separated by a space.

You can also use architecture wildcards.
http://www.debian.org/doc/debian-policy/ch-customized-programs.html#s-arch-wildcard-spec
http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Architecture

> +
> +.TP
> +.BR Package-Type: " <deb|udeb>"
> +This field indicates whether this binary package is an udeb for use in the
> +debian-installer. This field is not needed for normal packages.

It's a bit too restrictive, we might have other values in the future. I
would say that it's marker to define specific type of packages, that "deb"
is the default and implicit value, and that "udeb" is for size-constrained
packages used by the debian installer.

> +.SH USER-DEFINED FIELDS
> +It is allowed to add additional user-defined fields to the control file. The
> +tools will ignore these fields. If you want the fields to be copied over to
> +the output files, such as the binary packages, you need to use a custom naming
> +scheme: the fields should start with a X, followed by one or more of the
> +letters BCS and a hypen. If the letter B is used, the field will appear in the
> +control file in the binary package, see
> +.BR deb-control (5)
> +, for the letter S in the source package control file as constructed by
> +.BR dpkg-source (1)
> +and for the letter C in the upload control (.changes) files. Note that the BCS

s/files/file/

> +letters are stripped when they are copied over to the output files. A field as
> +XC-Approved-By will appear as X-Approved-By in the changes file and will not
> +appear in the binary or source package control files.

Actually the "X.*-" is stripped in its entirety. So you would get
"Approved-By" in the resulting file.

> +
> +
> +.SH EXAMPLE
> +." .RS
> +.nf
> +# Comment
> +Source: dpkg
> +Section: admin
> +Priority: required
> +Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
> +Origin: debian
> +Bugs: debbugs://bugs.debian.org

I would drop Origin and Bugs, we told users they are not needed usually.

> +# this field is not used by the tools and gets only copied to the changes file
> +XC-Old-Version: 1.15.8.5

A better example featuring a double copy.
XBS-Upstream-Release-Status: stable

> +Package: dpkg-dev
> +Section: utils
> +Priority: optional
> +Architecture: all
> +# this is a (quite useless) custom field in the binary package
> +XB-Used-Technology: perl

Trying to find an example that is more plausible...
XB-Mentoring-Contact: Raphaël Hertzog <hertzog@debian.org>

:-)

Cheers,
--
Raphaël Hertzog ◈ Debian Developer

Follow my Debian News ▶ http://RaphaelHertzog.com (English)
▶ http://RaphaelHertzog.fr (Français)


--
To UNSUBSCRIBE, email to debian-dpkg-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 20101124103044.GB21999@rivendell.home.ouaza.com">h ttp://lists.debian.org/20101124103044.GB21999@rivendell.home.ouaza.com
 

Thread Tools




All times are GMT. The time now is 05:08 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org