Caution

The Packaging and Development guide is currently undergoing a major overhaul to bring it up to date. The current state you are seeing now is a preview of this effort.

The current version is unstable (changing URLs can occur at any time) and most content is not in properly reviewed yet. Proceed with caution and be aware of technical inaccuracies.

If you are an experienced packager and would like to contribute, we would love for you to be involved! See our contribution page for details of how to join in.

Package model

Because Ubuntu is based on the community-driven Debian project, Ubuntu uses the Debian packaging model/format.

This consists of source packages and binary packages.

Source packages

A source package contains the source material used to build one or more binary packages.

A source package is composed of:

  • a Debian Source Control (.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 digital signature and many more fields.

Note

The 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 debian/source/format file. This file should always exist. If this file can not be found, the format 1.0 is assumed for backwards compatibility, but lintian(1) will warn you about it when you try to build a source package.

Tip

We strongly recommend to use the 3.0 (quilt) format for new packages.

You should only pick a different format if you really know what you are doing.

Native source packages

In most cases, a software project is packaged by external contributors called the 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 distribution. The source package can, in these cases, be considered as its own software project, like a fork. Consequently, the 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 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 shell on Ubuntu) is NOT a native package. The bash Software originates from the 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.

Format: 3.0 (quilt)

A new-generation source package format that records modifications in a quilt(1) Patch series within the debian/patches folder. The patches are organised as a 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 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:

pull-lp-source --download-only 'hello' '2.10-3'

Note

You need to install ubuntu-dev-tools to run the pull-lp-source:

sudo apt install ubuntu-dev-tools

When you now run ls(1):

ls -1 debhelper_*

you should see the following files:

  • hello_2.10-3.dsc: The Debian Source Control file of the source package.

  • hello_2.10.orig.tar.gz: The tarball containing the original source code of the upstream project.

  • hello_2.10.orig.tar.gz.asc: The detached upstream signature of hello_2.10.orig.tar.gz.

  • hello_2.10-3.debian.tar.xz: The tarball containing the content of the Debian directory.

Format: 3.0 (native)

A new-generation source package format extends the native package format defined in the 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:

pull-lp-source --download-only 'debhelper' '13.11.6ubuntu1'

When you now run ls(1):

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:

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 maintainers to track modifications. There were multiple approaches to how packages tracked patches. Therefore, the source packages of this format often contained a 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 git repository.

  • 3.0 (bzr): An experimental format to package from a Bazaar repository.

  • 2.0: The first specification of a new-generation source package format. It was never widely adopted and eventually replaced by 3.0 (quilt).

.changes file

Although technically not part of a source package – every time a source package is built, a .changes file will be created alongside it. The .changes file contains metadata from the Source Control file and other information (e.g. the latest changelog entry) about the source package. Archive tools and Archive Administrators use this data to process changes to source packages and determine the appropriate action to upload the source package to the Ubuntu Archive.

Binary packages

A binary package is a standardised format that the Package Manager (dpkg(1) or 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 .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