2. Preparation

To use FreeMD, 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 Multi Threading		How FreeMD can be used in an MT environment.

2.1 Header

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

#include <freemd.h>

The name space of FreeMD is freemd_* for symbol names and FREEMD_* for macros. Exported symbols internal to FreeMD take the form _freemd_*.

Because FreeMD links to the USB library, linking to FreeMD will also use the namespace of that library indirectly.

2.2 Building the Source

If you want to compile a source file including the `freemd.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, FreeMD ships with a small helper program freemd-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 freemd-config. The following example shows how it can be used at the command line:

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

Adding the output of `freemd-config --cflags' to the compilers command line will ensure that the compiler can find the FreeMD 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 freemd-config can be used. For convenience, this option also outputs all other options that are required to link the program with FreeMD (in particular, the `-lfreemd' option). The example shows how to link `foo.o' with the FreeMD library to a program foo.

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

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

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

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 freemd-config script at all. FreeMD provides an extension to Automake that does all the work for you.

Macro: AM_PATH_FREEMD ([minimum-version], [action-if-found], [action-if-not-found])

Check whether FreeMD (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 FREEMD_CFLAGS to the flags needed for compilation of the program to find the `freemd.h' header file, and FREEMD_LIBS to the linker flags needed to link the program to the FreeMD library.

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

AM_CPPFLAGS = $(FREEMD_CFLAGS) LDADD = $(FREEMD_LIBS)

2.4 Multi Threading

The freemd library is not thread-safe.