+.. _packaging-debian:
+
Packaging Debian
================
-(Tested on Ubuntu 12.04, 14.04, 16.04, 17.10, 18.04, Debian 8 and 9)
-
-.. note::
-
- If you try to build for a different distro, then it will most likely fail
- because of the missing backport. See :ref:`deb-backports` about adding a new
- backport.
-
-1. Install build dependencies for your platform as outlined in :ref:`building`.
-
-2. Install the following additional packages:
-
- - on Ubuntu 12.04, 14.04, 16.04, 17.10, Debian 8 and 9:
-
- .. code-block:: shell
-
- apt-get install realpath equivs groff fakeroot debhelper devscripts
+(Tested on Ubuntu 14.04, 16.04, 17.10, 18.04, Debian jessie, stretch and
+buster.)
- - on Ubuntu 18.04: (realpath is now part of preinstalled by coreutils)
+1. Install the Debian packaging tools:
.. code-block:: shell
- apt-get install equivs groff fakeroot debhelper devscripts
+ sudo apt install fakeroot debhelper devscripts
-3. Checkout FRR under a **unprivileged** user account:
+2. Checkout FRR under an **unprivileged** user account:
.. code-block:: shell
git checkout <branch>
-4. Run ``bootstrap.sh`` and make a dist tarball:
+3. Install build dependencies using the `mk-build-deps` tool from the
+ `devscripts` package:
.. code-block:: shell
- ./bootstrap.sh
- ./configure --with-pkg-extra-version=-MyDebPkgVersion
- make dist
-
- .. note::
-
- Configure parameters are not important for the Debian Package building -
- except the `with-pkg-extra-version` if you want to give the Debian
- package a specific name to mark your own unoffical build.
-
-5. Edit :file:`debianpkg/rules` and set the configuration as needed.
-
- Look for section ``dh_auto_configure`` to modify the configure options as
- needed. Options might be different between the top-level ``rules``` and
- :file:`backports/XXXX/debian/rules`. Please adjust as needed on all files.
+ sudo mk-build-deps --install debian/control
-6. Create backports debian sources
+ Alternatively, you can manually install build dependencies for your
+ platform as outlined in :ref:`building`.
- Rename the :file:`debianpkg` directory to :file:`debian` and create the
- backports (Debian requires to not ship a :file:`debian` directory inside the
- source directory to avoid build conflicts with the reserved ``debian``
- subdirectory name during the build):
+4. Run ``tools/tarsource.sh -V``:
.. code-block:: shell
- mv debianpkg debian
- make -f debian/rules backports
-
- This will create a :file:`frr_*.orig.tar.gz` with the source (same as the
- dist tarball), as well as multiple :file:`frr_*.debian.tar.xz` and
- :file:`frr_*.dsc` corresponding to each distribution for which a backport is
- available.
+ ./tools/tarsource.sh -V
-7. Create a new directory to build the package and populate with package
- source.
+ This script sets up the ``debian/changelog-auto`` file with proper version
+ information.
- .. code-block:: shell
-
- mkdir frrpkg
- cd frrpkg
- tar xf ~/frr/frr_*.orig.tar.gz
- cd frr*
- . /etc/os-release
- tar xf ~/frr/frr_*${ID}${VERSION_ID}*.debian.tar.xz
+5. (optional) Append a distribution identifier if needed (see below under
+ :ref:`multi-dist`.)
-8. Build Debian package dependencies and install them as needed.
+6. Build Debian Package:
.. code-block:: shell
- sudo mk-build-deps --install debian/control
+ dpkg-buildpackage $options
-9. Build Debian Package
+ Where `$options` may contain any or all of the following items:
- Building with standard options:
+ * build profiles specified with ``-P``, e.g.
+ ``-Ppkg.frr.nortrlib,pkg.frr.nosystemd``.
+ Multiple values are separated by commas and there must not be a space
+ after the ``-P``.
- .. code-block:: shell
+ The following build profiles are currently available:
- debuild -b -uc -us
+ +----------------+-------------------+-----------------------------------------+
+ | Profile | Negation | Effect |
+ +================+===================+=========================================+
+ | pkg.frr.rtrlib | pkg.frr.nortrlib | builds frr-rpki-rtrlib package (or not) |
+ +----------------+-------------------+-----------------------------------------+
+ | n/a | pkg.frr.nosystemd | removes libsystemd dependency and |
+ | | | disables unit file installation |
+ +----------------+-------------------+-----------------------------------------+
- Or change some options (see `rules` file for available options):
+ .. note::
- .. code-block:: shell
+ The ``pkg.frr.nosystemd`` option is only intended to support Ubuntu
+ 14.04 (and should be enabled when building for that.)
- debuild --set-envvar=WANT_BGP_VNC=1 --set-envvar=WANT_CUMULUS_MODE=1 -b -uc -us
+ * the ``-uc -us`` options to disable signing the packages with your GPG key
- To build with RPKI:
+ (git builds of the `master` or `stable/X.X` branches won't be signed by
+ default since their target release is set to ``UNRELEASED``.)
- - Download the librtr packages from
- https://ci1.netdef.org/browse/RPKI-RTRLIB/latestSuccessful/artifact
+7. Done!
- - install librtr-dev on the build server
+ If all worked correctly, then you should end up with the Debian packages in
+ the parent directory of where `debuild` ran. If distributed, please make sure
+ you distribute it together with the sources (``frr_*.orig.tar.xz``,
+ ``frr_*.debian.tar.xz`` and ``frr_*.dsc``)
- Then build with:
+.. note::
- .. code-block:: shell
+ A package created from `master` or `stable/X.X` is slightly different from
+ a package created from the `debian` branch. The changelog for the former
+ is autogenerated and sets the Debian revision to ``-0``, which causes an
+ intentional lintian warning. The `debian` branch on the other hand has
+ a manually maintained changelog that contains proper Debian release
+ versioning.
- debuild --set-envvar=WANT_RPKI=1 -b -uc -us
+ Furthermore, official Debian packages are built in ``3.0 (quilt)`` format
+ with an "orig" tarball and a "debian" tarball. These tarballs are created
+ by the ``tarsource.sh`` tool on any branch. The git repository however
+ contains a ``3.0 (git)`` source format specifier to easily allow direct
+ git builds.
- RPKI packages have an additonal dependency of ``librtr0`` which can be found
- at the same URL.
-10. Done!
+.. _multi-dist:
-If all worked correctly, then you should end up with the Debian packages under
-:file:`frrpkg`. If distributed, please make sure you distribute it together
-with the sources (``frr_*.orig.tar.gz``, ``frr_*.debian.tar.xz`` and
-``frr_*.dsc``)
+Multi-Distribution builds
+=========================
-The build procedure can also be executed automatically using the ``tools/build-debian-package.sh``
-script. For example:
+You can optionally append a distribution identifier in case you want to
+make multiple versions of the package available in the same repository.
+Do the following after creating the changelog with `tarsource.sh`:
.. code-block:: shell
- EXTRA_VERSION="-myversion" WANT_SNMP=1 WANT_CUMULUS_MODE=1 tools/build-debian-package.sh
-
-.. _deb-backports:
+ dch -l '~deb8u' 'build for Debian 8 (jessie)'
+ dch -l '~deb9u' 'build for Debian 9 (stretch)'
+ dch -l '~ubuntu14.04.' 'build for Ubuntu 14.04 (trusty)'
+ dch -l '~ubuntu16.04.' 'build for Ubuntu 16.04 (xenial)'
+ dch -l '~ubuntu18.04.' 'build for Ubuntu 18.04 (bionic)'
+
+Between building packages for specific distributions, the only difference
+in the package itself lies in the automatically generated shared library
+dependencies, e.g. libjson-c2 or libjson-c3. This means that the
+architecture independent packages should **not** have a suffix appended.
+Also, the current Debian testing/unstable releases should not have any suffix
+appended.
+
+For example, at the end of 2018 (i.e. ``buster``/Debian 10 is the current
+"testing" release), the following is a complete list of `.deb` files for
+Debian 8, 9 and 10 packages for FRR 6.0.1-1 with RPKI support::
+
+ frr_6.0.1-1_amd64.deb
+ frr_6.0.1-1~deb8u1_amd64.deb
+ frr_6.0.1-1~deb9u1_amd64.deb
+ frr-dbg_6.0.1-1_amd64.deb
+ frr-dbg_6.0.1-1~deb8u1_amd64.deb
+ frr-dbg_6.0.1-1~deb9u1_amd64.deb
+ frr-rpki-rtrlib_6.0.1-1_amd64.deb
+ frr-rpki-rtrlib_6.0.1-1~deb8u1_amd64.deb
+ frr-rpki-rtrlib_6.0.1-1~deb9u1_amd64.deb
+ frr-doc_6.0.1-1_all.deb
+ frr-pythontools_6.0.1-1_all.deb
+
+Note that there are no extra versions of the `frr-doc` and `frr-pythontools`
+packages (because they are for architecture ``all``, not ``amd64``), and the
+version for Debian 10 does **not** have a ``~deb10u1`` suffix.
+
+.. warning::
+
+ Do not use the ``-`` character in the version suffix. The last ``-`` in
+ the version number is the separator between upstream version and Debian
+ version. ``6.0.1-1~foobar-2`` means upstream version ``6.0.1-1~foobar``,
+ Debian version ``2``. This is not what you want.
+
+ The only allowed characters in the Debian version are ``0-9 A-Z a-z + . ~``
-Debian Backports
-----------------
-
-The :file:`debianpkg/backports` directory contains the Debian directories for
-backports to other Debian platforms. These are built via the ``3.0 (custom)``
-source format, which allows one to build a source package directly out of
-tarballs (e.g. an orig.tar.gz tarball and a debian.tar.gz file), at which point
-the format can be changed to a real format (e.g. ``3.0 (quilt)``).
-
-Source packages are assembled via targets of the same name as the system to
-which the backport is done (e.g. ``precise``), included in :file:`debian/rules`.
-
-To create a new Debian backport:
-
-- Add its name to ``KNOWN_BACKPORTS``, defined in :file:`debian/rules`.
-- Create a directory of the same name in :file:`debian/backports`.
-- Add the files ``exclude``, ``versionext``, and ``debian/source/format`` under
- this directory.
-
-For the last point, these files should contain the following:
-
-``exclude``
- Contains whitespace-separated paths (relative to the root of the source dir)
- that should be excluded from the source package (e.g.
- :file:`debian/patches`).
-
-``versionext``
- Contains the suffix added to the version number for this backport's build.
- Distributions often have guidelines for what this should be. If left empty,
- no new :file:`debian/changelog` entry is created.
+.. note::
-``debian/source/format``
- Contains the source format of the resulting source package. As of of the
- writing of this document the only supported format is ``3.0 (quilt)``.
+ The separating character for the suffix **must** be the tilde (``~``)
+ because the tilde is ordered in version-comparison before the empty
+ string. That means the order of the above packages is the following:
-- Add appropriate files under the :file:`debian/` subdirectory. These will be
- included in the source package, overriding any top-level :file:`debian/`
- files with equivalent paths.
+ ``6.0.1-1`` newer than ``6.0.1-1~deb9u1`` newer than ``6.0.1-1~deb8u1``
+ If you use another character (e.g. ``+``), the untagged version will be
+ regarded as the "oldest"!
projects / mirror_frr.git / blobdiff