Configurator: document new pkg-config plugin behaviors

Signed-off-by: Pierre Boutillier <pierre.boutillier@laposte.net>

doc/changes/10937.md

@@ -0,0 +1,2 @@
+- Configurator uses `pkgconf` as pkg-config implementation when available
+  and forwards it the `target` of `ocamlc -config`. (#10937, @pirbo)

otherlibs/configurator/src/v1.mli

@@ -73,8 +73,11 @@ module Pkg_config : sig
     type configurator = t
     type t
 
-    (** Search pkg-config in PATH. Prefers the [PKG_CONFIG_PATH] environment
-        variable if set. Returns [None] if pkg-config is not found. *)
+    (** Search a pkg-config implementation in PATH. Use the one
+       defined in [PKG_CONFIG] environment variable if set else try
+       [pkgconf] then [pkg-config]. Append the [PKG_CONFIG_PATH]
+       environment variable to the searched pathes. Returns [None] if
+       nothing is not found. *)
     val get : configurator -> t option
 
     type package_conf =
@@ -84,9 +87,11 @@ module Pkg_config : sig
 
     (** [query t ~package] query pkg-config for the [package]. The package must
         not contain a version constraint. Multiple, unversioned packages are
-        separated with spaces, for example "gtk+-3.0 gtksourceview-3.0". If set,
-        the [PKG_CONFIG_ARGN] environment variable specifies a list of arguments
-        to pass to pkg-config. Returns [None] if [package] is not available *)
+        separated with spaces, for example "gtk+-3.0 gtksourceview-3.0". By
+        default, the OCaml compiler [target] is passed to pkgconf as
+        {v --personality v} argument. An alternative list of arguments can be
+        specified by setting the [PKG_CONFIG_ARGN] environment variable.
+        Returns [None] if [package] is not available *)
     val query : t -> package:string -> package_conf option
 
     val query_expr : t -> package:string -> expr:string -> package_conf option
@@ -95,8 +100,10 @@ module Pkg_config : sig
     (** [query_expr_err t ~package ~expr] query pkg-config for the [package].
         [expr] may contain a version constraint, for example "gtk+-3.0 >= 3.18".
         [package] must be just the name of the package. If [expr] is specified,
-        [package] must be specified as well. If set, the [PKG_CONFIG_ARGN]
-        environment variable specifies a list of arguments to pass to pkg-config.
+        [package] must be specified as well. By default, the OCaml compiler
+        "target" is passed to pkgconf as {v --personality v} argument. An
+        alternative list of arguments can be specified by setting the
+        [PKG_CONFIG_ARGN] environment variable.
         Returns [Error error_msg] if [package] is not available *)
     val query_expr_err
       :  t