doc/developer/packaging-debian.rst

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