Chapter 3. Using Libraries with GCC
This chapter describes using libraries in code.
3.1. Library naming conventions
A special file name convention is used for libraries: a library known as foo is expected to exist as file
libfoo.a. This convention is automatically understood by the linking input options of GCC, but not by the output options:
When linking against the library, the library can be specified only by its name foo with the
$ gcc ... -lfoo ...
When creating the library, the full file name
libfoo.amust be specified.
3.3. Using a library with GCC
A library is a package of code which can be reused in your program. A C or C++ library consists of two parts:
- The library code
- Header files
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
$ gcc ... -Iinclude_path ...
Replace include_path with the actual path to the header file directory.
-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
Linking code that uses a library
When linking the 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:
Static libraries are available as archive files. They contain a group of object files. The archive file has a file name extension
Dynamic libraries are available as shared objects. They are a form of an executable file. A shared object has a file name extension
To tell GCC where the archives or shared object files of a library are, use the
$ gcc ... -Llibrary_path -lfoo ...
Replace library_path with the actual path to the library directory.
-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
The order of options matters: GCC cannot link against a library foo unless it knows the directory with 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.
3.4. Using a static library with GCC
Static libraries are available as archives containing object files. After linking, they become part of the resulting executable file.
Red Hat discourages use of static linking for security reasons. See Section 3.2, “Static and dynamic linking”. Use static linking only when necessary, especially against libraries provided by Red Hat.
- GCC must be installed on your system.
- You must understand static and dynamic linking.
- You have a set of source or object files forming a valid program, requiring some static library foo and no other libraries.
The foo library is available as a file
libfoo.a, and no file
libfoo.sois provided for dynamic linking.
Most libraries which are part of Red Hat Enterprise Linux are supported for dynamic linking only. The steps below only work for libraries which are not enabled for dynamic linking. See Section 3.2, “Static and dynamic linking”.
To link a program from source and object files, adding a statically linked library foo, which is to be found as a file
- Change to the directory containing your code.
Compile the program source files with headers of the foo library:
$ gcc ... -Iheader_path -c ...
Replace header_path with a path to a directory containing the header files for the foo library.
Link the program with the foo library:
$ gcc ... -Llibrary_path -lfoo ...
Replace library_path with a path to a directory containing the file
To run the program later, simply:
-static GCC option related to static linking forbids all dynamic linking. Instead, use the
-Wl,-Bdynamic options to control linker behavior more precisely. See Section 3.6, “Using both static and dynamic libraries with GCC”.
3.5. Using a dynamic library with GCC
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.
- GCC must be installed on the system.
- A set of source or object files forming a valid program, requiring some dynamic library foo and no other libraries.
- The foo library must be available as a file libfoo.so.
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:
rpathvalue stored in the executable file itself
LD_LIBRARY_PATHvariable at run time
rpath Value Stored in the Executable File
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
$ gcc ... -Llibrary_path -lfoo -Wl,-rpath=library_path ...
The path library_path must point to a directory containing the file libfoo.so.
There is no space after the comma in the
To run the program later:
Using the LD_LIBRARY_PATH environment variable
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. This value should represent the path where the shared library objects are located.
To run the program without
rpath set, with libraries present in path library_path:
$ 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 of this document. For more information, see the following resources:
Linux manual pages for the dynamic linker:
$ man ld.so
Contents of the
$ cat /etc/ld.so.conf
Report of the libraries recognized by the dynamic linker without additional configuration, which includes the directories:
$ ldconfig -v
3.6. Using both static and dynamic libraries with GCC
Sometimes it is required to link some libraries statically and some dynamically. This situation brings some challenges.
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:
- Only the shared object is found, and gcc links against it dynamically.
- Only the archive is found, and gcc links against it statically.
- Both the shared object and archive are found, and by default, gcc selects dynamic linking against the shared object.
- Neither shared object nor archive is found, and linking fails.
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
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 resolutions:
Specifying the static libraries by file path instead of the
-Wloption to pass options to the linker
Specifying the static libraries by file
Usually, gcc is instructed to link against the foo library with the
-lfoo option. However, it is possible to specify the full path to 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.
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 space-separated list of options.
The ld linker used by gcc offers the options
-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
To link a program, link library first statically (
libfirst.a) and second dynamically (
$ gcc ... -Wl,-Bstatic -lfirst -Wl,-Bdynamic -lsecond ...
gcc can be configured to use linkers other than the default ld.