19.2.2 Installing a library

If you use project files, library installation is part of the library build process. Thus no further action is needed in order to make use of the libraries that are built as part of the general application build. A usable version of the library is installed in the directory specified by the Library_Dir attribute of the library project file.

You may want to install a library in a context different from where the library is built. This situation arises with third party suppliers, who may want to distribute a library in binary form where the user is not expected to be able to recompile the library. The simplest option in this case is to provide a project file slightly different from the one used to build the library, by using the externally_built attribute. For instance, the project file used to build the library in the previous section can be changed into the following one when the library is installed:

     project My_Lib is
        for Source_Dirs use ("src1", "src2");
        for Library_Name use "mylib";
        for Library_Dir use "lib";
        for Library_Kind use "dynamic";
        for Externally_Built use "true";
     end My_lib;

This project file assumes that the directories src1, src2, and lib exist in the directory containing the project file. The externally_built attribute makes it clear to the GNAT builder that it should not attempt to recompile any of the units from this library. It allows the library provider to restrict the source set to the minimum necessary for clients to make use of the library as described in the first section of this chapter. It is the responsibility of the library provider to install the necessary sources, ALI files and libraries in the directories mentioned in the project file. For convenience, the user's library project file should be installed in a location that will be searched automatically by the GNAT builder. These are the directories referenced in the ADA_LIBRARY_PATH environment variable (see Importing Projects), and also the default GNAT library location that can be queried with gnatls -v and is usually of the form $gnat_install_root/lib/gnat.

When project files are not an option, it is also possible, but not recommended, to install the library so that the sources needed to use the library are on the Ada source path and the ALI files & libraries be on the Ada Object path (see Search Paths and the Run-Time Library (RTL). Alternatively, the system administrator can place general-purpose libraries in the default compiler paths, by specifying the libraries' location in the configuration files ada_source_path and ada_object_path. These configuration files must be located in the GNAT installation tree at the same place as the gcc spec file. The location of the gcc spec file can be determined as follows:

     $ gcc -v

The configuration files mentioned above have a simple format: each line must contain one unique directory name. Those names are added to the corresponding path in their order of appearance in the file. The names can be either absolute or relative; in the latter case, they are relative to where theses files are located.

The files ada_source_path and ada_object_path might not be present in a GNAT installation, in which case, GNAT will look for its run-time library in the directories adainclude (for the sources) and adalib (for the objects and ALI files). When the files exist, the compiler does not look in adainclude and adalib, and thus the ada_source_path file must contain the location for the GNAT run-time sources (which can simply be adainclude). In the same way, the ada_object_path file must contain the location for the GNAT run-time objects (which can simply be adalib).

You can also specify a new default path to the run-time library at compilation time with the switch --RTS=rts-path. You can thus choose / change the run-time library you want your program to be compiled with. This switch is recognized by gcc, gnatmake, gnatbind, gnatls, gnatfind and gnatxref.

It is possible to install a library before or after the standard GNAT library, by reordering the lines in the configuration files. In general, a library must be installed before the GNAT library if it redefines any part of it.