diff --git a/docs/how-to/build-packages.rst b/docs/how-to/build-packages.rst index c1bdb5d9..04d232d5 100644 --- a/docs/how-to/build-packages.rst +++ b/docs/how-to/build-packages.rst @@ -1,2 +1,162 @@ Build packages ============== + +In Ubuntu, packages can be built in several ways, depending on the intended +artifacts. We cover the following types of builds: + +* 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) + +(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:: text + + $ 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. + + +``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)`, +refer to the links in the Resources section. + +To do a binary-only build of a package using ``sbuild``, run: + +.. code-block:: text + + $ 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:: text + + $ sbuild -c -[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"] + +To build a package without running :manpage:`dh_clean(1)`, run: + +.. code-block:: text + + $ 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:: + + 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 `_. + +Here is a complete, working example of running the ``autopkgtest`` following the build: + +.. 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'" + + +Building with ``debuild`` +------------------------- + +: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. + +Ubuntu maintain its own version 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:: text + + $ debuild -S -d + +To build a source package *with* the upstream tarball, run: + +.. code-block:: text + + $ debuild -S -d -sa + +To build a source package without running Lintian, run: + +.. code-block:: text + + $ debuild --no-lintian -S -d + +.. note:: + + The ``--no-lintian`` flag only works in this case if it is first. + +To build a source package without running :manpage:`dh_clean(1)`, run: + +.. code-block:: text + + $ 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:: text + + $ debuild -S -d -us -uc + + +Local binary-only builds +~~~~~~~~~~~~~~~~~~~~~~~~ + +This is really only useful for packages you need to test locally or +packages with minimal build dependencies. Otherwise use :manpage:`sbuild(1)`. + +To do a binary-only build of a package, run: + +.. code-block:: text + + $ debuild -b + + +Resources +--------- + +* `Chapter 6. Building the package (Debian New Maintainers' Guide) `_ +* `SimpleSbuild (Ubuntu Wiki) `_ +* `sbuild (Debian Wiki) `_