Package model ============= Because :term:`Ubuntu` is based on the community-driven :term:`Debian` project, Ubuntu uses the Debian packaging model/format. This consists of :ref:`source packages ` and :ref:`binary packages `. .. _SourcePackages: Source packages --------------- A source package contains the :term:`source ` material used to build one or more binary packages. A source package is composed of: - a Debian Source Control (:file:`.dsc`) file, - one or more compressed tar files, and - optionally additional files depending on the type and format of the source package. The **Source Control** file contains metadata about the source package, for instance, a list of additional files, name and version, list of the binary packages it produces, dependencies, a :term:`digital signature ` and many more fields. .. note:: The :doc:`basic overview of the debian/ directory ` article showcases the layout of an unpacked source package. Source package formats ~~~~~~~~~~~~~~~~~~~~~~ There are multiple formats for how the source is packaged. The format of a source package is declared in the :file:`debian/source/format` file. This file should always exist. If this file can not be found, the :ref:`format 1.0 ` is assumed for backwards compatibility, but :manpage:`lintian(1)` will warn you about it when you try to build a source package. .. tip:: We strongly recommend to use the :ref:`3.0 (quilt) ` format for new packages. You should only pick a different format if you **really** know what you are doing. .. _NativeSourcePackages: Native source packages ^^^^^^^^^^^^^^^^^^^^^^ In most cases, a software project is packaged by external contributors called the :term:`maintainers ` of the package. Because the packaging is often done by a 3rd-party (from the perspective of the software project), the software to be packaged is often not designed to be packaged. In these cases the source package has to do modifications to solve specific problems for its target :term:`distribution `. The source package can, in these cases, be considered as its own software project, like a :term:`fork `. Consequently, the :term:`Upstream` releases and source package releases do not always align. Native packages almost always originate from software projects designed with Debian packaging in mind and have no independent existence outside its target distribution. Consequently native packages do not differentiate between Upstream releases and source package releases. Therefore, the version identifier of a native package does not have an Debian-specific component. For example: - The `debhelper package`_ (provides tools for building Debian packages) is a native package from Debian. Because it is designed with packaging in mind, the packaging specific files are part of the original :term:`source code `. The debhelper developers are also maintainers of the Debian package. The Debian debhelper package gets merged into the Ubuntu debhelper package and has therefore a ``ubuntu`` suffix in the version identifier. - In contrast, the `Ubuntu bash package`_ (the default :term:`shell ` on Ubuntu) is **NOT** a native package. The `bash Software`_ originates from the :term:`GNU project `. The bash releases of the GNU project project will get packaged by Debian maintainers and the `Debian bash package`_ is merged into the Ubuntu bash package by Ubuntu maintainers. The Debian and Ubuntu packages both are effectively their own separate software projects maintained by other people than the developers of the software that gets packaged. This is the process how most software is packaged on Ubuntu. .. warning:: Although native packages sound like the solution to use for your software project if you want to distribute your software to Ubuntu/Debian, we **strongly** recommend against using native package formats for new packages. Native packages are known to cause long-term maintenance problems. .. _SourcePackageFormat_3.0quilt: Format: ``3.0 (quilt)`` ^^^^^^^^^^^^^^^^^^^^^^^ A new-generation source package format that records modifications in a :manpage:`quilt(1)` :term:`Patch` series within the :file:`debian/patches` folder. The patches are organised as a :term:`stack `, and you can apply, unapply, and update them easily by traversing the stack (push/pop). These changes are automatically applied during the extraction of the source package. A source package in this format contains at least an original tarball (``.orig.tar.ext`` where ``ext`` can be ``gz``, ``bz2``, ``lzma`` or ``xz``) and a debian tarball (``.debian.tar.ext``). It can also contain additional original tarballs (``.orig-component.tar.ext``), where ``component`` can only contain alphanumeric (``a-z``, ``A-Z``, ``0-9``) characters and hyphens (``-``). Optionally, each original tarball can be accompanied by a :term:`detached signature ` from the upstream project (``.orig.tar.ext.asc`` and ``.orig-component.tar.ext.asc``). For example, take a look at the ``hello`` package: .. code:: bash pull-lp-source --download-only 'hello' '2.10-3' .. note:: You need to install ``ubuntu-dev-tools`` to run the :command:`pull-lp-source`: .. code:: bash sudo apt install ubuntu-dev-tools When you now run :manpage:`ls(1)`: .. code:: bash ls -1 debhelper_* you should see the following files: - :file:`hello_2.10-3.dsc`: The **Debian Source Control** file of the source package. - :file:`hello_2.10.orig.tar.gz`: The tarball containing the original source code of the upstream project. - :file:`hello_2.10.orig.tar.gz.asc`: The detached upstream signature of :file:`hello_2.10.orig.tar.gz`. - :file:`hello_2.10-3.debian.tar.xz`: The tarball containing the content of the Debian directory. .. _SourcePackageFormat_3.0native: Format: ``3.0 (native)`` ^^^^^^^^^^^^^^^^^^^^^^^^ A new-generation source package format extends the native package format defined in the :ref:`format 1.0 `. A source package in this format is a tarball (``.tar.ext`` where ``ext`` can be ``gz``, ``bz2``, ``lzma`` or ``xz``). For example, let's take a look at the ``debhelper`` package: .. code:: bash pull-lp-source --download-only 'debhelper' '13.11.6ubuntu1' When you now run :manpage:`ls(1)`: .. code:: bash ls -1 debhelper_* you should see the following files: - ``debhelper_13.11.6ubuntu1.dsc``: The **Debian Source Control** file of the source package. - ``debhelper_13.11.6ubuntu1.tar.xz``: The tarball containing the source code of the project. Other examples of native source packages are: - `ubuntu-dev-tools `_ - `ubuntu-release-upgrader `_ - `dh-cargo `_ - `ubiquity `_ - `subiquity `_ .. _SourcePackageFormat_1.0: Format: ``1.0`` ^^^^^^^^^^^^^^^ The original source package format. Nowadays, this format is rarely used. A native source package in this format consists of a single ``.tar.gz`` file containing the source. A non-native source package in this format consists of a ``.orig.tar.gz`` file (containing the Upstream source) associated with a ``.diff.gz`` file (the patch containing Debian packaging modifications). Optionally, the original tarball can be accompanied by a detached Upstream signature ``.orig.tar.gz.asc``. .. note:: This format does not specify a patch system, which makes it harder for :term:`maintainers ` to track modifications. There were multiple approaches to how packages tracked patches. Therefore, the source packages of this format often contained a :file:`debian/README.source` file explaining how to use the patch system. ``3.0`` formats improvements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some of the improvements that apply to most ``3.0`` formats are: - Support for additional compression formats: ``bzip2``, ``lzma`` and ``xz``. - Support for multiple Upstream tarballs. - Supports inclusion of binary files. - Debian-specific changes are no longer stored in a single ``.diff.gz``. - The Upstream tarball does not need to be repacked to strip the Debian directory. Other formats ^^^^^^^^^^^^^ The following formats are rarely used, experimental and/or historical. You should only choose these if you know what you are doing. - ``3.0 (custom)``: Doesn't represent an actual source package format but can be used to create source packages with arbitrary files. - ``3.0 (git)``: An experimental format to package from a :term:`git` repository. - ``3.0 (bzr)``: An experimental format to package from a :term:`Bazaar` repository. - ``2.0``: The first specification of a new-generation source package format. It was never widely adopted and eventually replaced by :ref:`3.0 (quilt) `. ``.changes`` file ~~~~~~~~~~~~~~~~~ Although technically not part of a source package -- every time a source package is built, a :file:`.changes` file will be created alongside it. The :file:`.changes` file contains metadata from the Source Control file and other information (e.g. the latest changelog entry) about the source package. :term:`Archive` tools and :term:`Archive Administrators ` use this data to process changes to source packages and determine the appropriate action to upload the source package to the :term:`Ubuntu Archive`. .. _BinaryPackages: Binary packages --------------- A **binary package** is a standardised format that the :term:`Package Manager` (:manpage:`dpkg(1)` or :manpage:`apt(8)`) can understand to install and uninstall software on a target machine. This simplifies distributing software to a target machine and managing the software on that machine. A Debian binary package uses the :file:`.deb` file extension and contains a set of files that will be installed on the host system and a set of files that control how the files will be installed or uninstalled. Resources --------- - `Debian policy manual v4.6.2.0 -- Chapter 3. Binary packages `_ - `Debian policy manual v4.6.2.0 -- Chapter 4. Source packages `_ - The manual page :manpage:`dpkg-source(1)` - `Debian wiki -- 3.0 source package format `_ .. _debhelper package: https://launchpad.net/ubuntu/+source/debhelper .. _bash Software: https://www.gnu.org/software/bash/ .. _Debian bash package: https://tracker.debian.org/pkg/bash .. _Ubuntu bash package: https://launchpad.net/ubuntu/+source/bash