From ae2057e6017427941aef00ccf1b7a9f6b0e3189c Mon Sep 17 00:00:00 2001 From: NIIBE Yutaka Date: Tue, 15 Nov 2022 14:25:26 +0900 Subject: [PATCH] doc: Update documentation for gpgme.pc and pkg-config. -- GnuPG-bug-id: 6274 Signed-off-by: NIIBE Yutaka --- doc/gpgme.texi | 99 ++++++++++++++++++++++++++++---------------------- 1 file changed, 55 insertions(+), 44 deletions(-) diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 327a5ea1..e88bf2ac 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -421,18 +421,28 @@ directory in which the header file is located to the compilers include file search path (via the @option{-I} option). However, the path to the include file is determined at the time the -source is configured. To solve this problem, gpgme ships with a small -helper program @command{gpgme-config} that knows about the path to the -include file and other configuration options. The options that need -to be added to the compiler invocation at compile time are output by -the @option{--cflags} option to @command{gpgme-config}. The following -example shows how it can be used at the command line: +source is configured. To solve this problem, gpgme ships with +@code{gpgme.pc} file, that knows about the path to the include file +and other configuration options. The command, @command{pkg-config}, +can be used to handle information with @code{gpgme.pc} file. In an +environment which doesn't have @command{pkg-config} (like the one in +early stage of OS bootstrap), for Automake, you can use +@code{gpgme.m4} which invokes @command{gpgrt-config} with +@code{gpgme.pc}. (In the past, gpgme used to ship with a small helper +program @command{gpgme-config}. This functionality of +@command{gpgme-config} is replaced by @command{pkg-config} with +@code{gpgme.pc} file.) + +The options that need to be added to the compiler invocation at +compile time are output by the @option{--cflags} option to +@command{pkg-config gpgme}. The following example shows how it can be +used at the command line: @example -gcc -c foo.c `gpgme-config --cflags` +gcc -c foo.c `pkg-config --cflags gpgme` @end example -Adding the output of @samp{gpgme-config --cflags} to the compiler +Adding the output of @samp{pkg-config --cflags gpgme} to the compiler command line will ensure that the compiler can find the @acronym{GPGME} header file. @@ -440,36 +450,39 @@ A similar problem occurs when linking the program with the library. Again, the compiler has to find the library files. For this to work, the path to the library files has to be added to the library search path (via the @option{-L} option). For this, the option -@option{--libs} to @command{gpgme-config} can be used. For +@option{--libs} to @command{pkg-config gpgme} can be used. For convenience, this option also outputs all other options that are required to link the program with @acronym{GPGME} (in particular, the @samp{-lgpgme} option). The example shows how to link @file{foo.o} with the @acronym{GPGME} library to a program @command{foo}. @example -gcc -o foo foo.o `gpgme-config --libs` +gcc -o foo foo.o `pkg-config --libs gpgme` @end example Of course you can also combine both examples to a single command by -specifying both options to @command{gpgme-config}: +specifying both options to @command{pkg-config gpgme}: @example -gcc -o foo foo.c `gpgme-config --cflags --libs` -@end example - -If you need to detect the installed language bindings you can use list -them using: - -@example -gpgme-config --print-lang -@end example - -or test for the availability using - -@example -gpgme-config --have-lang=python && echo 'Bindings for Pythons available' +gcc -o foo foo.c `pkg-config --cflags --libs gpgme` @end example +@c +@c Feature not available by pkg-config/gpgrt-config +@c +@c If you need to detect the installed language bindings you can use list +@c them using: +@c +@c @example +@c gpgme-config --print-lang +@c @end example +@c +@c or test for the availability using +@c +@c @example +@c gpgme-config --have-lang=python && echo 'Bindings for Pythons available' +@c @end example +@c @node Largefile Support (LFS) @section Largefile Support (LFS) @@ -578,7 +591,7 @@ mode (@code{_LARGEFILE64_SOURCE}). It is much easier if you use GNU Automake instead of writing your own Makefiles. If you do that you do not have to worry about finding and -invoking the @command{gpgme-config} script at all. @acronym{GPGME} +invoking the @command{pkg-config} script at all. @acronym{GPGME} provides an extension to Automake that does all the work for you. @c A simple macro for optional variables. @@ -586,20 +599,28 @@ provides an extension to Automake that does all the work for you. @r{[}@var{\varname\}@r{]} @end macro @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) -@defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) -@defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) Check whether @acronym{GPGME} (at least version @var{minimum-version}, if given) exists on the host system. If it is found, execute @var{action-if-found}, otherwise do @var{action-if-not-found}, if given. +This macro locates for @code{gpgme.pc}, with cross-compile support. + Additionally, the function defines @code{GPGME_CFLAGS} to the flags needed for compilation of the program to find the @file{gpgme.h} header file, and @code{GPGME_LIBS} to the linker flags needed to link -the program to the @acronym{GPGME} library. If the used helper script -does not match the target type you are building for a warning is -printed and the string @code{libgcrypt} is appended to the variable -@code{gpg_config_script_warn}. +the program to the @acronym{GPGME} library. +@c +@c If the used helper script does not match the target type you are +@c building for a warning is printed and the string @code{gpgme} is +@c appended to the variable @code{gpg_config_script_warn}. +@c@c@c@c@c@c@c@c +@c ^-- About this statement. +@c In the past, this might happens, when it was configured by +@c --with-*-prefix options, and it located the helper script for +@c other target. Cross-build by gpgrt-config has been improved +@c (in different way), so it's not relevant now. +@c @code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME} that can be used with the native pthread implementation, and defines @@ -607,15 +628,6 @@ that can be used with the native pthread implementation, and defines version 1.8.0 this is no longer required to GPGME_PTHREAD as @acronym{GPGME} itself is thread safe. -This macro searches for @command{gpgme-config} along the PATH. If -you are cross-compiling, it is useful to set the environment variable -@code{SYSROOT} to the top directory of your target. The macro will -then first look for the helper program in the @file{bin} directory -below that top directory. An absolute directory name must be used for -@code{SYSROOT}. Finally, if the configure command line option -@code{--with-gpgme-prefix} is used, only its value is used for the top -directory below which the helper script is expected. - @end defmac You can use the defined Autoconf variables like this in your @@ -632,9 +644,8 @@ LDADD = $(GPGME_LIBS) @cindex libtool The easiest way is to just use GNU Libtool. If you use libtool, and -link to @code{libgpgme.la}, @code{libgpgme-pth.la} or -@code{libgpgme-pthread.la} respectively, everything will be done -automatically by Libtool. +link to @code{libgpgme.la}, everything will be done automatically by +Libtool. @node Library Version Check