doc: stick `libunwind` into build docs

It's strictly optional, but… the backtraces are really much better.
Specifically, `libunwind` is notably more capable in figuring out
function names compared to glibc/libexecinfo `backtrace_symbols()`.

Signed-off-by: David Lamparter <equinox@opensourcerouting.org>

diff --git a/doc/developer/building-frr-for-archlinux.rst b/doc/developer/building-frr-for-archlinux.rst
index af1677e89e4a6d39a95905795b2a8f58ebc029fd..406d22d6180e51b3cf2d019f9697e5b6edf8408b 100644 (file)
--- a/doc/developer/building-frr-for-archlinux.rst
+++ b/doc/developer/building-frr-for-archlinux.rst
@@ -11,7 +11,9 @@ Installing Dependencies
       git autoconf automake libtool make cmake pcre readline texinfo \
       pkg-config pam json-c bison flex python-pytest \
       c-ares python python2-ipaddress python-sphinx \
-      net-snmp perl libcap libelf
+      net-snmp perl libcap libelf libunwind
+
+.. include:: building-libunwind-note.rst
 
 .. include:: building-libyang.rst
 

diff --git a/doc/developer/building-frr-for-centos7.rst b/doc/developer/building-frr-for-centos7.rst
index ce11126f70c642b242edcbe4bdda528d7c364100..c40b5de594dfbaeef83afef5570ece0aef715032 100644 (file)
--- a/doc/developer/building-frr-for-centos7.rst
+++ b/doc/developer/building-frr-for-centos7.rst
@@ -22,7 +22,9 @@ Add packages:
       readline-devel texinfo net-snmp-devel groff pkgconfig \
       json-c-devel pam-devel bison flex pytest c-ares-devel \
       python-devel python-sphinx libcap-devel \
-      elfutils-libelf-devel
+      elfutils-libelf-devel libunwind-devel
+
+.. include:: building-libunwind-note.rst
 
 .. include:: building-libyang.rst
 

diff --git a/doc/developer/building-frr-for-centos8.rst b/doc/developer/building-frr-for-centos8.rst
index 109a7866d9f382415630a762bddc8636188c6dde..659752f6df98d379d9bccfcd0a36f21ddab1c18d 100644 (file)
--- a/doc/developer/building-frr-for-centos8.rst
+++ b/doc/developer/building-frr-for-centos8.rst
@@ -15,7 +15,9 @@ Add packages:
       automake libtool make readline-devel texinfo net-snmp-devel pkgconfig \
       groff pkgconfig json-c-devel pam-devel bison flex python2-pytest \
       c-ares-devel python2-devel libcap-devel \
-      elfutils-libelf-devel
+      elfutils-libelf-devel libunwind-devel
+
+.. include:: building-libunwind-note.rst
 
 .. include:: building-libyang.rst
 

diff --git a/doc/developer/building-frr-for-debian9.rst b/doc/developer/building-frr-for-debian9.rst
index f8d8025f6293446be5db891f6c06388e00451f1a..b2fdef9990415d8312b8661fa14b65ec42129faa 100644 (file)
--- a/doc/developer/building-frr-for-debian9.rst
+++ b/doc/developer/building-frr-for-debian9.rst
@@ -11,7 +11,9 @@ Add packages:
    sudo apt-get install git autoconf automake libtool make \
      libreadline-dev texinfo libjson-c-dev pkg-config bison flex \
      libc-ares-dev python3-dev python3-pytest python3-sphinx build-essential \
-     libsnmp-dev libcap-dev libelf-dev
+     libsnmp-dev libcap-dev libelf-dev libunwind-dev
+
+.. include:: building-libunwind-note.rst
 
 .. include:: building-libyang.rst
 

diff --git a/doc/developer/building-frr-for-fedora.rst b/doc/developer/building-frr-for-fedora.rst
index 6ce76ba158e488fbed8ea7e3a98b53f279368160..dc869ece1057d7101111a618d52d37574c653a4b 100644 (file)
--- a/doc/developer/building-frr-for-fedora.rst
+++ b/doc/developer/building-frr-for-fedora.rst
@@ -15,7 +15,9 @@ Installing Dependencies
      readline-devel texinfo net-snmp-devel groff pkgconfig json-c-devel \
      pam-devel python3-pytest bison flex c-ares-devel python3-devel \
      python3-sphinx perl-core patch libcap-devel \
-     elfutils-libelf-devel
+     elfutils-libelf-devel libunwind-devel
+
+.. include:: building-libunwind-note.rst
 
 .. include:: building-libyang.rst
 

diff --git a/doc/developer/building-frr-for-freebsd10.rst b/doc/developer/building-frr-for-freebsd10.rst
index e85cb8005351cd8c89dfbe34a5af0b34e9642f1b..5e70b81d43d7fc79f9f9386aacd7d5a3793e0a25 100644 (file)
--- a/doc/developer/building-frr-for-freebsd10.rst
+++ b/doc/developer/building-frr-for-freebsd10.rst
@@ -17,7 +17,9 @@ is first package install and asked)
 ::
 
     pkg install git autoconf automake libtool gmake json-c pkgconf \
-        bison flex py36-pytest c-ares python3.6 py36-sphinx
+        bison flex py36-pytest c-ares python3.6 py36-sphinx libunwind
+
+.. include:: building-libunwind-note.rst
 
 Make sure there is no /usr/bin/flex preinstalled (and use the newly
 installed in /usr/local/bin): (FreeBSD frequently provides a older flex

diff --git a/doc/developer/building-frr-for-freebsd11.rst b/doc/developer/building-frr-for-freebsd11.rst
index b97538b763c18e992813ed31d2d0b5682fa956d9..808207b8314869ea41fc889fcf0976113bdc34af 100644 (file)
--- a/doc/developer/building-frr-for-freebsd11.rst
+++ b/doc/developer/building-frr-for-freebsd11.rst
@@ -17,7 +17,9 @@ is first package install and asked)
 .. code-block:: shell
 
    pkg install git autoconf automake libtool gmake json-c pkgconf \
-      bison flex py36-pytest c-ares python3.6 py36-sphinx texinfo
+      bison flex py36-pytest c-ares python3.6 py36-sphinx texinfo libunwind
+
+.. include:: building-libunwind-note.rst
 
 Make sure there is no /usr/bin/flex preinstalled (and use the newly
 installed in /usr/local/bin): (FreeBSD frequently provides a older flex

diff --git a/doc/developer/building-frr-for-opensuse.rst b/doc/developer/building-frr-for-opensuse.rst
index ee6a36a14bab9bd8dea947f00ccd8087f8013227..d9800a1638de1842c4d5acf3f650ba35c280928b 100644 (file)
--- a/doc/developer/building-frr-for-opensuse.rst
+++ b/doc/developer/building-frr-for-opensuse.rst
@@ -14,7 +14,9 @@ Installing Dependencies
      readline-devel texinfo net-snmp-devel groff pkgconfig libjson-c-devel\
      pam-devel python3-pytest bison flex c-ares-devel python3-devel\
      python3-Sphinx perl patch libcap-devel libyang-devel \
-     libelf-devel
+     libelf-devel libunwind-devel
+
+.. include:: building-libunwind-note.rst
 
 Building & Installing FRR
 -------------------------

diff --git a/doc/developer/building-frr-for-ubuntu1804.rst b/doc/developer/building-frr-for-ubuntu1804.rst
index 3e8c6c0d0b244a5d2eab18d32e50a4d6d73a1ae4..fcfd94ec2cabe4d0b6b90c051cff771fc91b3ace 100644 (file)
--- a/doc/developer/building-frr-for-ubuntu1804.rst
+++ b/doc/developer/building-frr-for-ubuntu1804.rst
@@ -15,7 +15,9 @@ Installing Dependencies
       pkg-config libpam0g-dev libjson-c-dev bison flex \
       libc-ares-dev python3-dev python3-sphinx \
       install-info build-essential libsnmp-dev perl libcap-dev \
-      libelf-dev
+      libelf-dev libunwind-dev
+
+.. include:: building-libunwind-note.rst
 
 .. include:: building-libyang.rst
 

diff --git a/doc/developer/building-frr-for-ubuntu2004.rst b/doc/developer/building-frr-for-ubuntu2004.rst
index 28e7ca6518d479261a0a48c34c274ff36182a7fd..fdfc25da9df0e06392122821c3757178f7b08880 100644 (file)
--- a/doc/developer/building-frr-for-ubuntu2004.rst
+++ b/doc/developer/building-frr-for-ubuntu2004.rst
@@ -15,7 +15,9 @@ Installing Dependencies
       pkg-config libpam0g-dev libjson-c-dev bison flex \
       libc-ares-dev python3-dev python3-sphinx \
       install-info build-essential libsnmp-dev perl \
-      libcap-dev python2 libelf-dev
+      libcap-dev python2 libelf-dev libunwind-dev
+
+.. include:: building-libunwind-note.rst
 
 Note that Ubuntu 20 no longer installs python 2.x, so it must be
 installed explicitly. Ensure that your system has a symlink named

diff --git a/doc/developer/building-libunwind-note.rst b/doc/developer/building-libunwind-note.rst
new file mode 100644 (file)
index 0000000..0beb1f8
--- /dev/null
+++ b/doc/developer/building-libunwind-note.rst
@@ -0,0 +1,6 @@
+.. note::
+
+   The ``libunwind`` library is optional but highly recommended, as it improves
+   backtraces printed for crashes and debugging.  However, if it is not
+   available for some reason, it can simply be left out without any loss of
+   functionality.

diff --git a/doc/developer/conf.py b/doc/developer/conf.py
index 61df6e0e604fca1caa63d416db6e7c0d558a0984..79f8233978aedc52e083e97837a221f23c390cff 100644 (file)
--- a/doc/developer/conf.py
+++ b/doc/developer/conf.py
@@ -136,6 +136,7 @@ language = None
 # directories to ignore when looking for source files.
 exclude_patterns = [
     "_build",
+    "building-libunwind-note.rst",
     "building-libyang.rst",
     "topotests-snippets.rst",
     "topotests-markers.rst",

diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am
index d16420c7e72c644b37a5d08a1bc324fa26ccb05e..c8654d6725c82b93eb4714fc926c78ce81ddd852 100644 (file)
--- a/doc/developer/subdir.am
+++ b/doc/developer/subdir.am
@@ -23,6 +23,7 @@ dev_RSTFILES = \
        doc/developer/building-frr-for-ubuntu1604.rst \
        doc/developer/building-frr-for-ubuntu1804.rst \
        doc/developer/building-frr-for-ubuntu2004.rst \
+       doc/developer/building-libunwind-note.rst \
        doc/developer/building-libyang.rst \
        doc/developer/building.rst \
        doc/developer/cli.rst \