Next: Installing a library with project files, Previous: Using Library Projects, Up: Library Projects [Contents][Index]
A stand-alone library is a library that contains the necessary code to elaborate the Ada units that are included in the library. A stand-alone library is a convenient way to add an Ada subsystem to a more global system whose main is not in Ada since it makes the elaboration of the Ada part mostly transparent. However, stand-alone libraries are also useful when the main is in Ada: they provide a means for minimizing relinking & redeployement of complex systems when localized changes are made.
The most proeminent characteristic of a stand-alone library is that it offers a
distinction between interface units and implementation units. Only the former
are visible to units outside the library. A stand-alone library project is thus
characterised by a third attribute, Library_Interface, in addition to the
two attributes that make a project a Library Project (Library_Name
and
Library_Dir
).
This attribute defines an explicit subset of the units of the project.
Projects importing this library project may only "with" units whose sources
are listed in the Library_Interface
. Other sources are considered
implementation units.
for Library_Dir use "lib"; for Library_Name use "loggin"; for Library_Interface use ("lib1", "lib2"); -- unit names
In order to include the elaboration code in the stand-alone library, the binder
is invoked on the closure of the library units creating a package whose name
depends on the library name (b~logging.ads/b in the example).
This binder-generated package includes initialization and finalization
procedures whose names depend on the library name (logginginit
and
loggingfinal
in the example). The object corresponding to this package is
included in the library.
A dynamic stand-alone Library is automatically initialized if automatic initialization of Stand-alone Libraries is supported on the platform and if attribute Library_Auto_Init is not specified or is specified with the value "true". A static Stand-alone Library is never automatically initialized. Specifying "false" for this attribute prevent automatic initialization.
When a non-automatically initialized stand-alone library is used in an executable, its initialization procedure must be called before any service of the library is used. When the main subprogram is in Ada, it may mean that the initialization procedure has to be called during elaboration of another package.
For a stand-alone library, only the ALI files of the interface units
(those that are listed in attribute Library_Interface
) are copied to
the library directory. As a consequence, only the interface units may be
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
When a stand-alone library is bound, the switches that are specified in
the attribute Binder.Default_Switches ("Ada") are
used in the call to gnatbind
.
This attribute defines the location (absolute or relative to the project
directory) where the sources of the interface units are copied at
installation time.
These sources includes the specs of the interface units along with the closure
of sources necessary to compile them successfully. That may include bodies and
subunits, when pragmas Inline
are used, or when there is a generic
units in the spec. This directory cannot point to the object directory or
one of the source directories, but it can point to the library directory,
which is the default value for this attribute.
This attribute controls the export of symbols and, on some platforms (like VMS) that have the notions of major and minor IDs built in the library files, it controls the setting of these IDs. It is not supported on all platforms (where it will just have no effect). It may have one of the following values:
"autonomous"
or "default"
: exported symbols are not controlled
"compliant"
: if attribute Library_Reference_Symbol_File
is not defined, then it is equivalent to policy "autonomous". If there
are exported symbols in the reference symbol file that are not in the
object files of the interfaces, the major ID of the library is increased.
If there are symbols in the object files of the interfaces that are not
in the reference symbol file, these symbols are put at the end of the list
in the newly created symbol file and the minor ID is increased.
"controlled"
: the attribute Library_Reference_Symbol_File must be
defined. The library will fail to build if the exported symbols in the
object files of the interfaces do not match exactly the symbol in the
symbol file.
"restricted"
: The attribute Library_Symbol_File must be defined.
The library will fail to build if there are symbols in the symbol file that
are not in the exported symbols of the object files of the interfaces.
Additional symbols in the object files are not added to the symbol file.
"direct"
: The attribute Library_Symbol_File must be defined and
must designate an existing file in the object directory. This symbol file
is passed directly to the underlying linker without any symbol processing.
This attribute may define the path name of a reference symbol file that is read when the symbol policy is either "compliant" or "controlled", on platforms that support symbol control, such as VMS, when building a stand-alone library. The path may be an absolute path or a path relative to the project directory.
This attribute may define the name of the symbol file to be created when building a stand-alone library when the symbol policy is either "compliant", "controlled" or "restricted", on platforms that support symbol control, such as VMS. When symbol policy is "direct", then a file with this name must exist in the object directory.