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 name of a stand-alone library, specified with attribute Library_Name, must have the syntax of an Ada identifier.

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, usually Library_Interface, in addition to the two attributes that make a project a Library Project (Library_Name and Library_Dir). This third attribute may also be Interfaces. Library_Interface only works when the interface is in Ada and takes a list of units as parameter. Interfaces works for any supported language and takes a list of sources as parameter.

Library_Interface:

This attribute defines an explicit subset of the units of the project. Units from 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

Interfaces

This attribute defines an explicit subset of the source files of a project. Sources from projects importing this project, can only depend on sources from this subset. This attribute can be used on non library projects. It can also be used as a replacement for attribute Library_Interface, in which case, units have to be replaced by source files. For multi-language library projects, it is the only way to make the project a Stand-Alone Library project whose interface is not purely Ada.

Library_Standalone:

This attribute defines the kind of standalone library to build. Values are either standard (the default), no or encapsulated. When standard is used the code to elaborate and finalize the library is embedded, when encapsulated is used the library can furthermore only depends on static libraries (including the GNAT runtime). This attribute can be set to no to make it clear that the library should not be standalone in which case the Library_Interface should not defined. Note that this attribute only applies to shared libraries, so Library_Kind must be set to dynamic.

               for Library_Dir use "lib";
               for Library_Name use "loggin";
               for Library_Kind use "dynamic";
               for Library_Interface use ("lib1", "lib2");  --  unit names
               for Library_Standalone use "encapsulated";

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^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.

Library_Auto_Init:

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.

Library_Dir:

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.

Binder.Default_Switches:

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.

Library_Src_Dir:

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.

Library_Symbol_Policy:

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.

Library_Reference_Symbol_File

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.

Library_Symbol_File

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.