[PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Robert P. J. Day]

  * Add note about new URL for FHS 3.0.
  * Add wildcard for "INHIBIT_" variable.
  * Fix font for ${PN}.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
index a05f39ca1..077184657 100644
--- a/documentation/dev-manual/prebuilt-libraries.rst
+++ b/documentation/dev-manual/prebuilt-libraries.rst
@@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
 This section shows how to deal with both versioned and unversioned
 pre-built libraries.

+.. note::
+
+   In the shared library article referenced above, the link to the current
+   version of the Filesystem Hierarchy Standard (FHS) is out of date;
+   the current FHS 3.0 release can be found
+   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
+
 Versioned Libraries
 ===================

@@ -79,7 +86,7 @@ To write a recipe to use such a library in your system:
 -  The vendor will typically ship release builds without debugging symbols.
    Avoid errors by preventing the packaging task from stripping out the symbols
    and adding them to a separate debug package. This is done by setting the
-   ``INHIBIT_`` flags shown below.
+   ``INHIBIT_*`` flags shown below.

 The complete recipe would look like this::

@@ -170,7 +177,7 @@ as follows::
 The modifications cause the ``.so`` file to be the real library
 and unset :term:`FILES_SOLIBSDEV` so that no libraries get packaged into
 ``${PN}-dev``. The changes are required because unless :term:`PACKAGES` is changed,
-``${PN}-dev`` collects files before `${PN}`. ``${PN}-dev`` must not collect any of
+``${PN}-dev`` collects files before ``${PN}``. ``${PN}-dev`` must not collect any of
 the files you want in ``${PN}``.

 Finally, loadable modules, essentially unversioned libraries that are linked

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Quentin Schulz]

Hi Robert,

On 6/22/25 12:59 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> 
>    * Add note about new URL for FHS 3.0.
>    * Add wildcard for "INHIBIT_" variable.
>    * Fix font for ${PN}.
> 
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> 
> ---
> 
> diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
> index a05f39ca1..077184657 100644
> --- a/documentation/dev-manual/prebuilt-libraries.rst
> +++ b/documentation/dev-manual/prebuilt-libraries.rst
> @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
>   This section shows how to deal with both versioned and unversioned
>   pre-built libraries.
> 
> +.. note::
> +
> +   In the shared library article referenced above, the link to the current
> +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
> +   the current FHS 3.0 release can be found
> +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
> +

Considering FHS 2.3 was released Jan 2004 and FHS 3.0 on Jun 2015, will 
we have another FHS version end of 2026?

We can simply link to https://refspecs.linuxfoundation.org/fhs.shtml so 
we hopefully aren't outdated ourselves later on as well?

Looks good to me otherwise!
Thanks!
Quentin

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Robert P. J. Day]

On Mon, 23 Jun 2025, Quentin Schulz wrote:

> Hi Robert,
>
> On 6/22/25 12:59 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> >
> >    * Add note about new URL for FHS 3.0.
> >    * Add wildcard for "INHIBIT_" variable.
> >    * Fix font for ${PN}.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> > diff --git a/documentation/dev-manual/prebuilt-libraries.rst
> > b/documentation/dev-manual/prebuilt-libraries.rst
> > index a05f39ca1..077184657 100644
> > --- a/documentation/dev-manual/prebuilt-libraries.rst
> > +++ b/documentation/dev-manual/prebuilt-libraries.rst
> > @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two
> > conditions:
> >   This section shows how to deal with both versioned and unversioned
> >   pre-built libraries.
> >
> > +.. note::
> > +
> > +   In the shared library article referenced above, the link to the current
> > +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
> > +   the current FHS 3.0 release can be found
> > +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
> > +
>
> Considering FHS 2.3 was released Jan 2004 and FHS 3.0 on Jun 2015, will we
> have another FHS version end of 2026?
>
> We can simply link to https://refspecs.linuxfoundation.org/fhs.shtml so we
> hopefully aren't outdated ourselves later on as well?
>
> Looks good to me otherwise!

  there is no discernible timeline for anything beyond FHS 3.0 that i
know of.

rday

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Antonin Godard]

On Sun Jun 22, 2025 at 12:59 PM CEST, Robert P. J. Day wrote:
>
>   * Add note about new URL for FHS 3.0.
>   * Add wildcard for "INHIBIT_" variable.
>   * Fix font for ${PN}.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---
>
> diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
> index a05f39ca1..077184657 100644
> --- a/documentation/dev-manual/prebuilt-libraries.rst
> +++ b/documentation/dev-manual/prebuilt-libraries.rst
> @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
>  This section shows how to deal with both versioned and unversioned
>  pre-built libraries.
>
> +.. note::
> +
> +   In the shared library article referenced above, the link to the current
> +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
> +   the current FHS 3.0 release can be found
> +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.

Not sure adding a note to say a link is outdated is the good approach.
Instead update the link above?

>  Versioned Libraries
>  ===================
>
> @@ -79,7 +86,7 @@ To write a recipe to use such a library in your system:
>  -  The vendor will typically ship release builds without debugging symbols.
>     Avoid errors by preventing the packaging task from stripping out the symbols
>     and adding them to a separate debug package. This is done by setting the
> -   ``INHIBIT_`` flags shown below.
> +   ``INHIBIT_*`` flags shown below.
>
>  The complete recipe would look like this::
>
> @@ -170,7 +177,7 @@ as follows::
>  The modifications cause the ``.so`` file to be the real library
>  and unset :term:`FILES_SOLIBSDEV` so that no libraries get packaged into
>  ``${PN}-dev``. The changes are required because unless :term:`PACKAGES` is changed,
> -``${PN}-dev`` collects files before `${PN}`. ``${PN}-dev`` must not collect any of
> +``${PN}-dev`` collects files before ``${PN}``. ``${PN}-dev`` must not collect any of

Can you send this in a separate patch?

>  the files you want in ``${PN}``.
>
>  Finally, loadable modules, essentially unversioned libraries that are linked


Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Robert P. J. Day]

On Tue, 24 Jun 2025, Antonin Godard wrote:

> On Sun Jun 22, 2025 at 12:59 PM CEST, Robert P. J. Day wrote:
> >
> >   * Add note about new URL for FHS 3.0.
> >   * Add wildcard for "INHIBIT_" variable.
> >   * Fix font for ${PN}.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> > diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
> > index a05f39ca1..077184657 100644
> > --- a/documentation/dev-manual/prebuilt-libraries.rst
> > +++ b/documentation/dev-manual/prebuilt-libraries.rst
> > @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
> >  This section shows how to deal with both versioned and unversioned
> >  pre-built libraries.
> >
> > +.. note::
> > +
> > +   In the shared library article referenced above, the link to the current
> > +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
> > +   the current FHS 3.0 release can be found
> > +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
>
> Not sure adding a note to say a link is outdated is the good approach.
> Instead update the link above?
>
> >  Versioned Libraries
> >  ===================
> >
> > @@ -79,7 +86,7 @@ To write a recipe to use such a library in your system:
> >  -  The vendor will typically ship release builds without debugging symbols.
> >     Avoid errors by preventing the packaging task from stripping out the symbols
> >     and adding them to a separate debug package. This is done by setting the
> > -   ``INHIBIT_`` flags shown below.
> > +   ``INHIBIT_*`` flags shown below.
> >
> >  The complete recipe would look like this::
> >
> > @@ -170,7 +177,7 @@ as follows::
> >  The modifications cause the ``.so`` file to be the real library
> >  and unset :term:`FILES_SOLIBSDEV` so that no libraries get packaged into
> >  ``${PN}-dev``. The changes are required because unless :term:`PACKAGES` is changed,
> > -``${PN}-dev`` collects files before `${PN}`. ``${PN}-dev`` must not collect any of
> > +``${PN}-dev`` collects files before ``${PN}``. ``${PN}-dev`` must not collect any of
>
> Can you send this in a separate patch?

  do you mean the FHS fix as one patch, and all else as a second
patch?  can do.

rday

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Antonin Godard]

On Tue Jun 24, 2025 at 10:19 AM CEST, Robert P. J. Day wrote:
> On Tue, 24 Jun 2025, Antonin Godard wrote:
>
>> On Sun Jun 22, 2025 at 12:59 PM CEST, Robert P. J. Day wrote:
>> >
>> >   * Add note about new URL for FHS 3.0.
>> >   * Add wildcard for "INHIBIT_" variable.
>> >   * Fix font for ${PN}.
>> >
>> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>> >
>> > ---
>> >
>> > diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
>> > index a05f39ca1..077184657 100644
>> > --- a/documentation/dev-manual/prebuilt-libraries.rst
>> > +++ b/documentation/dev-manual/prebuilt-libraries.rst
>> > @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
>> >  This section shows how to deal with both versioned and unversioned
>> >  pre-built libraries.
>> >
>> > +.. note::
>> > +
>> > +   In the shared library article referenced above, the link to the current
>> > +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
>> > +   the current FHS 3.0 release can be found
>> > +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
>>
>> Not sure adding a note to say a link is outdated is the good approach.
>> Instead update the link above?
>>
>> >  Versioned Libraries
>> >  ===================
>> >
>> > @@ -79,7 +86,7 @@ To write a recipe to use such a library in your system:
>> >  -  The vendor will typically ship release builds without debugging symbols.
>> >     Avoid errors by preventing the packaging task from stripping out the symbols
>> >     and adding them to a separate debug package. This is done by setting the
>> > -   ``INHIBIT_`` flags shown below.
>> > +   ``INHIBIT_*`` flags shown below.
>> >
>> >  The complete recipe would look like this::
>> >
>> > @@ -170,7 +177,7 @@ as follows::
>> >  The modifications cause the ``.so`` file to be the real library
>> >  and unset :term:`FILES_SOLIBSDEV` so that no libraries get packaged into
>> >  ``${PN}-dev``. The changes are required because unless :term:`PACKAGES` is changed,
>> > -``${PN}-dev`` collects files before `${PN}`. ``${PN}-dev`` must not collect any of
>> > +``${PN}-dev`` collects files before ``${PN}``. ``${PN}-dev`` must not collect any of
>>
>> Can you send this in a separate patch?
>
>   do you mean the FHS fix as one patch, and all else as a second
> patch?  can do.

I mean the part fixing the `${PN}` not being ``${PN}``.

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Robert P. J. Day]

On Tue, 24 Jun 2025, Antonin Godard via lists.yoctoproject.org wrote:

> On Sun Jun 22, 2025 at 12:59 PM CEST, Robert P. J. Day wrote:
> >
> >   * Add note about new URL for FHS 3.0.
> >   * Add wildcard for "INHIBIT_" variable.
> >   * Fix font for ${PN}.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> > diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
> > index a05f39ca1..077184657 100644
> > --- a/documentation/dev-manual/prebuilt-libraries.rst
> > +++ b/documentation/dev-manual/prebuilt-libraries.rst
> > @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
> >  This section shows how to deal with both versioned and unversioned
> >  pre-built libraries.
> >
> > +.. note::
> > +
> > +   In the shared library article referenced above, the link to the current
> > +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
> > +   the current FHS 3.0 release can be found
> > +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
>
> Not sure adding a note to say a link is outdated is the good approach.
> Instead update the link above?

  i'm not sure that's the right way to do it. that old article is
quite a decent explanation of library versioning; if we now link
directly to the FHS spec from the yocto docs and bypass that article,
we lose a lot of good intro-level explanation.

  thoughts?

rday

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Antonin Godard]

On Tue Jun 24, 2025 at 10:31 AM CEST, Robert P. J. Day wrote:
> On Tue, 24 Jun 2025, Antonin Godard via lists.yoctoproject.org wrote:
>
>> On Sun Jun 22, 2025 at 12:59 PM CEST, Robert P. J. Day wrote:
>> >
>> >   * Add note about new URL for FHS 3.0.
>> >   * Add wildcard for "INHIBIT_" variable.
>> >   * Fix font for ${PN}.
>> >
>> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>> >
>> > ---
>> >
>> > diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
>> > index a05f39ca1..077184657 100644
>> > --- a/documentation/dev-manual/prebuilt-libraries.rst
>> > +++ b/documentation/dev-manual/prebuilt-libraries.rst
>> > @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
>> >  This section shows how to deal with both versioned and unversioned
>> >  pre-built libraries.
>> >
>> > +.. note::
>> > +
>> > +   In the shared library article referenced above, the link to the current
>> > +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
>> > +   the current FHS 3.0 release can be found
>> > +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
>>
>> Not sure adding a note to say a link is outdated is the good approach.
>> Instead update the link above?
>
>   i'm not sure that's the right way to do it. that old article is
> quite a decent explanation of library versioning; if we now link
> directly to the FHS spec from the yocto docs and bypass that article,
> we lose a lot of good intro-level explanation.
>
>   thoughts?

I see. Then as Quentin suggested I think it's reasonable to link to
https://refspecs.linuxfoundation.org/fhs.shtml instead of the 3.0 version, and
say:

"""
the latest release can be found `here
<https://refspecs.linuxfoundation.org/fhs.shtml>`__.
"""

Thanks,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] dev-manual: some minor cleanups to "Pre-Built Libraries"

[Robert P. J. Day]

On Tue, 24 Jun 2025, Antonin Godard via lists.yoctoproject.org wrote:

> On Tue Jun 24, 2025 at 10:31 AM CEST, Robert P. J. Day wrote:
> > On Tue, 24 Jun 2025, Antonin Godard via lists.yoctoproject.org wrote:
> >
> >> On Sun Jun 22, 2025 at 12:59 PM CEST, Robert P. J. Day wrote:
> >> >
> >> >   * Add note about new URL for FHS 3.0.
> >> >   * Add wildcard for "INHIBIT_" variable.
> >> >   * Fix font for ${PN}.
> >> >
> >> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >> >
> >> > ---
> >> >
> >> > diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
> >> > index a05f39ca1..077184657 100644
> >> > --- a/documentation/dev-manual/prebuilt-libraries.rst
> >> > +++ b/documentation/dev-manual/prebuilt-libraries.rst
> >> > @@ -22,6 +22,13 @@ To summarize, a versioned library must meet two conditions:
> >> >  This section shows how to deal with both versioned and unversioned
> >> >  pre-built libraries.
> >> >
> >> > +.. note::
> >> > +
> >> > +   In the shared library article referenced above, the link to the current
> >> > +   version of the Filesystem Hierarchy Standard (FHS) is out of date;
> >> > +   the current FHS 3.0 release can be found
> >> > +   `here <https://refspecs.linuxfoundation.org/FHS_3.0/index.html>`__.
> >>
> >> Not sure adding a note to say a link is outdated is the good approach.
> >> Instead update the link above?
> >
> >   i'm not sure that's the right way to do it. that old article is
> > quite a decent explanation of library versioning; if we now link
> > directly to the FHS spec from the yocto docs and bypass that article,
> > we lose a lot of good intro-level explanation.
> >
> >   thoughts?
>
> I see. Then as Quentin suggested I think it's reasonable to link to
> https://refspecs.linuxfoundation.org/fhs.shtml instead of the 3.0 version, and
> say:
>
> """
> the latest release can be found `here
> <https://refspecs.linuxfoundation.org/fhs.shtml>`__.
> """

  I'll reword as first referring to that older article with the good
explanation of library versioning and SONAMEs, then add a reference to
the current FHS.

rday