Chapter 16. Using Libraries with GCC

A special file name convention is used for libraries: A library known as foo is expected to exist as the file libfoo.so or libfoo.a. This convention is automatically understood by the linking input options of gcc, but not by the output options:

Additional Resources

Developers have a choice of using static or dynamic linking when building applications with fully compiled languages. This section lists the differences, particularly in the contexti of using the C and C++ languages on Red Hat Enterprise Linux. To summarize, Red Hat discourages the use of static linking in applications for Red Hat Enterprise Linux.

Comparison of static and dynamic linking

Static linking makes libraries part of the resulting executable file. Dynamic linking keeps these libraries as separate files.

Dynamic and static linking can be compared in a number of ways:

As a result of the listed disadvantages, static linking should be avoided at all costs, particularly for whole applications and the glibc and libstdc++ libraries.

Reasons for static linking

Static linking might be a reasonable choice in some cases, such as:

Additional Resources

A library is a package of code which can be reused in your program. A C or C++ library consists of two parts:

Compiling Code That Uses a Library

The header files describe the interface of the library: The functions and variables available in the library. Information from the header files is needed for compiling the code.

Typically, header files of a library will be placed in a different directory than your application’s code. To tell GCC where the header files are, use the -I option:

$ gcc ... -Iinclude_path ...

Replace include_path with the actual path to the header file directory.

The -I option can be used multiple times to add multiple directories with header files. When looking for a header file, these directories are searched in the order of their appearance in the -I options.

Linking Code That Uses a Library

When linking an executable file, both the object code of your application and the binary code of the library must be available. The code for static and dynamic libraries is present in different forms:

To tell GCC where the archives or shared object files of a library are, use the -L option:

$ gcc ... -Llibrary_path -lfoo ...

Replace library_path with the actual path to the library directory.

The -L option can be used multiple times to add multiple directories. When looking for a library, these directories are searched in the order of their -L options.

The order of options matters: GCC cannot link against a library foo unless it knows the directory of this library. Therefore, use the -L options to specify library directories before using the -l options for linking against libraries.

Compiling and Linking Code Which Uses a Library in One Step

When the situation allows the code to be compiled and linked in one gcc command, use the options for both situations mentioned above at once.

Additional Resources

Static libraries are available as archives containing object files. After linking, they become part of the resulting executable file.

Prerequisites

Procedure

To link a program from source and object files, add a statically linked library foo, which is named libfoo.a:

Dynamic libraries are available as standalone executable files, required at both linking time and run time. They stay independent of your application’s executable file.

Prerequisites

Linking a Program Against a Dynamic Library

To link a program against a dynamic library foo:

$ gcc ... -Llibrary_path -lfoo ...

When a program is linked against a dynamic library, the resulting program must always load the library at run time. There are two options for locating the library:

Using an rpath Value Stored in the Executable File

The rpath is a special value saved as a part of an executable file when it is being linked. Later, when the program is loaded from its executable file, the runtime linker will use the rpath value to locate the library files.

While linking with GCC, to store the path library_path as an rpath:

$ gcc ... -Llibrary_path -lfoo -Wl,-rpath=library_path ...

The path library_path must point to a directory containing the file libfoo.so.

To run the program later, execute:

$ ./program

Using the LD_LIBRARY_PATH Environment Variable

If no rpath is found in the program’s executable file, the runtime linker will use the LD_LIBRARY_PATH environment variable. The value of this variable must be changed for each program according to the path where the shared library objects are located.

To run the program without rpath set, with libraries present in the library_path, execute:

$ export LD_LIBRARY_PATH=library_path:$LD_LIBRARY_PATH
$ ./program

Leaving out the rpath value offers flexibility, but requires setting the LD_LIBRARY_PATH variable every time the program is to run.

Placing the Library into the Default Directories

The runtime linker configuration specifies a number of directories as a default location of dynamic library files. To use this default behaviour, copy your library to the appropriate directory.

A full description of the dynamic linker behavior is out of scope for this document. For more information, see the following resources:

Sometimes it is required to link some libraries statically and some dynamically.

Prerequisites

Introduction

gcc recognizes both dynamic and static libraries. When the -lfoo option is encountered, gcc will first attempt to locate a shared object (a .so file) containing a dynamically linked version of the foo library, and then look for the archive file (.a) containing a static version of the library. Thus, the following situations can result from this search:

Because of these rules, the best way to select the static or dynamic version of a library for linking is having only that version found by gcc. This can be controlled to some extent by using or leaving out directories containing the library versions when specifying the -Lpath options.

Additionally, because dynamic linking is the default, the only situation where linking must be explicitly specified is when a library with both versions present should be linked statically. There are two possible solutions:

Specifying the static libraries by file

Usually, gcc is instructed to link against a library foo with the -lfoo option. However, it is possible to specify the full path to the file libfoo.a containing the library instead:

$ gcc ... path/to/libfoo.a ...

From the file extension .a, gcc will understand that this is a library to link with the program. However, specifying the full path to the library file is a less flexible method.

Using the -Wl option

The gcc option -Wl is a special option for passing options to the underlying linker. Syntax of this option differs from the other gcc options. The -Wl option is followed by a comma-separated list of linker options, while other gcc options require a space-separated list of options. The ld linker used by gcc offers the options -Bstatic and -Bdynamic to specify whether libraries following this option should be linked statically or dynamically, respectively. After passing -Bstatic and a library to the linker, the default dynamic linking behaviour must be restored manually for the following libraries to be linked dynamically with the -Bdynamic option.

To link a program, linking a library first statically (libfirst.a) and second dynamically (libsecond.so), run:

$ gcc ... -Wl,-Bstatic -lfirst -Wl,-Bdynamic -lsecond ...

Additional Resources