The `GnuPG Made Easy' Reference Manual: Preparation

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 2. Preparation

To use GPGME, you have to perform some changes to your sources and the build system. The necessary changes are small and explained in the following sections. At the end of this chapter, it is described how the library is initialized, and how the requirements of the library are verified.

> 2.1 Header |  | What header file you need to include.
> 2.2 Building the Source |  | Compiler options to be used.
> 2.3 Using Automake |  | Compiler options to be used the easy way.
> 2.4 Library Version Check |  | Getting and verifying the library version.
> 2.5 Multi Threading |  | How GPGME can be used in an MT environment.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.1 Header

All interfaces (data types and functions) of the library are defined in the header file `gpgme.h'. You must include this in all programs using the library, either directly or through some other header file, like this:

    #include <gpgme.h>

The name space of GPGME is `gpgme_*` for function names, `Gpgme*` for data types and `GPGME_*` for other symbols. Symbols internal to GPGME take the form `_gpgme_*`.

Because GPGME links to the Assuan library, linking to GPGME will also use the `assuan_*` and `_assuan_*` name space indirectly.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.2 Building the Source

If you want to compile a source file including the `gpgme.h' header file, you must make sure that the compiler can find it in the directory hierarchy. This is accomplished by adding the path to the directory in which the header file is located to the compilers include file search path (via the ``-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 `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 ``--cflags`' option to `gpgme-config`. The following example shows how it can be used at the command line:

    gcc -c foo.c `gpgme-config --cflags`

Adding the output of ``gpgme-config --cflags`' to the compilers command line will ensure that the compiler can find the GPGME header file.

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 ``-L`' option). For this, the option ``--libs`' to `gpgme-config` can be used. For convenience, this option also outputs all other options that are required to link the program with GPGME (in particular, the ``-lgpgme`' option). The example shows how to link ``foo.o`' with the GPGME library to a program `foo`.

    gcc -o foo foo.o `gpgme-config --libs`

Of course you can also combine both examples to a single command by specifying both options to `gpgme-config`:

    gcc -o foo foo.c `gpgme-config --cflags --libs`

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.3 Using Automake

It is much easier if you use GNU Automake instead writing your own Makefiles. If you do that you don't have to worry about finding and invoking the `gpgme-config` script at all. GPGME provides an extension to Automake that does all the work for you.

Macro: AM_PATH_GPGME ([minimum-version], [action-if-found], [action-if-not-found])
  Check whether GPGME (at least version minimum-version, if given) exists on the host system. If it is found, execute action-if-found, otherwise do action-if-not-found, if given.

  Additionally, the function defines `GPGME_CFLAGS` to the flags needed for compilation of the program to find the ``gpgme.h`' header file, and `GPGME_LIBS` to the linker flags needed to link the program to the GPGME library.

You can use the defined Autoconf variables like this in your ``Makefile.am`':

    AM_CPPFLAGS = $(GPGME_CFLAGS)
    LDADD = $(GPGME_LIBS)

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.4 Library Version Check

Function: const char * gpgme_check_version (const char *required_version)
  The function `gpgme_check_version` has three purposes. It can be used to retrieve the version number of the library. In addition it can verify that the version number is higher than a certain required version number. In either case, the function initializes some sub-systems, and for this reason alone it must be invoked early in your program, before you make use of the other functions in GPGME.

  If required_version is `NULL`, the function returns a pointer to a statically allocated string containing the version number of the library.

  If required_version is not `NULL`, it should point to a string containing a version number, and the function checks that the version of the library is at least as high as the version number provided. In this case, the function returns a pointer to a statically allocated string containing the version number of the library. If REQUIRED_VERSION is not a valid version number, or if the version requirement is not met, the function returns `NULL`.

  If you use a version of a library that is backwards compatible with older releases, but contains additional interfaces which your program uses, this function provides a run-time check if the necessary features are provided by the installed version of the library.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.5 Multi Threading

The GPGME library is not entirely thread-safe, but it can still be used in a multi-threaded environment if some care is taken. If the following requirements are met, there should be no race conditions to worry about:

- GPGME supports the thread libraries pthread and GNU Pth. The support for this has to be enabled at compile time. GPGME will automatically detect the location in which the thread libraries are installed and activate the support for them.

  Support for other thread libraries is very easy to add. Please contact us if you have the need.

- If you link your program dynamically to GPGME and your supported thread library, GPGME will automatically detect the presence of this library and activate its use. If you link to both pthread and GNU Pth, GPGME will use the pthread support. This feature requires weak symbol support.

- If you link your program statically to GPGME, there is currently no easy way to make sure that GPGME detects the presence of the thread library. This will be solved in a future version.

- The function `gpgme_check_version` must be called before any other function in the library, because it initializes the thread support subsystem in GPGME. To achieve this in all generality, it is necessary to synchronize the call to this function with all other calls to functions in the library, using the synchronization mechanisms available in your thread library. Otherwise, specific compiler or CPU memory cache optimizations could lead to the situation where a thread is started and uses GPGME before the effects of the initialization are visible for this thread. It doesn't even suffice to call `gpgme_check_version` before creating this other thread(1).

  For example, if you are using POSIX threads, each thread that wants to call functions in GPGME could call the following function before any function in the library:

      #include <pthread.h>

      void
      initialize_gpgme (void)
      {
        static int gpgme_init;
        static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;

        pthread_mutex_lock (&gpgme_init_lock);
        if (!gpgme_init)
          {
            gpgme_check_version ();
            gpgme_init = 1;
          }
        pthread_mutex_unlock (&gpgme_init_lock);
      }

- Any `GpgmeData`, `GpgmeCtx` and `GpgmeRecipients` object must only be accessed by one thread at a time. If multiple threads want to deal with the same object, the caller has to make sure that operations on this object are fully synchronized.

- Only one thread at any time is allowed to call `gpgme_wait`. If multiple threads call this function, the caller must make sure that all invocations are fully synchronized.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by John Goerzen on November, 21 2002 using texi2html