doc/developer/packaging-debian.rst

   1 Packaging Debian
   2 ================
   3
   4 (Tested on Ubuntu 12.04, 14.04, 16.04, 17.10, 18.04, Debian 8 and 9)
   5
   6 .. note::
   7
   8    If you try to build for a different distro, then it will most likely fail
   9    because of the missing backport. See :ref:`deb-backports` about adding a new
  10    backport.
  11
  12 1. Install build dependencies for your platform as outlined in :ref:`building`.
  13
  14 2. Install the following additional packages:
  15
  16    - on Ubuntu 12.04, 14.04, 16.04, 17.10, Debian 8 and 9:
  17
  18    .. code-block:: shell
  19
  20       apt-get install realpath equivs groff fakeroot debhelper devscripts
  21
  22    - on Ubuntu 18.04: (realpath is now part of preinstalled by coreutils)
  23
  24    .. code-block:: shell
  25
  26       apt-get install equivs groff fakeroot debhelper devscripts
  27
  28 3. Checkout FRR under a **unprivileged** user account:
  29
  30    .. code-block:: shell
  31
  32       git clone https://github.com/frrouting/frr.git frr
  33       cd frr
  34
  35    If you wish to build a package for a branch other than master:
  36
  37    .. code-block:: shell
  38
  39       git checkout <branch>
  40
  41 4. Run ``bootstrap.sh`` and make a dist tarball:
  42
  43    .. code-block:: shell
  44
  45       ./bootstrap.sh
  46       ./configure --with-pkg-extra-version=-MyDebPkgVersion
  47       make dist
  48
  49    .. note::
  50
  51       Configure parameters are not important for the Debian Package building -
  52       except the `with-pkg-extra-version` if you want to give the Debian
  53       package a specific name to mark your own unoffical build.
  54
  55 5. Edit :file:`debianpkg/rules` and set the configuration as needed.
  56
  57    Look for section ``dh_auto_configure`` to modify the configure options as
  58    needed. Options might be different between the top-level ``rules``` and
  59    :file:`backports/XXXX/debian/rules`. Please adjust as needed on all files.
  60
  61 6. Create backports debian sources
  62
  63    Rename the :file:`debianpkg` directory to :file:`debian` and create the
  64    backports (Debian requires to not ship a :file:`debian` directory inside the
  65    source directory to avoid build conflicts with the reserved ``debian``
  66    subdirectory name during the build):
  67
  68    .. code-block:: shell
  69
  70       mv debianpkg debian
  71       make -f debian/rules backports
  72
  73    This will create a :file:`frr_*.orig.tar.gz` with the source (same as the
  74    dist tarball), as well as multiple :file:`frr_*.debian.tar.xz` and
  75    :file:`frr_*.dsc` corresponding to each distribution for which a backport is
  76    available.
  77
  78 7. Create a new directory to build the package and populate with package
  79    source.
  80
  81    .. code-block:: shell
  82
  83       mkdir frrpkg
  84       cd frrpkg
  85       tar xf ~/frr/frr_*.orig.tar.gz
  86       cd frr*
  87       . /etc/os-release
  88       tar xf ~/frr/frr_*${ID}${VERSION_ID}*.debian.tar.xz
  89
  90 8. Build Debian package dependencies and install them as needed.
  91
  92    .. code-block:: shell
  93
  94       sudo mk-build-deps --install debian/control
  95
  96 9. Build Debian Package
  97
  98    Building with standard options:
  99
 100    .. code-block:: shell
 101
 102       debuild -b -uc -us
 103
 104    Or change some options (see `rules` file for available options):
 105
 106    .. code-block:: shell
 107
 108       debuild --set-envvar=WANT_BGP_VNC=1 --set-envvar=WANT_CUMULUS_MODE=1 -b -uc -us
 109
 110    To build with RPKI:
 111
 112    - Download the librtr packages from
 113      https://ci1.netdef.org/browse/RPKI-RTRLIB/latestSuccessful/artifact
 114
 115    - install librtr-dev on the build server
 116
 117    Then build with:
 118
 119    .. code-block:: shell
 120
 121       debuild --set-envvar=WANT_RPKI=1 -b -uc -us
 122
 123    RPKI packages have an additonal dependency of ``librtr0`` which can be found
 124    at the same URL.
 125
 126 10. Done!
 127
 128 If all worked correctly, then you should end up with the Debian packages under
 129 :file:`frrpkg`. If distributed, please make sure you distribute it together
 130 with the sources (``frr_*.orig.tar.gz``, ``frr_*.debian.tar.xz`` and
 131 ``frr_*.dsc``)
 132
 133 The build procedure can also be executed automatically using the ``tools/build-debian-package.sh``
 134 script. For example:
 135
 136 .. code-block:: shell
 137
 138    EXTRA_VERSION="-myversion" WANT_SNMP=1 WANT_CUMULUS_MODE=1 tools/build-debian-package.sh
 139
 140 .. _deb-backports:
 141
 142 Debian Backports
 143 ----------------
 144
 145 The :file:`debianpkg/backports` directory contains the Debian directories for
 146 backports to other Debian platforms.  These are built via the ``3.0 (custom)``
 147 source format, which allows one to build a source package directly out of
 148 tarballs (e.g. an orig.tar.gz tarball and a debian.tar.gz file), at which point
 149 the format can be changed to a real format (e.g. ``3.0 (quilt)``).
 150
 151 Source packages are assembled via targets of the same name as the system to
 152 which the backport is done (e.g. ``precise``), included in :file:`debian/rules`.
 153
 154 To create a new Debian backport:
 155
 156 - Add its name to ``KNOWN_BACKPORTS``, defined in :file:`debian/rules`.
 157 - Create a directory of the same name in :file:`debian/backports`.
 158 - Add the files ``exclude``, ``versionext``, and ``debian/source/format`` under
 159   this directory.
 160
 161 For the last point, these files should contain the following:
 162
 163 ``exclude``
 164    Contains whitespace-separated paths (relative to the root of the source dir)
 165    that should be excluded from the source package (e.g.
 166    :file:`debian/patches`).
 167
 168 ``versionext``
 169    Contains the suffix added to the version number for this backport's build.
 170    Distributions often have guidelines for what this should be. If left empty,
 171    no new :file:`debian/changelog` entry is created.
 172
 173 ``debian/source/format``
 174    Contains the source format of the resulting source package.  As of of the
 175    writing of this document the only supported format is ``3.0 (quilt)``.
 176
 177 - Add appropriate files under the :file:`debian/` subdirectory.  These will be
 178   included in the source package, overriding any top-level :file:`debian/`
 179   files with equivalent paths.
 180