C++ User's Guide |
Building Libraries
This chapter explains how to build your own libraries.
6.1 Understanding Libraries
Libraries provide two benefits. First, they provide a way to share code among several applications. If you have such code, you can create a library with it and link the library with any application that needs it. Second, libraries provide a way to reduce the complexity of very large applications. Such applications can build and maintain relatively independent portions as libraries and so reduce the burden on programmers working on other portions.
Building a library simply means creating
.o
files (by compiling your code with the-c
option) and combining the.o
files into a library using theCC
command. You can build two kinds of libraries, static (archive) libraries and dynamic (shared) libraries.With static (archive) libraries, objects within the library are linked into the program's executable file at link time. Only those
.o
files from the library that are needed by the application are linked into the executable. The name of a static (archive) library generally ends with a.a
suffix.With dynamic (shared) libraries, objects within the library are not linked into the program's executable file, but rather the linker notes in the executable that the program depends on the library. When the program is executed, the system loads the dynamic libraries that the program requires. If two programs that use the same dynamic library execute at the same time, the operating system shares the library among the programs. The name of a dynamic (shared) library ends with a
.so
suffix.Linking dynamically with shared libraries has several advantages over linking statically with archive libraries:
- The size of the executable is smaller.
- Significant portions of code can be shared among programs at runtime, reducing the amount of memory use.
- The library can be replaced at runtime without relinking with the application. (This is the primary mechanism that enables programs to take advantage of many improvements in the Solaris environment without requiring relinking and redistribution of programs.)
- The shared library can be loaded at runtime, using the
dlopen()
function call.However, dynamic libraries have some disadvantages:
- Runtime linking has an execution-time cost.
- Distributing a program that uses dynamic libraries might require simultaneous distribution of the libraries it uses.
- Moving a shared library to a different location can prevent the system from finding the library and executing the program. (The environment variable
LD_LIBRARY_PATH
helps overcome this problem.)6.2 Building Static (Archive) Libraries
The mechanism for building static (archive) libraries is similar to that of building an executable. A collection of object (
.o
) files can be combined into a single library using the-xar
option ofCC
.You should build static (archive) libraries using
CC
-xar
instead of using thear
command directly. The C++ language generally requires that the compiler maintain more information than can be accommodated with traditional.o
files, particularly template instances. The-xar
option ensures that all necessary information, including template instances, is included in the library. You might not be able to accomplish this in a normal programming environment sincemake
might not know which template files are actually created and referenced. WithoutCC
-xar
, referenced template instances might not be included in the library, as required. For example:
%CC -c foo.cc
# Compile main file, templates objects are created.%CC -xar -o foo.a foo.o
# Gather all objects into a library.The
-xar
flag causesCC
to create a static (archive) library. The-o
directive is required to name the newly created library. The compiler examines the object files on the command line, cross-references the object files with those known to the template repository, and adds those templates required by the user's object files (along with the main object files themselves) to the archive.
Note Use the-xar
flag for creating or updating an existing archive only. Do not use it to maintain an archive. The-xar
option is equivalent toar
-cr
.
It is a good idea to have only one function in each
.o
file. If you are linking with an archive, an entire.o
file from the archive is linked into your application when a symbol is needed from that particular.o
file. Having one function in each.o
file ensures that only those symbols needed by the application will be linked from the archive.6.3 Building Dynamic (Shared) Libraries
Dynamic (shared) libraries are built the same way as static (archive) libraries, except that you use
-G
instead of-xar
on the command line.You should not use
ld
directly. As with static libraries, theCC
command ensures that all the necessary template instances from the template repository are included in the library if you are using templates. Furthermore, the C++ compiler does not initialize global variables if they are defined in a dynamic library, unless the library is built correctly. All static constructors in a dynamic library that is linked to an application are called beforemain()
is executed and all static destructors are called aftermain()
exits. If a shared library is opened usingdlopen()
, all static constructors are executed atdlopen()
and all static destructors are executed atdlclose()
. Finally, exceptions might not work, unless you use theCC -G
command to build the dynamic library.To build a dynamic (shared) library, you must create relocatable object files by compiling each object with the
-Kpic
or-KPIC
option ofCC
. You can then build a dynamic library with these relocatable object files. If you get any bizarre link failures, you might have forgotten to compile some objects with-Kpic
or-KPIC
.To build a C++ dynamic library named
libfoo.so
that contains objects from source fileslsrc1.cc
andlsrc2.cc,
type:
%CC -G -o libfoo.so -h libfoo.so -Kpic lsrc1.cc lsrc2.cc
The
-G
option specifies the construction of a dynamic library. The-o
option specifies the file name for the library. The-h
option specifies a name for the shared library. The-Kpic
option specifies that the object files are to be position-independent.
Note TheCC
-G
command does not pass any-l
options told
. If you want the shared library to have a dependency on another shared library, you must pass the necessary-l
option on the command line. For example, if you want the shared library to be dependent uponlibCrun.so
, you must pass-lCrun
on the command line.
6.4 Building Shared Libraries That Contain Exceptions
When shared libraries are opened using
dlopen(),
you must useRTLD_GLOBAL
for exceptions to work.
Note When building shared libraries that contain exceptions, do not pass the option-Bsymbolic
told
. Exceptions that should be caught might be missed.
6.5 Building Libraries for Private Use
When an organization builds a library for internal use only, the library can be built with options that are not advised for more general use. In particular, the library need not comply with the system's application binary interface (ABI). For example, the library can be compiled with the
-fast
option to improve its performance on a known architecture. Likewise, it can be compiled with the-xregs=float
option to improve performance.6.6 Building Libraries for Public Use
When an organization builds a library for use by other organizations, the management of the libraries, platform generality, and other issues become significant. A simple test for whether or not a library is public is to ask if the application programmer can recompile the library easily. Public libraries should be built in conformance with the system's application binary interface (ABI). In general, this means that any processor-specific options should be avoided. (For example, do not use
-fast
or-xtarget
.)The SPARC ABI reserves some registers exclusively for applications. For V7 and V8, these registers are
%g2
,%g3
, and%g4
. For V9, these registers are%g2
and%g3
. Since most compilations are for applications, the C++ compiler, by default, uses these registers for scratch registers, improving program performance. However, use of these registers in a public library is generally not compliant with the SPARC ABI. When building a library for public use, compile all objects with the-xregs=no%appl
option to ensure that the application registers are not used.6.7 Building a Library That Has a C API
If you want to build a library that is written in C++ but that can be used with a C program, you must create a C API (application programming interface). To do this, make all the exported functions extern "C". Note that this can be done only for global functions and not for member functions.
If you also want to remove any dependency on the C++ runtime libraries, you should enforce the following coding rules in your library sources:
- Do not use any form of
new
ordelete
unless you provide your own corresponding versions.- Do not use exceptions.
- Do not use runtime type information (RTTI).
6.8 Using
dlopen
to Access a C++ Library From a C ProgramIf you want to use
dlopen()
to open a C++ shared library from a C program, make sure that the shared library has a dependency on the appropriate C++ runtime (libC.so.5
for-compat=4,
orlibCrun.so.1
for-compat=5
).To do this, add
-lC
for-compat=4
or add -lCrun
for-compat=5
to the command line when building the shared library. For example:
example%CC -G -compat=4 ... -lC
example%CC -G -compat=5 ... -lCrun
If the shared library uses exceptions and does not have a dependency on the C++ runtime library, your C program might behave erratically.
Note When shared libraries are opened withdlopen()
,RTLD_GLOBAL
must be used for exceptions to work.
6.9 Building Multithreaded Libraries
For information about building multithreaded libraries, refer to the C++ Programming Guide.
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |