20.2.1 Building a library

The easiest way to build a library is to use the Project Manager, which supports a special type of project called a Library Project (see Library Projects).

A project is considered a library project, when two project-level attributes are defined in it: Library_Name and Library_Dir. In order to control different aspects of library configuration, additional optional project-level attributes can be specified:

Library_Kind

This attribute controls whether the library is to be static or dynamic

Library_Version

This attribute specifies the library version; this value is used during dynamic linking of shared libraries to determine if the currently installed versions of the binaries are compatible.

Library_Options

Library_GCC

These attributes specify additional low-level options to be used during library generation, and redefine the actual application used to generate library.

The GNAT Project Manager takes full care of the library maintenance task, including recompilation of the source files for which objects do not exist or are not up to date, assembly of the library archive, and installation of the library (i.e., copying associated source, object and ALI files to the specified location).

Here is a simple library project file:

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

and the compilation command to build and install the library:

       $ gnatmake -Pmy_lib

It is not entirely trivial to perform manually all the steps required to produce a library. We recommend that you use the GNAT Project Manager for this task. In special cases where this is not desired, the necessary steps are discussed below.

There are various possibilities for compiling the units that make up the library: for example with a Makefile (see Using the GNU make Utility) or with a conventional script. For simple libraries, it is also possible to create a dummy main program which depends upon all the packages that comprise the interface of the library. This dummy main program can then be given to gnatmake, which will ensure that all necessary objects are built.

After this task is accomplished, you should follow the standard procedure of the underlying operating system to produce the static or shared library.

Here is an example of such a dummy program:

     with My_Lib.Service1;
     with My_Lib.Service2;
     with My_Lib.Service3;
     procedure My_Lib_Dummy is
     begin
        null;
     end;

Here are the generic commands that will build an archive or a shared library.

     # compiling the library
     $ gnatmake -c my_lib_dummy.adb
     
     # we don't need the dummy object itself
     $ rm my_lib_dummy.o my_lib_dummy.ali
     
     # create an archive with the remaining objects
     $ ar rc libmy_lib.a *.o
     # some systems may require "ranlib" to be run as well
     
     # or create a shared library
     $ gcc -shared -o libmy_lib.so *.o
     # some systems may require the code to have been compiled with -fPIC
     
     # remove the object files that are now in the library
     $ rm *.o
     
     # Make the ALI files read-only so that gnatmake will not try to
     # regenerate the objects that are in the library
     $ chmod -w *.ali

Please note that the library must have a name of the form libxxx.a or libxxx.so (or libxxx.dll on Windows) in order to be accessed by the directive -lxxx at link time.