Next: Stand-alone Library Projects, Previous: Naming Schemes, Up: GNAT Project Manager
Library projects are projects whose object code is placed in a library. (Note that this facility is not yet supported on all platforms)
To create a library project, you need to define in its project file
two project-level attributes: Library_Name
and Library_Dir
.
Additionally, you may define other library-related attributes such as
Library_Kind
, Library_Version
, Library_Interface
,
Library_Auto_Init
, Library_Options
and Library_GCC
.
The Library_Name
attribute has a string value. There is no restriction
on the name of a library. It is the responsibility of the developer to
choose a name that will be accepted by the platform. It is recommended to
choose names that could be Ada identifiers; such names are almost guaranteed
to be acceptable on all platforms.
The Library_Dir
attribute has a string value that designates the path
(absolute or relative) of the directory where the library will reside.
It must designate an existing directory, and this directory must be writable,
different from the project's object directory and from any source directory
in the project tree.
If both Library_Name
and Library_Dir
are specified and
are legal, then the project file defines a library project. The optional
library-related attributes are checked only for such project files.
The Library_Kind
attribute has a string value that must be one of the
following (case insensitive): "static"
, "dynamic"
or
"relocatable"
(which is a synonym for "dynamic"
). If this
attribute is not specified, the library is a static library, that is
an archive of object files that can be potentially linked into a
static executable. Otherwise, the library may be dynamic or
relocatable, that is a library that is loaded only at the start of execution.
If you need to build both a static and a dynamic library, you should use two different object directories, since in some cases some extra code needs to be generated for the latter. For such cases, it is recommended to either use two different project files, or a single one which uses external variables to indicate what kind of library should be build.
The Library_ALI_Dir
attribute may be specified to indicate the
directory where the ALI files of the library will be copied. When it is
not specified, the ALI files are copied to the directory specified in
attribute Library_Dir
. The directory specified by Library_ALI_Dir
must be writable and different from the project's object directory and from
any source directory in the project tree.
The Library_Version
attribute has a string value whose interpretation
is platform dependent. It has no effect on VMS and Windows. On Unix, it is
used only for dynamic/relocatable libraries as the internal name of the
library (the "soname"
). If the library file name (built from the
Library_Name
) is different from the Library_Version
, then the
library file will be a symbolic link to the actual file whose name will be
Library_Version
.
Example (on Unix):
project Plib is Version := "1"; for Library_Dir use "lib_dir"; for Library_Name use "dummy"; for Library_Kind use "relocatable"; for Library_Version use "libdummy.so." & Version; end Plib;
Directory lib_dir will contain the internal library file whose name will be libdummy.so.1, and libdummy.so will be a symbolic link to libdummy.so.1.
When gnatmake detects that a project file is a library project file, it will check all immediate sources of the project and rebuild the library if any of the sources have been recompiled.
Standard project files can import library project files. In such cases, the libraries will only be rebuilt if some of its sources are recompiled because they are in the closure of some other source in an importing project. Sources of the library project files that are not in such a closure will not be checked, unless the full library is checked, because one of its sources needs to be recompiled.
For instance, assume the project file A
imports the library project file
L
. The immediate sources of A are a1.adb, a2.ads and
a2.adb. The immediate sources of L are l1.ads, l1.adb,
l2.ads, l2.adb.
If l1.adb has been modified, then the library associated with L
will be rebuilt when compiling all the immediate sources of A
only
if a1.ads, a2.ads or a2.adb includes a statement
"with L1;"
.
To be sure that all the sources in the library associated with L
are
up to date, and that all the sources of project A
are also up to date,
the following two commands needs to be used:
gnatmake -Pl.gpr gnatmake -Pa.gpr
When a library is built or rebuilt, an attempt is made first to delete all files in the library directory. All ALI files will also be copied from the object directory to the library directory. To build executables, gnatmake will use the library rather than the individual object files.
It is also possible to create library project files for third-party libraries
that are precompiled and cannot be compiled locally thanks to the
externally_built
attribute. (See Installing a library).