From 1579a87b3b81244fe56b63d1e51f7d2b068f0757 Mon Sep 17 00:00:00 2001 From: Xavier Claessens 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
  • Requires: A list of packages required by this package. The versions of these packages may be specified using the comparison operators - =, <, >, <= or >=.
    • + =, <, >, <= or >=. This is to be used when an application + using this package will have to use symbols and APIs from a dependent + library.
  • Requires.private: A list of private packages required by this package but not exposed to applications. The version specific rules from - the Requires field also apply here.
    • + the Requires 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. -
  • Conflicts: An optional field describing packages that this one +
  • Requires.internal: A list of internal packages required by this + package but not exposed to applications. The version specific rules from + the Requires 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.
    • + +
  • Conflicts: An op tional field describing packages that this one conflicts with. The version specific rules from the Requires field also apply here. This field also takes multiple instances of the same package. E.g., Conflicts: bar < 1.2.3, bar >= 1.3.0.
    • @@ -186,25 +196,25 @@ includedir=${prefix}/include Cflags: -I${includedir}/foo

    The most important pkg-config metadata fields are - Requires, Requires.private, Cflags, Libs - and Libs.private. They will define the metadata used by external - projects to compile and link with the library.

    - -

    Requires and Requires.private define other modules - needed by the library. It is usually preferred to use the private variant of - Requires 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 + Requires, Requires.private, Requires.internal, + Cflags, Libs and Libs.private. They will define + the metadata used by external projects to compile and link with the library.

    + +

    Requires, Requires.private and Requires.internal + define other modules needed by the library. It is usually preferred to use the + private variant of Requires 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 overlinking for a more thorough explanation.

    Since pkg-config always exposes the link flags of the Requires libraries, these modules will become direct dependencies of the program. On the other hand, libraries from Requires.private - will only be included when static linking. For this reason, it is usually - only appropriate to add modules from the same package in Requires. -

    + and Requires.internal will only be included when static linking. For + this reason, it is usually only appropriate to add modules from the same + package in Requires.

    The Libs field contains the link flags necessary to use that library. In addition, Libs and Libs.private contain link @@ -404,10 +414,10 @@ myapp_LDADD = $(X_LIBS) expose libx data types in its public API. What do I put in my z.pc file? -

    Again, add the module to Requires.private if it supports - pkg-config. In this case, the compiler flags will be emitted - unnecessarily, but it ensures that the linker flags will be present when - linking statically. If libx does not support pkg-config, +

    Add the module to Requires.internal if it supports + pkg-config. Unlike Requires.private the compiler flags + will not be emitted, but it ensures that the linker flags will be present + when linking statically. If libx does not support pkg-config, add the necessary linker flags to Libs.private.

    -- 2.14.1