Next: , Previous: Using Library Projects, Up: Library Projects

11.5.3 Stand-alone Library Projects

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 & redeployment of complex systems when localized changes are made.

The most prominent 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:
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.