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 --remove debian/control
  34
  35    Alternatively, you can manually install build dependencies for your
  36    platform as outlined in :ref:`building`.
  37
  38 4. Install `git-buildpackage` package:
  39
  40    .. code-block:: shell
  41
  42       sudo apt-get install git-buildpackage
  43
  44 5. (optional) Append a distribution identifier if needed (see below under
  45    :ref:`multi-dist`.)
  46
  47 6. Build Debian Binary and/or Source Packages:
  48
  49    .. code-block:: shell
  50
  51       gbp buildpackage --git-builder=dpkg-buildpackage --git-debian-branch="$(git rev-parse --abbrev-ref HEAD)" $options
  52
  53    Where `$options` may contain any or all of the following items:
  54
  55    * build profiles specified with ``-P``, e.g.
  56      ``-Ppkg.frr.nortrlib,pkg.frr.rtrlib``.
  57      Multiple values are separated by commas and there must not be a space
  58      after the ``-P``.
  59
  60      The following build profiles are currently available:
  61
  62      +----------------+-------------------+-----------------------------------------+
  63      | Profile        | Negation          | Effect                                  |
  64      +================+===================+=========================================+
  65      | pkg.frr.rtrlib | pkg.frr.nortrlib  | builds frr-rpki-rtrlib package (or not) |
  66      +----------------+-------------------+-----------------------------------------+
  67      | pkg.frr.lua    | pkg.frr.nolua     | builds lua scripting extension          |
  68      +----------------+-------------------+-----------------------------------------+
  69      | pkg.frr.pim6d  | pkg.frr.nopim6d   | builds pim6d (default enabled)          |
  70      +----------------+-------------------+-----------------------------------------+
  71
  72    * the ``-uc -us`` options to disable signing the packages with your GPG key
  73
  74      (git builds of the `master` or `stable/X.X` branches won't be signed by
  75      default since their target release is set to ``UNRELEASED``.)
  76
  77    * the ``--build=type`` accepts following options (see ``dpkg-buildpackage`` manual page):
  78
  79      * ``source`` builds the source package
  80      * ``any`` builds the architecture specific binary packages
  81      * ``all`` build the architecture independent binary packages
  82      * ``binary`` build the architecture specific and independent binary packages (alias for ``any,all``)
  83      * ``full`` builds everything (alias for ``source,any,all``)
  84
  85    Alternatively, you might want to replace ``dpkg-buildpackage`` with
  86    ``debuild`` wrapper that also runs ``lintian`` and ``debsign`` on the final
  87    packages.
  88
  89 7. Done!
  90
  91    If all worked correctly, then you should end up with the Debian packages in
  92    the parent directory of where `debuild` ran.  If distributed, please make sure
  93    you distribute it together with the sources (``frr_*.orig.tar.xz``,
  94    ``frr_*.debian.tar.xz`` and ``frr_*.dsc``)
  95
  96 .. note::
  97
  98    A package created from `master` or `stable/X.X` is slightly different from
  99    a package created from the `debian` branch.  The changelog for the former
 100    is autogenerated and sets the Debian revision to ``-0``, which causes an
 101    intentional lintian warning.  The `debian` branch on the other hand has
 102    a manually maintained changelog that contains proper Debian release
 103    versioning.
 104
 105
 106 .. _multi-dist:
 107
 108 Multi-Distribution builds
 109 =========================
 110
 111 You can optionally append a distribution identifier in case you want to
 112 make multiple versions of the package available in the same repository.
 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"!