pkgconfig: Improve and document generator behaviour

- Add libraries from InternalDependency.libraries
- Deprecate association of libraries from the "libraries" keyword
argument to the generated pkg-config file.

2 files changed, 81 insertions, 10 deletions

diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md
index 9a34e14..6aee0c7 100644
--- a/docs/markdown/Pkgconfig-module.md
+++ b/docs/markdown/Pkgconfig-module.md
@@ -5,9 +5,12 @@ This module is a simple generator for
 
 ## Usage
 
-To use this module, just do: **`pkg = import('pkgconfig')`**. The
-following function will then be available as `pkg.generate()`. You
-can, of course, replace the name `pkg` with anything else.
+```meson
+pkg = import('pkgconfig')
+bar_dep = dependency('bar')
+lib = library('foo', dependencies : [bar])
+pkg.generate(lib)
+```
 
 ### pkg.generate()
 
@@ -25,14 +28,13 @@ keyword arguments.
 - `libraries` a list of built libraries (usually results of
   shared_library) that the user needs to link against. Arbitrary strings can
   also be provided and they will be added into the `Libs` field. Since 0.45.0
-  dependencies of built libraries will be automatically added to `Libs.private`
-  field. If a dependency is provided by pkg-config then it will be added in
-  `Requires.private` instead. Other type of dependency objects can also be passed
-  and will result in their `link_args` and `compile_args` to be added to `Libs`
-  and `Cflags` fields.
+  dependencies of built libraries will be automatically added, see the
+  [Implicit dependencies](#Implicit_dependencies) section below for the exact
+  rules.
 - `libraries_private` list of built libraries or strings to put in the
-  `Libs.private` field. Since 0.45.0 it can also contain dependency objects,
-  their `link_args` will be added to `Libs.private`.
+  `Libs.private` field. Since 0.45.0 dependencies of built libraries will be
+  automatically added, see the [Implicit dependencies](#Implicit_dependencies)
+  section below for the exact rules.
 - `name` the name of this library, used to set the `Name:` field
 - `subdirs` which subdirs of `include` should be added to the header
   search path, for example if you install headers into
@@ -59,3 +61,38 @@ provided for all required fields of the pc file:
 - `install_dir` is set to `pkgconfig` folder in the same location than the provided library.
 - `description` is set to the project's name followed by the library's name.
 - `name` is set to the library's name.
+
+### Implicit dependencies
+
+The exact rules followed to find dependencies that are implicitly added into the
+pkg-config file have evolved over time. Here are the rules as of Meson *0.49.0*,
+previous versions might have slightly different behaviour.
+
+- Not found libraries or dependencies are ignored.
+- Libraries and dependencies are private by default (i.e. added into
+  `Requires.private:` or `Libs.private:`) unless they are explicitly added in
+  `libraries` or `requires` keyword arguments, or is the main library (first
+  positional argument).
+- Libraries and dependencies will be de-duplicated, if they are added in both
+  public and private (e.g `Requires:` and `Requires.private:`) it will be removed
+  from the private list.
+- Shared libraries (i.e. `shared_library()` and **NOT** `library()`) add only
+  `-lfoo` into `Libs:` or `Libs.private:` but their dependencies are not pulled.
+  This is because dependencies are only needed for static link.
+- Other libraries (i.e. `static_library()` or `library()`) add `-lfoo` into `Libs:`
+  or `Libs.private:` and recursively add their dependencies into `Libs.private:` or
+  `Requires.private:`.
+- Dependencies provided by pkg-config are added into `Requires:` or
+  `Requires.private:`. If a version was specified when declaring that dependency
+  it will be written into the generated file too.
+- The thread dependency (i.e. `dependency('thread')`) adds `-pthread` into
+  `Libs:` or `Libs.private:`.
+- Internal dependencies (i.e.
+  `declare_dependency(compiler_args : '-DFOO', link_args : '-Wl,something', link_with : foo)`)
+  add `compiler_args` into `Cflags:` if public, `link_args` and `link_with` into
+  `Libs:` if public or `Libs.private:` if private.
+- Other dependency types add their compiler arguments into `Cflags:` if public,
+  and linker arguments into `Libs:` if public or `Libs.private:` if private.
+- Once a pkg-config file is generated for a library using `pkg.generate(mylib)`,
+  any subsequent call to `pkg.generate()` where mylib appears, will generate a
+  `Requires:` or `Requires.private` instead of a `Libs:` or `Libs.private:`.
diff --git a/docs/markdown/snippets/pkgconfig_break.md b/docs/markdown/snippets/pkgconfig_break.md
new file mode 100644
index 0000000..49c908d
--- /dev/null
+++ b/docs/markdown/snippets/pkgconfig_break.md
@@ -0,0 +1,34 @@
+## Deprecation warning in pkg-config generator
+
+All libraries passed to the `libraries` keyword argument of the `generate()`
+method used to be associated with that generated pkg-config file. That means
+that any subsequent call to `generate()` where those libraries appear would add
+the filebase of the `generate()` that first contained them into `Requires:` or
+`Requires.private:` field instead of adding an `-l` to `Libs:` or `Libs.private:`.
+
+This behaviour is now deprecated. The library that should be associated with
+the generated pkg-config file should be passed as first positional argument
+instead of in the `libraries` keyword argument. The previous behaviour is
+maintained but prints a deprecation warning and support for this will be removed
+in a future Meson release. If you can not create the needed pkg-config file
+without this warning, please file an issue with as much details as possible
+about the situation.
+
+For example this sample will write `Requires: liba` into `libb.pc` but print a
+deprecation warning:
+```meson
+liba = library(...)
+pkg.generate(libraries : liba)
+
+libb = library(...)
+pkg.generate(libraries : [liba, libb])
+```
+
+It can be fixed by passing `liba` as first positional argument::
+```meson
+liba = library(...)
+pkg.generate(liba)
+
+libb = library(...)
+pkg.generate(libb, libraries : [liba])
+```