Skip to content

Commit 5f8e846

Browse files
authored
Merge branch 'main' into mir-when-is-it-needed
2 parents 7da64b5 + 0dd093d commit 5f8e846

File tree

70 files changed

+2818
-3846
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

70 files changed

+2818
-3846
lines changed

docs/.custom_wordlist.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,7 @@ packageset
181181
PDFs
182182
PID
183183
plantuml
184+
Postconf
184185
powerpc
185186
PPA
186187
PPAs
Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
(bug-fix-a-package)=
1+
(fix-a-bug-in-a-package)=
2+
# Fix a bug in a package
23

3-
# How to bug-fix a package
4+
TODO: This could be a combination of:
45

6+
- {ref}`propose-changes`
7+
- {ref}`making-changes-to-a-package`
Lines changed: 29 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1+
.. _build-packages:
2+
13
Build packages
24
==============
35

4-
In Ubuntu, packages can be built in several ways, depending on the intended
5-
artifacts. We cover the following types of builds:
6+
In Ubuntu, packages can be built in several ways, depending on the intended artifacts. We cover the following types of builds:
67

78
* Source and binary (using ``sbuild`` for a clean environment)
89
* Binary-only (using ``sbuild`` for a clean environment)
@@ -11,69 +12,59 @@ artifacts. We cover the following types of builds:
1112

1213
(Many other backends are available, including an ``schroot``-based backend.)
1314

14-
Only source uploads are permitted to PPAs or the archive. That
15-
being said, it is best practice to perform a local build and iron out any
16-
potential issues prior to uploading it to any archive.
15+
Only source uploads are permitted to PPAs or the archive. That said, it is best practice to perform a local build and fix any potential issues before uploading it to any archive.
1716

1817

1918
Prerequisites
2019
-------------
2120

22-
.. code-block:: text
21+
.. code-block:: none
2322
2423
$ sudo apt install sbuild debhelper ubuntu-dev-tools piuparts
2524
26-
All of the following sections assume you have already fetched the packaging
27-
and are in the same directory as :file:`debian/`.
25+
All of the following sections assume you have already fetched the packaging and are in the same directory as the :file:`debian/` sub-directory.
2826

2927

3028
``sbuild``-based builds
3129
-----------------------
3230

33-
This is the standard way of building a package for Ubuntu. All of the Debian
34-
and Ubuntu infrastructure use :manpage:`sbuild(1)`, so it is beneficial to
35-
learn how to use it. For more information on setting up :manpage:`sbuild(1)`,
36-
refer to the links in the Resources section.
31+
This is the standard way of building a package for Ubuntu. All of the Debian and Ubuntu infrastructure use :manpage:`sbuild(1)`. For more information on setting up :manpage:`sbuild(1)`, refer to the links at the end of this article.
3732

3833
To do a binary-only build of a package using ``sbuild``, run:
3934

40-
.. code-block:: text
35+
.. code-block:: none
4136
42-
$ sbuild -c <RELEASE>-<ARCH>[-shm]
37+
$ sbuild --chroot <RELEASE>-<ARCH>[-shm]
4338
4439
.. note::
4540

46-
It is possible to use ``-d`` instead of ``-c``, but that causes the produced
47-
files to contain the entire chroot name (``<RELEASE>-<ARCH>[-shm]``) instead
48-
of just ``<RELEASE>``. An example chroot name is ``noble-amd64-shm``.
41+
It is possible to use ``--dist`` (``-d``) to specify the distribution for the build instead of ``--chroot``, which explicitly selects the chroot to use, but that causes the produced files to contain the entire chroot name (``<RELEASE>-<ARCH>[-shm]``) instead of just ``<RELEASE>``. An example chroot name is ``noble-amd64-shm``.
4942

50-
To explicitly run Lintian following the build:
43+
To explicitly run :term:`lintian` following the build:
5144

52-
.. code-block:: text
45+
.. code-block:: none
5346
5447
$ sbuild -c <RELEASE>-<ARCH>[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"]
5548
5649
To build a package without running :manpage:`dh_clean(1)`, run:
5750

58-
.. code-block:: text
51+
.. code-block:: none
5952
6053
$ sbuild -c <RELEASE>-<ARCH>[-shm] --no-clean-source
6154
6255
To build both a binary *and* a source package with one ``sbuild`` run:
6356

64-
.. code-block:: text
57+
.. code-block:: none
6558
6659
$ sbuild -c <RELEASE>-<ARCH>[-shm] -s
6760
6861
.. note::
6962

70-
Launchpad rejects uploads that contains both binaries and sources.
71-
However, this is required for uploads to the Debian NEW queue. That being
72-
said, uploads to Debian with binaries `do not migrate to Testing <https://lists.debian.org/debian-devel-announce/2019/07/msg00002.html>`_.
63+
Launchpad rejects uploads that contains both binaries and sources. However, this is required for uploads to the Debian NEW queue. That said, uploads to Debian with binaries `do not migrate to Testing <https://lists.debian.org/debian-devel-announce/2019/07/msg00002.html>`_.
7364

74-
Here is a complete, working example of running the ``autopkgtest`` following the build:
65+
Here is a complete, working example of running :manpage:`autopkgtest(1)` following the build:
7566

76-
.. code-block:: text
67+
.. code-block:: none
7768
7869
$ sbuild -c noble-amd64-shm --run-autopkgtest \
7970
--autopkgtest-virt-server=qemu \
@@ -87,33 +78,29 @@ Here is a complete, working example of running the ``autopkgtest`` following the
8778
Building with ``debuild``
8879
-------------------------
8980

90-
:manpage:`debuild(1)` (short for :manpage:`dpkg-buildpackage(1)`) is
91-
another tool used to build Debian packages. It is part of the
92-
:manpage:`debhelper(7)` package and written in Perl.
81+
:manpage:`debuild(1)` (short for :manpage:`dpkg-buildpackage(1)`) is another tool used to build Debian packages. It is part of the :manpage:`debhelper(7)` package and written in Perl.
9382

94-
Ubuntu maintain its own version the ``debhelper`` package. Therefore,
95-
packages built on Debian may be slightly different than packages built on
96-
Ubuntu.
83+
Ubuntu maintains its own version of the ``debhelper`` package. Therefore, packages built on Debian may be slightly different than packages built on Ubuntu.
9784

9885

9986
Source-only builds
10087
~~~~~~~~~~~~~~~~~~
10188

10289
To build a source package *without* including the upstream tarball, run:
10390

104-
.. code-block:: text
91+
.. code-block:: none
10592
10693
$ debuild -S -d
10794
10895
To build a source package *with* the upstream tarball, run:
10996

110-
.. code-block:: text
97+
.. code-block:: none
11198
11299
$ debuild -S -d -sa
113100
114-
To build a source package without running Lintian, run:
101+
To build a source package without running :term:`lintian`, run:
115102

116-
.. code-block:: text
103+
.. code-block:: none
117104
118105
$ debuild --no-lintian -S -d
119106
@@ -123,35 +110,28 @@ To build a source package without running Lintian, run:
123110

124111
To build a source package without running :manpage:`dh_clean(1)`, run:
125112

126-
.. code-block:: text
113+
.. code-block:: none
127114
128115
$ debuild -S -d -nc
129116
130117
.. note::
131118

132119
This tends to fix failures regarding missing build dependencies.
133120

134-
To build a source package without a cryptographic signature (not recommended), run:
135-
136-
.. code-block:: text
137-
138-
$ debuild -S -d -us -uc
139-
140121

141122
Local binary-only builds
142123
~~~~~~~~~~~~~~~~~~~~~~~~
143124

144-
This is really only useful for packages you need to test locally or
145-
packages with minimal build dependencies. Otherwise use :manpage:`sbuild(1)`.
125+
This is really only useful for packages you need to test locally or packages with minimal build dependencies. Otherwise use :manpage:`sbuild(1)`.
146126

147127
To do a binary-only build of a package, run:
148128

149-
.. code-block:: text
129+
.. code-block:: none
150130
151131
$ debuild -b
152132
153133
154-
Resources
155-
---------
134+
Further reading
135+
---------------
156136

157-
* `Chapter 6. Building the package (Debian New Maintainers' Guide) <https://www.debian.org/doc/manuals/maint-guide/build.html>`_
137+
* Debian New Maintainers' Guide: `Building the package <https://www.debian.org/doc/manuals/maint-guide/build.html>`_
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
(debug-an-apport-bug)=
22

3-
# How to debug an apport bug
3+
# Debug an apport bug
44

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
.. _download-a-new-upstream-version:
2+
3+
Download a new upstream version
4+
===============================
5+
6+
Download a new :term:`upstream <Upstream>` release or checking if a newer upstream release exists is usually needed when:
7+
8+
- Fixing a bug to rule out that a more recent version may have already fixed the bug.
9+
- (As a :term:`source package <Source Package>` :term:`maintainer <Maintainer>`) to check for, download, and package a newer upstream release.
10+
11+
Most of the source packages contain a ``watch`` file in the ``debian`` directory. This is a configuration file for the :manpage:`uscan(1)` utility, which allows you to automatically search HTTP or FTP sites or :manpage:`git(1)` repositories for newly available updates of the upstream project.
12+
13+
.. note::
14+
If the source package does not contain a :file:`debian/watch` file, there may be
15+
an explanation and instructions in the :file:`debain/README.source` or
16+
:file:`debian/README.debian` file (if available) that tell you how to proceed.
17+
18+
Best practices
19+
--------------
20+
21+
Download upstream file(s) manually only if there is no automatic download mechanism and you can't find any download instructions.
22+
23+
Packages may get distributed to hundreds of thousands of users. Humans are the weakest link in this distribution chain because we may accidentally miss or skip a verification step, misspell a :term:`URL`, copy the wrong URL or copy a URL only partially, etc.
24+
25+
When downloading upstream file(s) manually, make sure to verify :term:`cryptographic signatures <Cryptographic Signature>` (if available). The :term:`signing key` of the upstream project should be stored in the source package as :file:`debian/upstream/signing-key.asc` (if the upstream project has a signing key).
26+
27+
:manpage:`uscan(1)` verifies downloads against this signing key automatically (if available).
28+
29+
Download new upstream version (if available)
30+
--------------------------------------------
31+
32+
Running :manpage:`uscan(1)` from the :term:`root` of the :term:`source tree` checks if a newer upstream version exists and downloads it:
33+
34+
.. code-block:: bash
35+
36+
uscan
37+
38+
If :manpage:`uscan(1)` cannot find a newer upstream version, it returns exit code `1` and prints nothing to the :term:`standard output`.
39+
40+
:manpage:`uscan(1)` reads the first entry in :file:`debian/changelog` to determine the name and version of the source package.
41+
42+
Add the ``--verbose`` flag to see more information (e.g., which version :manpage:`uscan(1)` found):
43+
44+
.. code-block:: bash
45+
46+
uscan --verbose
47+
48+
Check for new upstream version (no download)
49+
--------------------------------------------
50+
51+
To check if a new update is available without downloading anything, run the :manpage:`uscan(1)` command with the ``--safe`` flag from the :term:`root` of the source tree:
52+
53+
.. code-block:: bash
54+
55+
uscan --safe
56+
57+
Force the download
58+
------------------
59+
60+
Use the ``--force-download`` flag to download an upstream release from the upstream project, even if the upstream release is up-to-date with the source package:
61+
62+
.. code-block:: bash
63+
64+
uscan --force-download
65+
66+
Download the source of older versions from the upstream project
67+
---------------------------------------------------------------
68+
69+
To download the source of a specific version from the upstream project, use the ``--download-version`` flag.
70+
71+
Basic syntax:
72+
73+
.. code-block:: none
74+
75+
uscan --download-version VERSION
76+
77+
For example:
78+
79+
.. code-block:: bash
80+
81+
uscan --download-version '1.0'
82+
83+
To download the source for the current version of the source package from the upstream project, use the ``--download-current-version`` flag instead, which parses the version to download from the first entry in the :file:`debian/changelog` file:
84+
85+
.. code:: bash
86+
87+
uscan --download-current-version
88+
89+
.. note::
90+
91+
The ``--download-version`` and ``--download-current-version`` flags are both a :term:`best-effort` features of :manpage:`uscan(1)`.
92+
93+
There are special cases where they do not work for technical reasons.
94+
95+
96+
Further reading
97+
---------------
98+
99+
- Manual page -- :manpage:`uscan(1)`
100+
- Debian wiki -- `debian/watch <https://wiki.debian.org/debian/watch>`_
101+
- Debian policy ``4.6.2.0`` -- `Upstream source location: debian/watch <https://www.debian.org/doc/debian-policy/ch-source.html#upstream-source-location-debian-watch>`_

docs/staging/PG/contributors/bug-fix/extract-packages.rst renamed to docs/contributors/bug-fix/extract-packages.rst

Lines changed: 15 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,23 @@ Extract packages
55

66
This article demonstrates how to extract the contents of Debian packages.
77

8-
See also the article :ref:`package-model` for a deeper
9-
understanding of package formats.
8+
See also the article :ref:`package-model` for a deeper understanding of package formats.
109

11-
.. _ExtractSourcePackage:
1210

13-
Extract a source package
11+
.. _extract-a-source-package:
12+
13+
Extract a source package
1414
------------------------
1515

1616
This section demonstrates how to extract the content of a source package.
1717

1818
.. note::
1919

20-
A source package archive has the file extension `.dsc`.
21-
See also the manual page :manpage:`dsc(5)` for further information.
20+
A source package archive has the file extension `.dsc`. See also the manual page :manpage:`dsc(5)` for further information.
2221

2322
.. important::
2423

25-
Make sure that you have the :pkg:`dpkg-dev` package installed.
26-
To install it, run the following commands in a terminal:
24+
Make sure you have the :pkg:`dpkg-dev` package installed. To install it:
2725

2826
.. code-block:: none
2927
@@ -39,15 +37,12 @@ Run the following command in a terminal:
3937
The path to the source package control file.
4038

4139
``OUTPUT-DIRECTORY`` (optional)
42-
The path to the directory where to extract the content of the source
43-
package to. This directory **must not** exist. If no output directory is
44-
specified, the content is extracted into a directory named
45-
``NAME-VERSION`` (where ``NAME`` is the name of the source package and
46-
``VERSION`` its version) under the current working directory.
40+
The path to the directory where to extract the content of the source package to. This directory **must not** exist. If no output directory is specified, the content is extracted into a directory named ``NAME-VERSION`` (where ``NAME`` is the name of the source package and ``VERSION`` its version) under the current working directory.
4741

4842
See the manual page :manpage:`dpkg-source(1)` for further information.
4943

50-
.. _ExtractBinaryPackage:
44+
45+
.. _extract-a-binary-package:
5146

5247
Extract a binary package
5348
------------------------
@@ -56,29 +51,25 @@ This section demonstrates how to extract the content a binary package.
5651

5752
.. note::
5853

59-
A binary package archive has the file extension `.deb`.
60-
See also the manual page :manpage:`deb(5)` for further information.
54+
A binary package archive has the file extension `.deb`. See the manual page :manpage:`deb(5)` for further information.
6155

62-
Run the following command in a terminal:
56+
Run:
6357

6458
.. code-block:: none
6559
66-
dpkg-deb --extract BINARY-PACKAGE.deb OUTPUT-DIRECTORY
60+
dpkg-deb --extract <BINARY-PACKAGE>.deb <OUTPUT-DIRECTORY>
6761
6862
``BINARY-PACKAGE.deb``
6963
The path to the binary package control file.
7064

7165
``OUTPUT-DIRECTORY``
72-
The path to the directory where to extract the content of the binary
73-
package to. In comparison to :ref:`ExtractSourcePackage`, this directory
74-
can already exist and even contain files.
66+
The path to the directory where to extract the content of the binary package. In comparison to :ref:`extract-a-source-package`, this directory can already exist and even contain files.
7567

7668
See the manual page :manpage:`dpkg-deb(1)` for further information.
7769

7870
.. tip::
7971

80-
Using ``--vextract`` instead of ``--extract`` also outputs a list of
81-
the extracted files to :term:`standard output <Standard Output>`.
72+
Using ``--vextract`` instead of ``--extract`` also outputs a list of the extracted files to :term:`standard output`.
8273

8374
To just list the files that the package contains, use the ``--contents`` option:
8475

@@ -88,6 +79,4 @@ See the manual page :manpage:`dpkg-deb(1)` for further information.
8879
8980
.. tip::
9081

91-
You can also replace ``dpkg-deb`` with ``dpkg`` for the examples
92-
demonstrated here. ``dpkg`` forwards the options to ``dpkg-deb``.
93-
See the manual page :manpage:`dpkg(1)` for further information.
82+
You can also replace ``dpkg-deb`` with ``dpkg`` for the examples shown here. ``dpkg`` forwards the options to ``dpkg-deb``. See the manual page :manpage:`dpkg(1)` for further information.

0 commit comments

Comments
 (0)