From: Volker Schlecht <openbsd-ports@schlecht.dev>
Subject: Re: Add check-shlib-syms to faq/ports
To: ports@openbsd.org
Date: Sun, 7 Jun 2026 14:39:23 +0200

lgtm, but I think it would be better for a native speaker to ok that one...

On 6/5/26 11:52 AM, Kirill A. Korinsky wrote:
> On Thu, 21 May 2026 18:46:54 +0200,
> Kirill A. Korinsky <kirill@korins.ky> 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 <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
> 
>