doc/developer/packaging-debian.rst

   1 .. _packaging-debian:
   2
   3 Packaging Debian
   4 ================
   5
   6 (Tested on Ubuntu 14.04, 16.04, 17.10, 18.04, Debian jessie, stretch and
   7 buster.)
   8
   9 1. Install the Debian packaging tools:
  10
  11    .. code-block:: shell
  12
  13       sudo apt install fakeroot debhelper devscripts
  14
  15 2. Checkout FRR under an **unprivileged** user account:
  16
  17    .. code-block:: shell
  18
  19       git clone https://github.com/frrouting/frr.git frr
  20       cd frr
  21
  22    If you wish to build a package for a branch other than master:
  23
  24    .. code-block:: shell
  25
  26       git checkout <branch>
  27
  28 3. Install build dependencies using the  `mk-build-deps` tool from the
  29    `devscripts` package:
  30
  31    .. code-block:: shell
  32
  33       sudo mk-build-deps --install debian/control
  34
  35    Alternatively, you can manually install build dependencies for your
  36    platform as outlined in :ref:`building`.
  37
  38 4. Run ``tools/tarsource.sh -V``:
  39
  40    .. code-block:: shell
  41
  42       ./tools/tarsource.sh -V
  43
  44    This script sets up the ``debian/changelog-auto`` file with proper version
  45    information.
  46
  47 5. (optional) Append a distribution identifier if needed (see below under
  48    :ref:`multi-dist`.)
  49
  50 6. Build Debian Package:
  51
  52    .. code-block:: shell
  53
  54       dpkg-buildpackage $options
  55
  56    Where `$options` may contain any or all of the following items:
  57
  58    * build profiles specified with ``-P``, e.g.
  59      ``-Ppkg.frr.nortrlib,pkg.frr.nosystemd``.
  60      Multiple values are separated by commas and there must not be a space
  61      after the ``-P``.
  62
  63      The following build profiles are currently available:
  64
  65      +----------------+-------------------+-----------------------------------------+
  66      | Profile        | Negation          | Effect                                  |
  67      +================+===================+=========================================+
  68      | pkg.frr.rtrlib | pkg.frr.nortrlib  | builds frr-rpki-rtrlib package (or not) |
  69      +----------------+-------------------+-----------------------------------------+
  70      | n/a            | pkg.frr.nosystemd | removes libsystemd dependency and       |
  71      |                |                   | disables unit file installation         |
  72      +----------------+-------------------+-----------------------------------------+
  73
  74      .. note::
  75
  76         The ``pkg.frr.nosystemd`` option is only intended to support Ubuntu
  77         14.04 (and should be enabled when building for that.)
  78
  79    * the ``-uc -us`` options to disable signing the packages with your GPG key
  80
  81      (git builds of the `master` or `stable/X.X` branches won't be signed by
  82      default since their target release is set to ``UNRELEASED``.)
  83
  84 7. Done!
  85
  86    If all worked correctly, then you should end up with the Debian packages in
  87    the parent directory of where `debuild` ran.  If distributed, please make sure
  88    you distribute it together with the sources (``frr_*.orig.tar.xz``,
  89    ``frr_*.debian.tar.xz`` and ``frr_*.dsc``)
  90
  91 .. note::
  92
  93    A package created from `master` or `stable/X.X` is slightly different from
  94    a package created from the `debian` branch.  The changelog for the former
  95    is autogenerated and sets the Debian revision to ``-0``, which causes an
  96    intentional lintian warning.  The `debian` branch on the other hand has
  97    a manually maintained changelog that contains proper Debian release
  98    versioning.
  99
 100    Furthermore, official Debian packages are built in ``3.0 (quilt)`` format
 101    with an "orig" tarball and a "debian" tarball.  These tarballs are created
 102    by the ``tarsource.sh`` tool on any branch.  The git repository however
 103    contains a ``3.0 (git)`` source format specifier to easily allow direct
 104    git builds.
 105
 106
 107 .. _multi-dist:
 108
 109 Multi-Distribution builds
 110 =========================
 111
 112 You can optionally append a distribution identifier in case you want to
 113 make multiple versions of the package available in the same repository.
 114 Do the following after creating the changelog with `tarsource.sh`:
 115
 116 .. code-block:: shell
 117
 118    dch -l '~deb8u' 'build for Debian 8 (jessie)'
 119    dch -l '~deb9u' 'build for Debian 9 (stretch)'
 120    dch -l '~ubuntu14.04.' 'build for Ubuntu 14.04 (trusty)'
 121    dch -l '~ubuntu16.04.' 'build for Ubuntu 16.04 (xenial)'
 122    dch -l '~ubuntu18.04.' 'build for Ubuntu 18.04 (bionic)'
 123
 124 Between building packages for specific distributions, the only difference
 125 in the package itself lies in the automatically generated shared library
 126 dependencies, e.g. libjson-c2 or libjson-c3.  This means that the
 127 architecture independent packages should **not** have a suffix appended.
 128 Also, the current Debian testing/unstable releases should not have any suffix
 129 appended.
 130
 131 For example, at the end of 2018 (i.e. ``buster``/Debian 10 is the current
 132 "testing" release), the following is a complete list of `.deb` files for
 133 Debian 8, 9 and 10 packages for FRR 6.0.1-1 with RPKI support::
 134
 135    frr_6.0.1-1_amd64.deb
 136    frr_6.0.1-1~deb8u1_amd64.deb
 137    frr_6.0.1-1~deb9u1_amd64.deb
 138    frr-dbg_6.0.1-1_amd64.deb
 139    frr-dbg_6.0.1-1~deb8u1_amd64.deb
 140    frr-dbg_6.0.1-1~deb9u1_amd64.deb
 141    frr-rpki-rtrlib_6.0.1-1_amd64.deb
 142    frr-rpki-rtrlib_6.0.1-1~deb8u1_amd64.deb
 143    frr-rpki-rtrlib_6.0.1-1~deb9u1_amd64.deb
 144    frr-doc_6.0.1-1_all.deb
 145    frr-pythontools_6.0.1-1_all.deb
 146
 147 Note that there are no extra versions of the `frr-doc` and `frr-pythontools`
 148 packages (because they are for architecture ``all``, not ``amd64``), and the
 149 version for Debian 10 does **not** have a ``~deb10u1`` suffix.
 150
 151 .. warning::
 152
 153    Do not use the ``-`` character in the version suffix.  The last ``-`` in
 154    the version number is the separator between upstream version and Debian
 155    version.  ``6.0.1-1~foobar-2`` means upstream version ``6.0.1-1~foobar``,
 156    Debian version ``2``.  This is not what you want.
 157
 158    The only allowed characters in the Debian version are ``0-9 A-Z a-z + . ~``
 159
 160 .. note::
 161
 162    The separating character for the suffix **must** be the tilde (``~``)
 163    because the tilde is ordered in version-comparison before the empty
 164    string.  That means the order of the above packages is the following:
 165
 166    ``6.0.1-1`` newer than ``6.0.1-1~deb9u1`` newer than ``6.0.1-1~deb8u1``
 167
 168    If you use another character (e.g. ``+``), the untagged version will be
 169    regarded as the "oldest"!