From 9993fd8bac2452860aa26265311350e49cfad72b Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 9 May 2018 15:12:07 -0400 Subject: [PATCH] doc: move Debian packaging docs to dev docs Updated the doc to cross-reference build documentation as well and reformatted to RST. Removed stub section on how to configure daemons and whatnot, as that's the domain of the user docs. Signed-off-by: Quentin Young --- debianpkg/README.deb_build.md | 127 --------------------- doc/developer/building.rst | 2 + doc/developer/index.rst | 1 + doc/developer/packaging-debian.rst | 173 +++++++++++++++++++++++++++++ doc/developer/packaging.rst | 8 ++ 5 files changed, 184 insertions(+), 127 deletions(-) delete mode 100644 debianpkg/README.deb_build.md create mode 100644 doc/developer/packaging-debian.rst create mode 100644 doc/developer/packaging.rst diff --git a/debianpkg/README.deb_build.md b/debianpkg/README.deb_build.md deleted file mode 100644 index c90ca13394..0000000000 --- a/debianpkg/README.deb_build.md +++ /dev/null @@ -1,127 +0,0 @@ -Building your own FRRouting Debian Package -========================================== -(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 debianpkg/backports/README about -adding a new backport. - -1. Follow the package installation as outlined in doc/Building_on_XXXX.md - (XXXX refers your OS Distribution) to install the required build packages - -2. Install the following additional packages: - - on Ubuntu 12.04, 14.04, 16.04, 17.10, Debian 8 and 9: - - apt-get install realpath equivs groff fakeroot debhelper devscripts - - on Ubuntu 18.04: (realpath is now part of preinstalled by coreutils) - - apt-get install equivs groff fakeroot debhelper devscripts - -3. Checkout FRR under a **unpriviledged** user account - - git clone https://github.com/frrouting/frr.git frr - cd frr - # git checkout - if different branch than master - -4. Run Bootstrap and make distribution tar.gz - - ./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 `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 main `rules` and - `backports/XXXX/debian/rules`. Please adjust as needed on all files - -6. Create backports debian sources - - Move the `debianpkg` to `debian` and create the backports - (Debian requires to not ship a `debian` directory inside the source - directory to avoid build conflicts with the reserved `debian` subdirectory - name during the build) - - mv debianpkg debian - make -f debian/rules backports - - This will create a `frr_*.orig.tar.gz` with the source (same as dist tar), - and multiple `frr_*.debian.tar.xz` and `frr_*.dsc` for the debian package - source on each backport supported distribution - -7. Create a new directory to build the package and populate with package src - - 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 - -8. Build Debian Package Dependencies and install them as needed - - sudo mk-build-deps --install debian/control - -9. Build Debian Package - - Building with standard options: - - debuild -b -uc -us - - Or change some options: - (see `rules` file for available options) - - debuild --set-envvar=WANT_BGP_VNC=1 --set-envvar=WANT_CUMULUS_MODE=1 -b -uc -us - - To build with RPKI, download the librtr packages from - https://ci1.netdef.org/browse/RPKI-RTRLIB/latestSuccessful/artifact - install librtr-dev on the build server and build the packages as - debuild --set-envvar=WANT_RPKI=1 -b -uc -us - RPKI packages have an additonal dependency of librtr0 which can be - found at the same URL - -DONE. - -If all works correctly, then you should end up with the Debian packages under -`frrpkg`. If distributed, please make sure you distribute it together with -the sources (`frr_*.orig.tar.gz`, `frr_*.debian.tar.xz` and `frr_*.dsc`) - - -Enabling daemons after installation of the package: ---------------------------------------------------- - -1. Edit `/etc/frr/daemons` and enable required routing daemons (Zebra is -probably needed for most deployments, so make sure to enable it.) - -2. Check your firewall / IPtables to make sure the routing protocols are -allowed. - -3. Enable FRR at startup - - - On `init.d` based systems (Ubuntu 12.04) - - sudo update-rc.d frr defaults - - - On `systemd` based systems (Debian 8 and later, Ubuntu 14.04 and later) - - sudo systemctl enable frr - -4. Start/Restart the daemons (or reboot) - - - On `init.d` based systems (Ubuntu 12.04) - - sudo invoke-rc.d frr start - - - on `systemd` based systems (Debian 8 and later, Ubuntu 14.04 and later) - - sudo systemctl start frr - - -Configuration is stored in `/etc/frr/*.conf` files and daemon selection -is stored in `/etc/frr/daemons`. diff --git a/doc/developer/building.rst b/doc/developer/building.rst index 92fd1bb63a..051611a65d 100644 --- a/doc/developer/building.rst +++ b/doc/developer/building.rst @@ -1,3 +1,5 @@ +.. _building: + ************ Building FRR ************ diff --git a/doc/developer/index.rst b/doc/developer/index.rst index 2f4b96bc1f..938db28082 100644 --- a/doc/developer/index.rst +++ b/doc/developer/index.rst @@ -6,6 +6,7 @@ Welcome to FRR's documentation! workflow building + packaging process-architecture library bgpd diff --git a/doc/developer/packaging-debian.rst b/doc/developer/packaging-debian.rst new file mode 100644 index 0000000000..66339b6d1f --- /dev/null +++ b/doc/developer/packaging-debian.rst @@ -0,0 +1,173 @@ +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 + + - on Ubuntu 18.04: (realpath is now part of preinstalled by coreutils) + + .. code-block:: shell + + apt-get install equivs groff fakeroot debhelper devscripts + +3. Checkout FRR under a **unprivileged** user account: + + .. code-block:: shell + + git clone https://github.com/frrouting/frr.git frr + cd frr + + If you wish to build a package for a branch other than master: + + .. code-block:: shell + + git checkout + +4. Run ``bootstrap.sh`` and make a dist tarball: + + .. 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. + +6. Create backports debian sources + + 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): + + .. 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. + +7. Create a new directory to build the package and populate with package + source. + + .. 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 + +8. Build Debian package dependencies and install them as needed. + + .. code-block:: shell + + sudo mk-build-deps --install debian/control + +9. Build Debian Package + + Building with standard options: + + .. code-block:: shell + + debuild -b -uc -us + + Or change some options (see `rules` file for available options): + + .. code-block:: shell + + debuild --set-envvar=WANT_BGP_VNC=1 --set-envvar=WANT_CUMULUS_MODE=1 -b -uc -us + + To build with RPKI: + + - Download the librtr packages from + https://ci1.netdef.org/browse/RPKI-RTRLIB/latestSuccessful/artifact + + - install librtr-dev on the build server + + Then build with: + + .. code-block:: shell + + debuild --set-envvar=WANT_RPKI=1 -b -uc -us + + RPKI packages have an additonal dependency of ``librtr0`` which can be found + at the same URL. + +10. Done! + +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``) + +.. _deb-backports: + +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. + +``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)``. + +- 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. + diff --git a/doc/developer/packaging.rst b/doc/developer/packaging.rst new file mode 100644 index 0000000000..e9bb3a5409 --- /dev/null +++ b/doc/developer/packaging.rst @@ -0,0 +1,8 @@ +********* +Packaging +********* + +.. toctree:: + :maxdepth: 2 + + packaging-debian -- 2.39.5