Add check-shlib-syms to faq/ports

ports@, Here a small rework of faq/ports with introducing of check-shlib-syms and replacing nm suggestion to that tool. Thoughts? Ok? Index: faq/ports/guide.html =================================================================== RCS file: /home/cvs/www/faq/ports/guide.html,v diff -u -p -r1.114 guide.html --- faq/ports/guide.html 8 May 2026 15:45:15 -0000 1.114 +++ faq/ports/guide.html 20 May 2026 16:27:23 -0000 @@ -586,6 +586,9 @@ Verify shared library dependencies. Run <code>make port-lib-depends-check</code> and add every <code>LIB_DEPENDS</code> or <code>WANTLIB</code> annotation that is needed until it runs cleanly. +For ports that build shared libraries, also run +<code>make check-shlib-syms</code> to see whether <code>SHARED_LIBS</code> +needs a version bump. You may want to read <a href="#PortsUpdate">the update guidelines</a> to understand why this is so important. @@ -1212,8 +1215,11 @@ For libtool-based ports, you have the <c whether the software authors made significant changes. <i>Note well that this is not enough.</i> Many software authors do not really understand shared library issues. -You have to read the full diff between the old and the new version, and bump -library versions accordingly. +Run <code>make check-shlib-syms</code> to see whether dynamic export changes +require a <code>SHARED_LIBS</code> version bump. +You still have to read the full diff between the old and the new version, +because added exports do not prove that a minor bump is sufficient, and an +empty result only means that no dynamic export change was reported. When in doubt, bump the major version. <li> Index: faq/ports/specialtopics.html =================================================================== RCS file: /home/cvs/www/faq/ports/specialtopics.html,v diff -u -p -r1.95 specialtopics.html --- faq/ports/specialtopics.html 8 May 2026 15:45:15 -0000 1.95 +++ faq/ports/specialtopics.html 20 May 2026 16:27:42 -0000 @@ -79,20 +79,20 @@ incompatible way, the library major numb This includes removing old functions. Any function removal should trigger a major number bump. -<li>A good hint is to compare the output of - -<pre class="cmdbox"> -$ <b>nm -g oldlib.so.X.Y | cut -c10- | grep -e^T</b> -</pre> - -and - -<pre class="cmdbox"> -$ <b>nm -g newlib.so.X.Y | cut -c10- | grep -e^T</b> -</pre> - -This won't show if function argument types changed, but at least you'll see -quickly if some functions were added and/or removed. +<li>A good hint is to run <code>make check-shlib-syms</code> whenever +you update a port that provides shared libraries. +It compares dynamic exports for shared libraries in the <code>PLIST</code> +against matching installed libraries. +Added exported symbols require at least a <code>SHARED_LIBS</code> minor bump; +removed exported symbols and changed data object sizes require a major bump. +This output is only a dynamic export check: added symbols do not prove that a +minor bump is sufficient, and an empty result only means there was no reported +dynamic export change. +You still have to read the full upstream diff and bump library versions for +ABI changes it cannot report. +New libraries have no installed counterpart, so they are reported and skipped; +use the initial <code>SHARED_LIBS</code> version selected for the new library, +usually 0.0. </ul> <p> Index: faq/ports/testing.html =================================================================== RCS file: /home/cvs/www/faq/ports/testing.html,v diff -u -p -r1.45 testing.html --- faq/ports/testing.html 8 May 2026 15:45:15 -0000 1.45 +++ faq/ports/testing.html 20 May 2026 16:18:05 -0000 @@ -209,6 +209,13 @@ or "Missing." </ul> <li> +<i>check-shlib-syms</i> +<ul><li> +This will check whether dynamic export changes in shared libraries require +a <code>SHARED_LIBS</code> version bump. +</ul> + +<li> <i>package</i> <ul><li> Package creation can break if <code>pkg/PLIST*</code> and/or -- wbr, Kirill