You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
6
7
7
8
* Source and binary (using ``sbuild`` for a clean environment)
8
9
* Binary-only (using ``sbuild`` for a clean environment)
@@ -11,69 +12,59 @@ artifacts. We cover the following types of builds:
11
12
12
13
(Many other backends are available, including an ``schroot``-based backend.)
13
14
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.
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.
28
26
29
27
30
28
``sbuild``-based builds
31
29
-----------------------
32
30
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.
37
32
38
33
To do a binary-only build of a package using ``sbuild``, run:
39
34
40
-
.. code-block:: text
35
+
.. code-block:: none
41
36
42
-
$ sbuild -c <RELEASE>-<ARCH>[-shm]
37
+
$ sbuild --chroot <RELEASE>-<ARCH>[-shm]
43
38
44
39
.. note::
45
40
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``.
49
42
50
-
To explicitly run Lintian following the build:
43
+
To explicitly run :term:`lintian` following the build:
To build both a binary *and* a source package with one ``sbuild`` run:
63
56
64
-
.. code-block:: text
57
+
.. code-block:: none
65
58
66
59
$ sbuild -c <RELEASE>-<ARCH>[-shm] -s
67
60
68
61
.. note::
69
62
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>`_.
73
64
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:
75
66
76
-
.. code-block:: text
67
+
.. code-block:: none
77
68
78
69
$ sbuild -c noble-amd64-shm --run-autopkgtest \
79
70
--autopkgtest-virt-server=qemu \
@@ -87,33 +78,29 @@ Here is a complete, working example of running the ``autopkgtest`` following the
87
78
Building with ``debuild``
88
79
-------------------------
89
80
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.
93
82
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.
97
84
98
85
99
86
Source-only builds
100
87
~~~~~~~~~~~~~~~~~~
101
88
102
89
To build a source package *without* including the upstream tarball, run:
103
90
104
-
.. code-block:: text
91
+
.. code-block:: none
105
92
106
93
$ debuild -S -d
107
94
108
95
To build a source package *with* the upstream tarball, run:
109
96
110
-
.. code-block:: text
97
+
.. code-block:: none
111
98
112
99
$ debuild -S -d -sa
113
100
114
-
To build a source package without running Lintian, run:
101
+
To build a source package without running :term:`lintian`, run:
115
102
116
-
.. code-block:: text
103
+
.. code-block:: none
117
104
118
105
$ debuild --no-lintian -S -d
119
106
@@ -123,35 +110,28 @@ To build a source package without running Lintian, run:
123
110
124
111
To build a source package without running :manpage:`dh_clean(1)`, run:
125
112
126
-
.. code-block:: text
113
+
.. code-block:: none
127
114
128
115
$ debuild -S -d -nc
129
116
130
117
.. note::
131
118
132
119
This tends to fix failures regarding missing build dependencies.
133
120
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
-
140
121
141
122
Local binary-only builds
142
123
~~~~~~~~~~~~~~~~~~~~~~~~
143
124
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)`.
146
126
147
127
To do a binary-only build of a package, run:
148
128
149
-
.. code-block:: text
129
+
.. code-block:: none
150
130
151
131
$ debuild -b
152
132
153
133
154
-
Resources
155
-
---------
134
+
Further reading
135
+
---------------
156
136
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>`_
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
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>`_
Copy file name to clipboardExpand all lines: docs/contributors/bug-fix/extract-packages.rst
+15-26Lines changed: 15 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,25 +5,23 @@ Extract packages
5
5
6
6
This article demonstrates how to extract the contents of Debian packages.
7
7
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.
10
9
11
-
.. _ExtractSourcePackage:
12
10
13
-
Extract a source package
11
+
.. _extract-a-source-package:
12
+
13
+
Extract a source package
14
14
------------------------
15
15
16
16
This section demonstrates how to extract the content of a source package.
17
17
18
18
.. note::
19
19
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.
22
21
23
22
.. important::
24
23
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:
27
25
28
26
.. code-block:: none
29
27
@@ -39,15 +37,12 @@ Run the following command in a terminal:
39
37
The path to the source package control file.
40
38
41
39
``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.
47
41
48
42
See the manual page :manpage:`dpkg-source(1)` for further information.
49
43
50
-
.. _ExtractBinaryPackage:
44
+
45
+
.. _extract-a-binary-package:
51
46
52
47
Extract a binary package
53
48
------------------------
@@ -56,29 +51,25 @@ This section demonstrates how to extract the content a binary package.
56
51
57
52
.. note::
58
53
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.
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.
75
67
76
68
See the manual page :manpage:`dpkg-deb(1)` for further information.
77
69
78
70
.. tip::
79
71
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`.
82
73
83
74
To just list the files that the package contains, use the ``--contents`` option:
84
75
@@ -88,6 +79,4 @@ See the manual page :manpage:`dpkg-deb(1)` for further information.
88
79
89
80
.. tip::
90
81
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