Attachment 138204 Details for Bug 105572 – Update the guide to include Requires.internal

[patch] Update the guide to include Requires.internal

Update-the-guide-to-include-Requiresinternal.patch (text/plain), 5.24 KB, created by Xavier Claessens on 2018-03-19 15:23:42 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Xavier Claessens

Created: 2018-03-19 15:23:42 UTC

Size: 5.24 KB

patch

obsolete

>From 1579a87b3b81244fe56b63d1e51f7d2b068f0757 Mon Sep 17 00:00:00 2001
>From: Xavier Claessens <xavier.claessens@collabora.com>
>Date: Mon, 19 Mar 2018 11:16:29 -0400
>Subject: [PATCH] Update the guide to include Requires.internal
>
>https://bugs.freedesktop.org/show_bug.cgi?id=105572
>---
> pkg-config-guide.html | 50 ++++++++++++++++++++++++++++++--------------------
> 1 file changed, 30 insertions(+), 20 deletions(-)
>
>diff --git a/pkg-config-guide.html b/pkg-config-guide.html
>index c666fe5..9ebce3f 100644
>--- a/pkg-config-guide.html
>+++ b/pkg-config-guide.html
>@@ -121,13 +121,23 @@ Libs: -L${libdir} -lfoo</pre>
> 
> <li>Requires: A list of packages required by this package. The
> versions of these packages may be specified using the comparison operators
>- =, &lt;, &gt;, &lt;= or &gt;=.</li>
>+ =, &lt;, &gt;, &lt;= or &gt;=. This is to be used when an application
>+ using this package will have to use symbols and APIs from a dependent
>+ library. </li>
> 
> <li>Requires.private: A list of private packages required by this
> package but not exposed to applications. The version specific rules from
>- the <tt>Requires</tt> field also apply here.</li>
>+ the <tt>Requires</tt> field also apply here. This is to be used when an
>+ application using this package needs header files from a dependent library
>+ but is not likely to call any of their symbols.</li>
> 
>- <li>Conflicts: An optional field describing packages that this one
>+ <li>Requires.internal: A list of internal packages required by this
>+ package but not exposed to applications. The version specific rules from
>+ the <tt>Requires</tt> field also apply here. This is to be used when
>+ this package uses a library as internal implementation detail but is not
>+ exposed neither in its API nor ABI.</li>
>+
>+ <li>Conflicts: An op tional field describing packages that this one
> conflicts with. The version specific rules from the <tt>Requires</tt>
> field also apply here. This field also takes multiple instances of the
> same package. E.g., <tt>Conflicts: bar < 1.2.3, bar >= 1.3.0</tt>.</li>
>@@ -186,25 +196,25 @@ includedir=${prefix}/include
> Cflags: -I${includedir}/foo</pre>
> 
> The most important <tt>pkg-config</tt> metadata fields are
>- <tt>Requires</tt>, <tt>Requires.private</tt>, <tt>Cflags</tt>, <tt>Libs</tt>
>- and <tt>Libs.private</tt>. They will define the metadata used by external
>- projects to compile and link with the library.
>-
>- <tt>Requires</tt> and <tt>Requires.private</tt> define other modules
>- needed by the library. It is usually preferred to use the private variant of
>- <tt>Requires</tt> to avoid exposing unnecessary libraries to the program
>- that is linking with your library. If the program will not be using the
>- symbols of the required library, it should not be linking directly to that
>- library. See the discussion of
>+ <tt>Requires</tt>, <tt>Requires.private</tt>, <tt>Requires.internal</tt>,
>+ <tt>Cflags</tt>, <tt>Libs</tt> and <tt>Libs.private</tt>. They will define
>+ the metadata used by external projects to compile and link with the library.
>+
>+ <tt>Requires</tt>, <tt>Requires.private</tt> and <tt>Requires.internal</tt>
>+ define other modules needed by the library. It is usually preferred to use the
>+ private variant of <tt>Requires</tt> to avoid exposing unnecessary libraries
>+ to the program that is linking with your library. If the program will not be
>+ using the symbols of the required library, it should not be linking directly
>+ to that library. See the discussion of
> <a href="https://wiki.openmandriva.org/en/Overlinking_issues_in_packaging">overlinking</a>
> for a more thorough explanation.
> 
> Since <tt>pkg-config</tt> always exposes the link flags of the
> <tt>Requires</tt> libraries, these modules will become direct dependencies
> of the program. On the other hand, libraries from <tt>Requires.private</tt>
>- will only be included when static linking. For this reason, it is usually
>- only appropriate to add modules from the same package in <tt>Requires</tt>.
>- 
>+ and <tt>Requires.internal</tt> will only be included when static linking. For
>+ this reason, it is usually only appropriate to add modules from the same
>+ package in <tt>Requires</tt>.
> 
> The <tt>Libs</tt> field contains the link flags necessary to use that
> library. In addition, <tt>Libs</tt> and <tt>Libs.private</tt> contain link
>@@ -404,10 +414,10 @@ myapp_LDADD = $(X_LIBS)</pre>
> expose <tt>libx</tt> data types in its public API. What do I put in my
> <tt>z.pc</tt> file?</li>
> 
>- Again, add the module to <tt>Requires.private</tt> if it supports
>- <tt>pkg-config</tt>. In this case, the compiler flags will be emitted
>- unnecessarily, but it ensures that the linker flags will be present when
>- linking statically. If <tt>libx</tt> does not support <tt>pkg-config</tt>,
>+ Add the module to <tt>Requires.internal</tt> if it supports
>+ <tt>pkg-config</tt>. Unlike <tt>Requires.private</tt> the compiler flags
>+ will not be emitted, but it ensures that the linker flags will be present
>+ when linking statically. If <tt>libx</tt> does not support <tt>pkg-config</tt>,
> add the necessary linker flags to <tt>Libs.private</tt>.
> </ol>
> 
>-- 
>2.14.1

Actions: View | Splinter Review

Attachments on bug 105572: 138185 | 138186 | 138201 | 138202 | 138203 | 138204 | 138281 | 138282

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.