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>

13 files changed, 38 insertions, 10 deletions

diff --git a/doc/developer/building-frr-for-archlinux.rst b/doc/developer/building-frr-for-archlinux.rst
index af1677e89e..406d22d618 100644
--- 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 ce11126f70..c40b5de594 100644
--- 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 109a7866d9..659752f6df 100644
--- 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 f8d8025f62..b2fdef9990 100644
--- 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 6ce76ba158..dc869ece10 100644
--- 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 e85cb80053..5e70b81d43 100644
--- 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 b97538b763..808207b831 100644
--- 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 ee6a36a14b..d9800a1638 100644
--- 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 3e8c6c0d0b..fcfd94ec2c 100644
--- 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 28e7ca6518..fdfc25da9d 100644
--- 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
index 0000000000..0beb1f8d37
--- /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 61df6e0e60..79f8233978 100644
--- 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 d16420c7e7..c8654d6725 100644
--- 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 \