From 15d60da1bf9c0ed552d5c8b6f656fb51eab795af Mon Sep 17 00:00:00 2001 From: Simon Quigley Date: Wed, 15 Jan 2025 15:30:56 -0600 Subject: [PATCH 1/6] Initial documentation for building packages --- docs/how-to/build-packages.rst | 148 +++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) diff --git a/docs/how-to/build-packages.rst b/docs/how-to/build-packages.rst index c1bdb5d9..494eab50 100644 --- a/docs/how-to/build-packages.rst +++ b/docs/how-to/build-packages.rst @@ -1,2 +1,150 @@ Build packages ============== + +In Ubuntu, packages can be built in several ways, depending on the intended +artifacts. We'll cover the following types of builds: + * Source-only + * Binary-only (using installed build dependencies) + * Binary-only (using sbuild for a clean environment) + * Source and binary (using sbuild for a clean environment) + +In Ubuntu, only source uploads are permitted to PPAs or the archive. That +being said, it is best practice to perform a local build and iron out any +potential issues prior to uploading it to any archive. + +Prerequisites +------------- + +.. code-block:: bash + + sudo apt install sbuild debhelper ubuntu-dev-tools piuparts + +All of the following sections assume you have already fetched the packaging +and are in the same directory as :file:`debian/`. + +For :manpage:`sbuild(1)`, follow the instructions on the Debian and Ubuntu +sbuild pages as linked in the Resources section. + +What is debuild? +---------------- + +:manpage:`debuild(1)` (short for :manpage:`dpkg-buildpackage(1)`) is +the tool used to build Debian packages. It is part of the +:manpage:`debhelper(7)` package and written in Perl. + +In Ubuntu, we maintain a delta for the `debhelper` package. Therefore, +packages built on Debian may be slightly different than packages built on +Ubuntu. + +Source-Only Builds +------------------ + +To build a source package *without* including the upstream tarball, run: + +.. code-block:: bash + + debuild -S -d + +To build a source package *with* the upstream tarball, run: + +.. code-block:: bash + + debuild -S -d -sa + +To build a source package without running Lintian, run: + +.. code-block:: bash + + debuild --no-lintian -S -d + +.. note:: + + The `--no-lintian` flag will only work in this case if it is first. + +To build a source package without running :manpage:`dh_clean(1)`, run: + +.. code-block:: bash + + debuild -S -d -nc + +.. note:: + + This tends to fix failures regarding missing build dependencies. + +To build a source package without a cryptographic signature (not recommended), run: + +.. code-block:: bash + + debuild -S -d -us -uc + +Local Binary-Only Builds +------------------------ + +This is really only useful for packages you need to test locally, and/or +packages with minimal build dependencies. You would otherwise use :manpage:`sbuild(1)` +as discussed in a later section. + +To do a binary-only build of a package, run: + +.. code-block:: bash + + debuild -b + +sbuild-based Builds +------------------------ + +This is the standard way of building a package for Ubuntu. All of the Debian +and Ubuntu infrastructure use :manpage:`sbuild(1)`, so it is beneficial to +learn how to use it. For more information on setting up :manpage:`sbuild(1)`, +please refer to the wiki links in the Resources section. + +To do a binary-only build of a package using sbuild, run: + +.. code-block:: bash + + sbuild -c -[-shm] + +.. note:: + + It is possible to use `-d` instead of `-c`, but that causes the produced + files to contain the entire chroot name (-[-shm]) instead + of just . An example chroot name is `noble-amd64-shm`. + +To explicitly run Lintian following the build: + +.. code-block:: bash + + sbuild -c -[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"] + +To build a package without running :manpage:`dh_clean(1)`, run: + +.. code-block:: bash + + sbuild -c -[-shm] --no-clean-source + +To build both a binary *and* a source package with one sbuild run: + +.. code-block:: bash + + sbuild -c -[-shm] -s + +.. note:: + + Launchpad rejects uploads which contains both binaries and sources, + however this is required for uploads to the Debian NEW queue. That being + said, uploads to Debian with binaries `will not migrate to Testing `. + +Here is a complete, working example of running the autopkgtest following the build: + +.. code-block:: bash + + sbuild -c noble-amd64-shm --run-autopkgtest --autopkgtest-virt-server=qemu --autopkgtest-virt-server-opt="/path/to/autopkgtest-noble-amd64.img" --autopkgtest-opt="--apt-pocket=proposed=src:qt6-base" --autopkgtest-opt="-U" --autopkgtest-opt="--ram-size=12000" --autopkgtest-opt="--setup-commands='apt-get -y install aptitude && aptitude -t noble-proposed -y install qt6-base-dev=6.8.1+dfsg-0ubuntu1'" + +(Many other backends are available, including an schroot-based backend.) + +Resources +--------- + + * `Chapter 6. Building the package (Debian New Maintainers' Guide) ` + * `SimpleSbuild (Ubuntu Wiki) ` + * `sbuild (Debian Wiki) ` From 508c474e341ddce17d48558b46a9061dd7ad96e8 Mon Sep 17 00:00:00 2001 From: Simon Quigley Date: Wed, 15 Jan 2025 15:36:31 -0600 Subject: [PATCH 2/6] Fix indentation for bullet-pointed items --- docs/how-to/build-packages.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/how-to/build-packages.rst b/docs/how-to/build-packages.rst index 494eab50..b222bb15 100644 --- a/docs/how-to/build-packages.rst +++ b/docs/how-to/build-packages.rst @@ -3,10 +3,10 @@ Build packages In Ubuntu, packages can be built in several ways, depending on the intended artifacts. We'll cover the following types of builds: - * Source-only - * Binary-only (using installed build dependencies) - * Binary-only (using sbuild for a clean environment) - * Source and binary (using sbuild for a clean environment) +* Source-only +* Binary-only (using installed build dependencies) +* Binary-only (using sbuild for a clean environment) +* Source and binary (using sbuild for a clean environment) In Ubuntu, only source uploads are permitted to PPAs or the archive. That being said, it is best practice to perform a local build and iron out any @@ -145,6 +145,6 @@ Here is a complete, working example of running the autopkgtest following the bui Resources --------- - * `Chapter 6. Building the package (Debian New Maintainers' Guide) ` - * `SimpleSbuild (Ubuntu Wiki) ` - * `sbuild (Debian Wiki) ` +* `Chapter 6. Building the package (Debian New Maintainers' Guide) ` +* `SimpleSbuild (Ubuntu Wiki) ` +* `sbuild (Debian Wiki) ` From 6adbc061dd1abc3ad8f18bd480d9cd7cb0aca4be Mon Sep 17 00:00:00 2001 From: Simon Quigley Date: Wed, 15 Jan 2025 15:40:06 -0600 Subject: [PATCH 3/6] Fix missing _ from links --- docs/how-to/build-packages.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/build-packages.rst b/docs/how-to/build-packages.rst index b222bb15..ad8f994c 100644 --- a/docs/how-to/build-packages.rst +++ b/docs/how-to/build-packages.rst @@ -145,6 +145,6 @@ Here is a complete, working example of running the autopkgtest following the bui Resources --------- -* `Chapter 6. Building the package (Debian New Maintainers' Guide) ` -* `SimpleSbuild (Ubuntu Wiki) ` -* `sbuild (Debian Wiki) ` +* `Chapter 6. Building the package (Debian New Maintainers' Guide) `_ +* `SimpleSbuild (Ubuntu Wiki) `_ +* `sbuild (Debian Wiki) `_ From eaadfc008c59889f73a4b9b64904c9d1d2490a80 Mon Sep 17 00:00:00 2001 From: Simon Quigley Date: Wed, 15 Jan 2025 15:42:54 -0600 Subject: [PATCH 4/6] Add a missing newline --- docs/how-to/build-packages.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to/build-packages.rst b/docs/how-to/build-packages.rst index ad8f994c..09e79864 100644 --- a/docs/how-to/build-packages.rst +++ b/docs/how-to/build-packages.rst @@ -3,6 +3,7 @@ Build packages In Ubuntu, packages can be built in several ways, depending on the intended artifacts. We'll cover the following types of builds: + * Source-only * Binary-only (using installed build dependencies) * Binary-only (using sbuild for a clean environment) From 5f62b1e4f1d5ace608b168248747e0120c185b97 Mon Sep 17 00:00:00 2001 From: Simon Quigley Date: Wed, 15 Jan 2025 16:14:33 -0600 Subject: [PATCH 5/6] Add another missed _ --- docs/how-to/build-packages.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/build-packages.rst b/docs/how-to/build-packages.rst index 09e79864..8725ddca 100644 --- a/docs/how-to/build-packages.rst +++ b/docs/how-to/build-packages.rst @@ -133,7 +133,7 @@ To build both a binary *and* a source package with one sbuild run: Launchpad rejects uploads which contains both binaries and sources, however this is required for uploads to the Debian NEW queue. That being - said, uploads to Debian with binaries `will not migrate to Testing `. + said, uploads to Debian with binaries `will not migrate to Testing `_. Here is a complete, working example of running the autopkgtest following the build: From 8157485057300fd89061d67eee62b389c42cc5aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Mon, 16 Jun 2025 15:58:46 +0200 Subject: [PATCH 6/6] Update 'Build packages' with lang. and formatting fixes --- docs/how-to/build-packages.rst | 157 ++++++++++++++++++--------------- 1 file changed, 84 insertions(+), 73 deletions(-) diff --git a/docs/how-to/build-packages.rst b/docs/how-to/build-packages.rst index 8725ddca..04d232d5 100644 --- a/docs/how-to/build-packages.rst +++ b/docs/how-to/build-packages.rst @@ -2,23 +2,26 @@ Build packages ============== In Ubuntu, packages can be built in several ways, depending on the intended -artifacts. We'll cover the following types of builds: +artifacts. We cover the following types of builds: -* Source-only -* Binary-only (using installed build dependencies) -* Binary-only (using sbuild for a clean environment) -* Source and binary (using sbuild for a clean environment) +* Source and binary (using ``sbuild`` for a clean environment) +* Binary-only (using ``sbuild`` for a clean environment) +* Source-only (using ``debuild``) +* Binary-only (using ``debuild`` and installed build dependencies) -In Ubuntu, only source uploads are permitted to PPAs or the archive. That +(Many other backends are available, including an ``schroot``-based backend.) + +Only source uploads are permitted to PPAs or the archive. That being said, it is best practice to perform a local build and iron out any potential issues prior to uploading it to any archive. + Prerequisites ------------- -.. code-block:: bash +.. code-block:: text - sudo apt install sbuild debhelper ubuntu-dev-tools piuparts + $ sudo apt install sbuild debhelper ubuntu-dev-tools piuparts All of the following sections assume you have already fetched the packaging and are in the same directory as :file:`debian/`. @@ -26,122 +29,130 @@ and are in the same directory as :file:`debian/`. For :manpage:`sbuild(1)`, follow the instructions on the Debian and Ubuntu sbuild pages as linked in the Resources section. -What is debuild? ----------------- -:manpage:`debuild(1)` (short for :manpage:`dpkg-buildpackage(1)`) is -the tool used to build Debian packages. It is part of the -:manpage:`debhelper(7)` package and written in Perl. +``sbuild``-based builds +----------------------- -In Ubuntu, we maintain a delta for the `debhelper` package. Therefore, -packages built on Debian may be slightly different than packages built on -Ubuntu. +This is the standard way of building a package for Ubuntu. All of the Debian +and Ubuntu infrastructure use :manpage:`sbuild(1)`, so it is beneficial to +learn how to use it. For more information on setting up :manpage:`sbuild(1)`, +refer to the links in the Resources section. -Source-Only Builds ------------------- +To do a binary-only build of a package using ``sbuild``, run: -To build a source package *without* including the upstream tarball, run: +.. code-block:: text -.. code-block:: bash + $ sbuild -c -[-shm] - debuild -S -d +.. note:: -To build a source package *with* the upstream tarball, run: + It is possible to use ``-d`` instead of ``-c``, but that causes the produced + files to contain the entire chroot name (``-[-shm]``) instead + of just ````. An example chroot name is ``noble-amd64-shm``. -.. code-block:: bash +To explicitly run Lintian following the build: - debuild -S -d -sa +.. code-block:: text -To build a source package without running Lintian, run: + $ sbuild -c -[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"] + +To build a package without running :manpage:`dh_clean(1)`, run: -.. code-block:: bash +.. code-block:: text - debuild --no-lintian -S -d + $ sbuild -c -[-shm] --no-clean-source + +To build both a binary *and* a source package with one ``sbuild`` run: + +.. code-block:: text + + $ sbuild -c -[-shm] -s .. note:: - The `--no-lintian` flag will only work in this case if it is first. + Launchpad rejects uploads that contains both binaries and sources. + However, this is required for uploads to the Debian NEW queue. That being + said, uploads to Debian with binaries `do not migrate to Testing `_. -To build a source package without running :manpage:`dh_clean(1)`, run: +Here is a complete, working example of running the ``autopkgtest`` following the build: -.. code-block:: bash +.. code-block:: text - debuild -S -d -nc + $ sbuild -c noble-amd64-shm --run-autopkgtest \ + --autopkgtest-virt-server=qemu \ + --autopkgtest-virt-server-opt="/path/to/autopkgtest-noble-amd64.img" \ + --autopkgtest-opt="--apt-pocket=proposed=src:qt6-base" \ + --autopkgtest-opt="-U" --autopkgtest-opt="--ram-size=12000" \ + --autopkgtest-opt="--setup-commands='apt-get -y install aptitude \ + && aptitude -t noble-proposed -y install qt6-base-dev=6.8.1+dfsg-0ubuntu1'" -.. note:: - This tends to fix failures regarding missing build dependencies. +Building with ``debuild`` +------------------------- -To build a source package without a cryptographic signature (not recommended), run: +: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. -.. code-block:: bash +Ubuntu maintain its own version the ``debhelper`` package. Therefore, +packages built on Debian may be slightly different than packages built on +Ubuntu. - debuild -S -d -us -uc -Local Binary-Only Builds ------------------------- +Source-only builds +~~~~~~~~~~~~~~~~~~ -This is really only useful for packages you need to test locally, and/or -packages with minimal build dependencies. You would otherwise use :manpage:`sbuild(1)` -as discussed in a later section. +To build a source package *without* including the upstream tarball, run: -To do a binary-only build of a package, run: +.. code-block:: text -.. code-block:: bash + $ debuild -S -d - debuild -b +To build a source package *with* the upstream tarball, run: -sbuild-based Builds ------------------------- +.. code-block:: text -This is the standard way of building a package for Ubuntu. All of the Debian -and Ubuntu infrastructure use :manpage:`sbuild(1)`, so it is beneficial to -learn how to use it. For more information on setting up :manpage:`sbuild(1)`, -please refer to the wiki links in the Resources section. + $ debuild -S -d -sa -To do a binary-only build of a package using sbuild, run: +To build a source package without running Lintian, run: -.. code-block:: bash +.. code-block:: text - sbuild -c -[-shm] + $ debuild --no-lintian -S -d .. note:: - It is possible to use `-d` instead of `-c`, but that causes the produced - files to contain the entire chroot name (-[-shm]) instead - of just . An example chroot name is `noble-amd64-shm`. + The ``--no-lintian`` flag only works in this case if it is first. -To explicitly run Lintian following the build: +To build a source package without running :manpage:`dh_clean(1)`, run: -.. code-block:: bash +.. code-block:: text - sbuild -c -[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"] + $ debuild -S -d -nc -To build a package without running :manpage:`dh_clean(1)`, run: +.. note:: -.. code-block:: bash + This tends to fix failures regarding missing build dependencies. - sbuild -c -[-shm] --no-clean-source +To build a source package without a cryptographic signature (not recommended), run: -To build both a binary *and* a source package with one sbuild run: +.. code-block:: text -.. code-block:: bash + $ debuild -S -d -us -uc - sbuild -c -[-shm] -s -.. note:: +Local binary-only builds +~~~~~~~~~~~~~~~~~~~~~~~~ - Launchpad rejects uploads which contains both binaries and sources, - however this is required for uploads to the Debian NEW queue. That being - said, uploads to Debian with binaries `will not migrate to Testing `_. +This is really only useful for packages you need to test locally or +packages with minimal build dependencies. Otherwise use :manpage:`sbuild(1)`. -Here is a complete, working example of running the autopkgtest following the build: +To do a binary-only build of a package, run: -.. code-block:: bash +.. code-block:: text - sbuild -c noble-amd64-shm --run-autopkgtest --autopkgtest-virt-server=qemu --autopkgtest-virt-server-opt="/path/to/autopkgtest-noble-amd64.img" --autopkgtest-opt="--apt-pocket=proposed=src:qt6-base" --autopkgtest-opt="-U" --autopkgtest-opt="--ram-size=12000" --autopkgtest-opt="--setup-commands='apt-get -y install aptitude && aptitude -t noble-proposed -y install qt6-base-dev=6.8.1+dfsg-0ubuntu1'" + $ debuild -b -(Many other backends are available, including an schroot-based backend.) Resources ---------