Initial documentation for building packages

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 <RELEASE>-<ARCH>[-shm]
+
+.. note::
+
+    It is possible to use ``-d`` instead of ``-c``, 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``.
+
+To explicitly run Lintian following the build:
+
+.. code-block:: text
+
+    $ sbuild -c <RELEASE>-<ARCH>[-shm] --run-lintian [--lintian-opts="-EvIiL +pedantic"]
+
+To build a package without running :manpage:`dh_clean(1)`, run:
+
+.. code-block:: text
+
+    $ sbuild -c <RELEASE>-<ARCH>[-shm] --no-clean-source
+
+To build both a binary *and* a source package with one ``sbuild`` run:
+
+.. code-block:: text
+
+    $ sbuild -c <RELEASE>-<ARCH>[-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 <https://lists.debian.org/debian-devel-announce/2019/07/msg00002.html>`_.
+
+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) <https://www.debian.org/doc/manuals/maint-guide/build.html>`_
+* `SimpleSbuild (Ubuntu Wiki) <https://wiki.ubuntu.com/SimpleSbuild>`_
+* `sbuild (Debian Wiki) <https://wiki.debian.org/sbuild>`_