GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Update documentation for gpgme.pc and pkg-config.

Browse Source 
--

GnuPG-bug-id: 6274
Signed-off-by: NIIBE Yutaka <gniibe@fsij.org>
This commit is contained in:
NIIBE Yutaka 2022-11-15 14:25:26 +09:00
parent abd51848bd
commit ae2057e601
No known key found for this signature in database
GPG Key ID: 640114AF89DE6054
1 changed files with 55 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
doc/gpgme.texi
View File

@ -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