Bug#658009: debian-policy: dpkg-buildpackage -rroot-command out of date
Sam Morris wrote:
> C.1.2 says:
>
> If no root-command is supplied then dpkg-buildpackage will take
> no special action to gain root privilege, so that for most
> packages it will have to be invoked as root to start with.
>
> This is wrong according to the dpkg-buildpackage man page
True. How about this patch?
---
policy.sgml | 295 ++---------------------------------------------------------
1 files changed, 9 insertions(+), 286 deletions(-)
diff --git a/policy.sgml b/policy.sgml
index c1ff4b4c..6463713d 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -10295,19 +10295,8 @@ END-INFO-DIR-ENTRY
Various tools are provided for manipulating source packages;
they pack and unpack sources and help build of binary
packages and help manage the distribution of new versions.
- </p>
-
- <p>
- They are introduced and typical uses described here; see
- <manref name="dpkg-source" section="1"> for full
- documentation about their arguments and operation.
- </p>
-
- <p>
- For examples of how to construct a Debian source package,
- and how to use those utilities that are used by Debian
- source packages, please see the <prgn>hello</prgn> example
- package.
+ See <manref name="dpkg-source" section="1"> for
+ documentation about their typical uses, arguments and operation.
</p>
<sect1 id="pkg-dpkg-source">
@@ -10316,46 +10305,7 @@ END-INFO-DIR-ENTRY
packages
</heading>
- <p>
- This program is frequently used by hand, and is also
- called from package-independent automated building scripts
- such as <prgn>dpkg-buildpackage</prgn>.
- </p>
-
- <p>
- To unpack a package it is typically invoked with
- <example>
- dpkg-source -x <var>.../path/to/filename</var>.dsc
- </example>
- </p>
-
- <p>
- with the <file><var>filename</var>.tar.gz</file> and
- <file><var>filename</var>.diff.gz</file> (if applicable) in
- the same directory. It unpacks into
- <file><var>package</var>-<var>version</var></file>, and if
- applicable
- <file><var>package</var>-<var>version</var>.orig</file>, in
- the current directory.
- </p>
-
- <p>
- To create a packed source archive it is typically invoked:
- <example>
- dpkg-source -b <var>package</var>-<var>version</var>
- </example>
- </p>
-
- <p>
- This will create the <file>.dsc</file>, <file>.tar.gz</file> and
- <file>.diff.gz</file> (if appropriate) in the current
- directory. <prgn>dpkg-source</prgn> does not clean the
- source tree first - this must be done separately if it is
- required.
- </p>
-
- <p>
- See also <ref id="pkg-sourcearchives">.</p>
+ <p>See <manref name="dpkg-source" section="1">.</p>
</sect1>
@@ -10365,57 +10315,7 @@ END-INFO-DIR-ENTRY
control script
</heading>
- <p>
- <prgn>dpkg-buildpackage</prgn> is a script which invokes
- <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
- targets <tt>clean</tt>, <tt>build</tt> and
- <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
- <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
- source and binary package upload.
- </p>
-
- <p>
- It is usually invoked by hand from the top level of the
- built or unbuilt source directory. It may be invoked with
- no arguments; useful arguments include:
- <taglist compact="compact">
- <tag><tt>-uc</tt>, <tt>-us</tt></tag>
- <item>
- <p>
- Do not sign the <tt>.changes</tt> file or the
- source package <tt>.dsc</tt> file, respectively.</p>
- </item>
- <tag><tt>-p<var>sign-command</var></tt></tag>
- <item>
- <p>
- Invoke <var>sign-command</var> instead of finding
- <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
- <var>sign-command</var> must behave just like
- <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
- </item>
- <tag><tt>-r<var>root-command</var></tt></tag>
- <item>
- <p>
- When root privilege is required, invoke the command
- <var>root-command</var>. <var>root-command</var>
- should invoke its first argument as a command, from
- the <prgn>PATH</prgn> if necessary, and pass its
- second and subsequent arguments to the command it
- calls. If no <var>root-command</var> is supplied
- then <var>dpkg-buildpackage</var> will take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.</p>
- </item>
- <tag><tt>-b</tt>, <tt>-B</tt></tag>
- <item>
- <p>
- Two types of binary-only build and upload - see
- <manref name="dpkg-source" section="1">.
- </p>
- </item>
- </taglist>
- </p>
+ <p>See <manref name="dpkg-buildpackage" section="1">.</p>
</sect1>
<sect1 id="pkg-dpkg-gencontrol">
@@ -10424,61 +10324,7 @@ END-INFO-DIR-ENTRY
control files
</heading>
- <p>
- This program is usually called from <file>debian/rules</file>
- (see <ref id="pkg-sourcetree">) in the top level of the source
- tree.
- </p>
-
- <p>
- This is usually done just before the files and directories in the
- temporary directory tree where the package is being built have their
- permissions and ownerships set and the package is constructed using
- <prgn>dpkg-deb/</prgn>
- <footnote>
- This is so that the control file which is produced has
- the right permissions
- </footnote>.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> must be called after all the
- files which are to go into the package have been placed in
- the temporary build directory, so that its calculation of
- the installed size of a package is correct.
- </p>
-
- <p>
- It is also necessary for <prgn>dpkg-gencontrol</prgn> to
- be run after <prgn>dpkg-shlibdeps</prgn> so that the
- variable substitutions created by
- <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
- are available.
- </p>
-
- <p>
- For a package which generates only one binary package, and
- which builds it in <file>debian/tmp</file> relative to the top
- of the source package, it is usually sufficient to call
- <prgn>dpkg-gencontrol</prgn>.
- </p>
-
- <p>
- Sources which build several binaries will typically need
- something like:
- <example>
- dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
- </example> The <tt>-P</tt> tells
- <prgn>dpkg-gencontrol</prgn> that the package is being
- built in a non-default directory, and the <tt>-p</tt>
- tells it which package's control file should be generated.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> also adds information to the
- list of files in <file>debian/files</file>, for the benefit of
- (for example) a future invocation of
- <prgn>dpkg-genchanges</prgn>.</p>
+ <p>See <manref name="dpkg-gencontrol" section="1">.</p>
</sect1>
<sect1 id="pkg-dpkg-shlibdeps">
@@ -10487,80 +10333,7 @@ END-INFO-DIR-ENTRY
dependencies
</heading>
- <p>
- This program is usually called from <file>debian/rules</file>
- just before <prgn>dpkg-gencontrol</prgn> (see <ref
- id="pkg-sourcetree">), in the top level of the source tree.
- </p>
-
- <p>
- Its arguments are executables and shared libraries
- <footnote>
- <p>
- They may be specified either in the locations in the
- source tree where they are created or in the locations
- in the temporary build tree where they are installed
- prior to binary package creation.
- </p>
- </footnote> for which shared library dependencies should
- be included in the binary package's control file.
- </p>
-
- <p>
- If some of the found shared libraries should only
- warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
- some warrant a <tt>Pre-Depends</tt>, this can be achieved
- by using the <tt>-d<var>dependency-field</var></tt> option
- before those executable(s). (Each <tt>-d</tt> option
- takes effect until the next <tt>-d</tt>.)
- </p>
-
- <p>
- <prgn>dpkg-shlibdeps</prgn> does not directly cause the
- output control file to be modified. Instead by default it
- adds to the <file>debian/substvars</file> file variable
- settings like <tt>shlibs:Depends</tt>. These variable
- settings must be referenced in dependency fields in the
- appropriate per-binary-package sections of the source
- control file.
- </p>
-
- <p>
- For example, a package that generates an essential part
- which requires dependencies, and optional parts that
- which only require a recommendation, would separate those
- two sets of dependencies into two different fields.<footnote>
- At the time of writing, an example for this was the
- <package/xmms/ package, with Depends used for the xmms
- executable, Recommends for the plug-ins and Suggests for
- even more optional features provided by unzip.
- </footnote>
- It can say in its <file>debian/rules</file>:
- <example>
- dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
- -dRecommends <var>optionalpart anotheroptionalpart</var>
- </example>
- and then in its main control file <file>debian/control</file>:
- <example>
- <var>...</var>
- Depends: ${shlibs:Depends}
- Recommends: ${shlibs:Recommends}
- <var>...</var>
- </example>
- </p>
-
- <p>
- Sources which produce several binary packages with
- different shared library dependency requirements can use
- the <tt>-p<var>varnameprefix</var></tt> option to override
- the default <tt>shlibs:</tt> prefix (one invocation of
- <prgn>dpkg-shlibdeps</prgn> per setting of this option).
- They can thus produce several sets of dependency
- variables, each of the form
- <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
- which can be referred to in the appropriate parts of the
- binary package control files.
- </p>
+ <p>See <manref name="dpkg-shlibdeps" section="1">.</p>
</sect1>
@@ -10570,36 +10343,7 @@ END-INFO-DIR-ENTRY
<file>debian/files</file>
</heading>
- <p>
- Some packages' uploads need to include files other than
- the source and binary package files.
- </p>
-
- <p>
- <prgn>dpkg-distaddfile</prgn> adds a file to the
- <file>debian/files</file> file so that it will be included in
- the <file>.changes</file> file when
- <prgn>dpkg-genchanges</prgn> is run.
- </p>
-
- <p>
- It is usually invoked from the <tt>binary</tt> target of
- <file>debian/rules</file>:
- <example>
- dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
- </example>
- The <var>filename</var> is relative to the directory where
- <prgn>dpkg-genchanges</prgn> will expect to find it - this
- is usually the directory above the top level of the source
- tree. The <file>debian/rules</file> target should put the
- file there just before or just after calling
- <prgn>dpkg-distaddfile</prgn>.
- </p>
-
- <p>
- The <var>section</var> and <var>priority</var> are passed
- unchanged into the resulting <file>.changes</file> file.
- </p>
+ <p>See <manref name="dpkg-distaddfile" section="1">.</p>
</sect1>
@@ -10609,21 +10353,7 @@ END-INFO-DIR-ENTRY
upload control file
</heading>
- <p>
- This program is usually called by package-independent
- automatic building scripts such as
- <prgn>dpkg-buildpackage</prgn>, but it may also be called
- by hand.
- </p>
-
- <p>
- It is usually called in the top level of a built source
- tree, and when invoked with no arguments will print out a
- straightforward <file>.changes</file> file based on the
- information in the source package's changelog and control
- file and the binary and source packages which should have
- been built.
- </p>
+ <p>See <manref name="dpkg-genchanges" section="1">.</p>
</sect1>
@@ -10633,14 +10363,7 @@ END-INFO-DIR-ENTRY
representation of a changelog
</heading>
- <p>
- This program is used internally by
- <prgn>dpkg-source</prgn> et al. It may also occasionally
- be useful in <file>debian/rules</file> and elsewhere. It
- parses a changelog, <file>debian/changelog</file> by default,
- and prints a control-file format representation of the
- information in it to standard output.
- </p>
+ <p>See <manref name="dpkg-parsechangelog" section="1">.<p>
</sect1>
<sect1 id="pkg-dpkg-architecture">
--
1.7.9
Reply to: