[PATCH v3] ref-manual/variables.rst: document PACKAGE_KEEP_SECTIONS

[PATCH v3] ref-manual/variables.rst: document PACKAGE_KEEP_SECTIONS

[Mathieu Othacehe]

Document the PACKAGE_KEEP_SECTIONS variable added to
openembedded-core, which can be used to keep specific ELF sections
(such as .debug_frame, for use with libunwind) around when stripping
binaries and libraries.

Companion documentation for the openembedded-core patch "lib/oe/package:
Add strip keep-section support", sent separately to the oe-core list.

Signed-off-by: Mathieu Othacehe <othacehe@gnu.org>
---
 documentation/ref-manual/variables.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 83bc59e..1ea1d5a 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7166,6 +7166,30 @@ system and gives an overview of their function and contents.
       install, the build system does not generate an error. This variable
       is generally not user-defined.
 
+   :term:`PACKAGE_KEEP_SECTIONS`
+      Specifies a space-separated list of ELF sections to keep when
+      stripping binaries and shared libraries, even though they would
+      normally be removed by :term:`STRIP`. This variable is never applied
+      to kernel modules.
+
+      For example, on 32-bit Arm targets, GCC can emit DWARF Call Frame
+      Information for stack unwinding under the ``.debug_frame`` section
+      instead of the ``.eh_frame`` section used on most other
+      architectures. Tools such as `libunwind
+      <https://www.nongnu.org/libunwind/>`__ can use that information, for
+      example to produce a full backtrace when an unhandled C++ exception
+      is thrown, which the ``.ARM.exidx``/``.ARM.extab`` unwind tables
+      that GCC generates by default do not always allow (see `GCC bug
+      117941 <https://gcc.gnu.org/bugzilla/show_bug.cgi?id=117941>`__). By
+      default this section is removed like any other debug section, but
+      it can be kept with::
+
+         PACKAGE_KEEP_SECTIONS:pn-myrecipe = ".debug_frame"
+
+      .. note::
+
+         Keeping extra sections increases the size of stripped binaries.
+
    :term:`PACKAGE_NO_LOCALE`
       The :term:`PACKAGE_NO_LOCALE` variable can be set to "1" to prevent the
       :term:`OpenEmbedded Build System` from splitting the locales found in the
-- 
2.34.1