Short Course on Linux Libraries

(This is a draft document. If you have corrections or additions please contact jrvz at comcast dot net.)

Static Libraries

What they are, why they're useful.

An archive is a single file holding a collection of other files in a structure that makes it possible to retrieve the original individual files (called members of the archive). A static library is an archive whose members are object files. A library makes it possible for a program to use common routines without the administrative overhead of maintaining their source code, or the processing overhead of compiling them each time the program is compiled.

How they're named, version numbers, symbolic links.

Static libraries have names like libfoo.a, with no version numbers. There are normally no symbolic links associated with a static library.

Debugging symbols.

Where they're installed.

Static libraries are installed in /usr/lib or /usr/local/lib, not in /lib. They are used only during compilation. They are not critical to the operation of the system, so need not be on the root filesystem.

How ld finds them.

ld looks for the C library libc automatically. Otherwise, the option -lfoo will cause it to search its path-list for the library libfoo.a. ld looks for libraries in standard directories, plus those specified by -Ldir options on its command line.

What nm can tell you.

nm can list the symbols defined in a library. For example, "$ nm --print-file-name /usr/lib/*.a|grep cbrt" will show that the symbols containing the string "cbrt" are in libm.a (the math library).

Example commands to build a static library.

ar rs libfoo.a foo1.o foo2.o

Example commands to compile and link using a local static library.

gcc -I. -o jvct jvct.c libjvc.a

Example commands to install a static library.

install -m 644 libjvc.a /usr/lib

Example commands to compile and link using an installed static library.

gcc --static -I. -o jvct jvct.c -ljvc

Shared Libraries.

What they are, why they're useful.

Each program using routines from a static library has a copy of them in the executable file. This wastes disk space and (if more than one such program is in use at the same time) RAM as well. Also, when a static library is updated, all the programs using it must be recompiled in order to take advantage of the new code. When a program uses a shared library instead, the program binary does not include a copy of the code, but only a reference to the library. The run time loader, ld.so, finds the library and loads it into memory at the same time as the program.

How they're named, version numbers, symbolic links.

The run time loader finds the library by its "soname" which includes only the major version number (for example, "libfoo.so.1"). Therefore, a new version of the library can be installed, and existing programs will use it automatically. Of course, it is critical to change the major version number if calling sequences change in an incompatible way. Several libraries with different major version numbers can be installed at once, and in fact need to be, until all programs using the library have been recompiled. ldconfig creates a symbolic link with the soname pointing to the current version of the shared library. There should also be a symbolic link with no version number (for example, "libfoo.so") which is used at compile time to find the current version.

libfoo.sa: what "exported initialized library data" means.

What flags to compile with.

Debugging symbols.

Where they're installed.

The shared library ("libfoo.so.1.0.1") and the symbolic link with only the major version number ("libfoo.so.1") should be in /lib if the library is required by any program in /bin or /sbin. The link with no version number ("libfoo.so") is used only at compile time. It should be in /usr/lib.

How ld, ldconfig, ldd, and ld.so find them, and /etc/ld.so.conf.

At compile time, ld searches for shared libraries in standard directories and in directories added with -rpath dir and -Ldir command line options. During system boot, or when run manually (after updating libraries), ldconfig searches in standard places plus directories specified in /etc/ld.so.conf, and saves references to the libraries it finds in a cache. ld.so (at program run time) and ldd (as requested) look in directories specified by the -rpath option given at compile time, or in the cache built by ldconfig.

What "ldconfig -p", "ldconfig -D", nm and ldd can tell you.

"ldconfig -p" will display the contents of the cache. "ldconfig -D" will search for shared libraries and display them. "nm --dynamic /usr/lib/libfoo.so.X" will display the symbols defined by the library. "ldd foo" will display the shared libraries required by foo, and where they were found.

Example commands to build a shared library.

	gcc -shared -Wl,-soname,libjvc.so.1 -o libjvc.so.1.0.1 jvc.o
	ln -sf libjvc.so.1.0.1 libjvc.so.1.0
	ln -sf libjvc.so.1.0 libjvc.so.1
	ln -sf libjvc.so.1 libjvc.so

Example commands to compile and link using a local shared library.

	gcc -I. -o jvct jvct.c -ljvc -L. -Wl,-rpath,`pwd`

[To alter the search path for shared libraries without using -rpath, the ld man page suggests setting LD_RUN_PATH, and the ld.so man page says you set LD_AOUT_LIBRARY_PATH, but I could not get either one to work.]

Example commands to install a shared library.

	cp libjvc.so.1.0.1 /lib
	(cd /usr/lib; ln -sf ../../libjvc.so.1.0.1 libjvc.so)
	ldconfig

Example commands to compile and link using an installed shared library.

	gcc -I. -o jvct jvct.c -ljvc

History: how much more difficult a.out shared libraries were to work with.

Pitfalls.

Multiple versions with same name (version scripts?).

The libc5/libc6 problem.

Debian Packaging Policy Commentary (The Reasons Behind The Policy).

The policy for packaging libraries is given in /usr/doc/dpkg/packaging.html.

What goes where: static, shared, headers, executables, man pages.

The shared library should go into a package by itself ("libfoo") in section "libs" or "base". A user needing to run but not compile programs need only install that package. Several versions may need to be installed at the same time, to support programs compiled at different times. (This is why the package name may include the major version number.) The symbolic link without the version number, the static library, header files, and documentation go into a second package ("libfoo-dev") in section "devel". Man pages should be installed in section 3 of the manual (/usr/man/man3). These are used by developers. Executables should go into a third package.

Stripping.

Threads.

Installing multiple versions with same name.

Handling the libc5/libc6 problem.

Example debian/rules commands to build and install.

Upgrade strategies.

home

Last modified: 2003-11-13