From: Kirill A. Korinsky Subject: Re: Add check-shlib-syms to faq/ports To: ports@openbsd.org Date: Fri, 05 Jun 2026 11:52:53 +0200 On Thu, 21 May 2026 18:46:54 +0200, Kirill A. Korinsky wrote: > > ports@, > > Here a small rework of faq/ports with introducing of check-shlib-syms and > replacing nm suggestion to that tool. > > Thoughts? Ok? > Anyone? 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 make port-lib-depends-check and add every LIB_DEPENDS or WANTLIB annotation that is needed until it runs cleanly. +For ports that build shared libraries, also run +make check-shlib-syms to see whether SHARED_LIBS +needs a version bump. You may want to read the update guidelines to understand why this is so important. @@ -1212,8 +1215,11 @@ For libtool-based ports, you have the Note well that this is not enough. 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 make check-shlib-syms to see whether dynamic export changes +require a SHARED_LIBS 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.
  • 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. -
  • A good hint is to compare the output of - -
    -$ nm -g oldlib.so.X.Y | cut -c10- | grep -e^T
-
    - -and - -
    -$ nm -g newlib.so.X.Y | cut -c10- | grep -e^T
-
    - -This won't show if function argument types changed, but at least you'll see -quickly if some functions were added and/or removed. +
  • A good hint is to run make check-shlib-syms whenever +you update a port that provides shared libraries. +It compares dynamic exports for shared libraries in the PLIST +against matching installed libraries. +Added exported symbols require at least a SHARED_LIBS 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 SHARED_LIBS version selected for the new library, +usually 0.0.

    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."

  • +check-shlib-syms +
    • +This will check whether dynamic export changes in shared libraries require +a SHARED_LIBS version bump. +
    + +
  • package
    • Package creation can break if pkg/PLIST* and/or -- wbr, Kirill