doc: update instructions for building libyang

* Upstream libyang now works with FRR; use it
* Install libyang to system library directories to satisfy pkg-config
* Remove warnings about ABI version
* Remove outdated binary package links
* Cleanup formatting

Validated that these instructions work on:
- Fedora 24
- Fedora 28.
- Ubuntu 18.04

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>

diff --git a/doc/developer/building-libyang.rst b/doc/developer/building-libyang.rst
index c45c294b75295db8640da9422235c04e2a093fc7..41fe09e322fef4445a432106dc750c8de0ac3877 100644 (file)
--- a/doc/developer/building-libyang.rst
+++ b/doc/developer/building-libyang.rst
@@ -1,57 +1,55 @@
-The libyang library can be installed from third-party packages available `here
-<https://ci1.netdef.org/browse/LIBYANG-YANGRELEASE/latestSuccessful/artifact>`_.
+FRR depends on the relatively new ``libyang`` library to provide YANG/NETCONF
+support. Unfortunately, most distributions do not yet offer a ``libyang``
+package from their repositories. Therefore we offer two options to install this
+library.
 
-Note: the libyang dev/devel packages need to be installed in addition
-to the libyang core package in order to build FRR successfully.
+**Option 1: Binary Install**
+
+The FRR project builds binary ``libyang`` packages, which we offer for download
+`here <https://ci1.netdef.org/browse/LIBYANG-YANGRELEASE/latestSuccessful/artifact>`_.
 
 .. warning::
-   libyang ABI version 0.16.74 or newer will be required to build FRR in the
-   near future since it significantly eases build and installation
-   considerations.  "0.16-r3" is equal to 0.16.105 and will work, "0.16-r2"
-   is equal to 0.16.52 and will stop working.  The CI artifacts will be
-   updated shortly.
 
-For example, for CentOS 7.x:
+   ``libyang`` version 0.16.74 or newer is required to build FRR.
+
+.. note::
 
-.. code-block:: shell
+   The ``libyang`` development packages need to be installed in addition to the
+   libyang core package in order to build FRR successfully. Make sure to
+   download and install those from the link above alongside the binary
+   packages.
 
-   wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/CentOS-7-x86_64-Packages/libyang-0.16.46-0.x86_64.rpm
-   wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/CentOS-7-x86_64-Packages/libyang-devel-0.16.46-0.x86_64.rpm
-   sudo rpm -i libyang-0.16.46-0.x86_64.rpm libyang-devel-0.16.46-0.x86_64.rpm
+   Depending on your platform, you may also need to install the PCRE
+   development package. Typically this is ``libpcre-dev`` or ``pcre-devel``.
 
-or Ubuntu 18.04:
+.. note::
 
-.. code-block:: shell
+   For Debian-based systems, the official ``libyang`` package requires recent
+   versions of ``swig`` (3.0.12) and ``debhelper`` (11) which are only
+   available in Debian buster (10).  However, ``libyang`` packages built on
+   Debian buster can be installed on both Debian jessie (8) and Debian stretch
+   (9), as well as various Ubuntu systems.  The ``python3-yang`` package will
+   not work, but the other packages (``libyang-dev`` is the one needed for FRR)
+   will.
 
-   wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/Ubuntu-18.04-x86_64-Packages/libyang-dev_0.16.46_amd64.deb
-   wget https://ci1.netdef.org/artifact/LIBYANG-YANGRELEASE/shared/build-1/Ubuntu-18.04-x86_64-Packages/libyang_0.16.46_amd64.deb
-   sudo apt install libpcre3-dev
-   sudo dpkg -i libyang-dev_0.16.46_amd64.deb libyang_0.16.46_amd64.deb
+**Option 2: Source Install**
 
 .. note::
-   For Debian-based systems, the official libyang package requires recent
-   versions of swig (3.0.12) and debhelper (11) which are only available in
-   Debian buster (10).  However, libyang packages built on Debian buster can
-   be installed on both Debian jessie (8) and Debian stretch (9), as well as
-   various Ubuntu systems.  The python3-yang package will not work, but the
-   other packages (libyang-dev is the one needed for FRR) will.
 
-Alternatively, libyang can be built and installed manually by following
-the steps below:
+   Ensure that the `libyang build requirements
+   <https://github.com/CESNET/libyang/blob/master/README.md#build-requirements>`_
+   are met before continuing. Usually this entails installing ``cmake`` and
+   ``libpcre-dev`` or ``pcre-devel``.
 
-.. code-block:: shell
+.. code-block:: console
 
-   git clone https://github.com/opensourcerouting/libyang
+   git clone https://github.com/CESNET/libyang.git
    cd libyang
-   git checkout -b tmp origin/tmp
    mkdir build; cd build
-   cmake -DENABLE_LYD_PRIV=ON ..
+   cmake -DENABLE_LYD_PRIV=ON -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
    make
    sudo make install
 
 When building libyang on CentOS 6, it's also necessary to pass the
 ``-DENABLE_CACHE=OFF`` parameter to cmake.
 
-Note: please check the `libyang build requirements
-<https://github.com/CESNET/libyang/blob/master/README.md#build-requirements>`_
-first.