18. Minimizing Executables for Ada Programs Using gnatelim

18.1 About gnatelim
18.2 Eliminate pragma
18.3 Preparing Tree and Bind Files for gnatelim
18.4 Running gnatelim
18.5 Correcting the List of Eliminate Pragmas
18.6 Making your Executables smaller
18.7 Summary of the gnatelim Usage Cycle

18.1 About gnatelim

When a program shares a set of Ada packages with other programs, it may happen that this program uses only a fraction of the subprograms defined in these packages. The code created for those unused subprograms increases the size of the executable.

gnatelim is a utility tracking unused subprograms in an Ada program. Its output consists of a list of Eliminate pragmas marking all the subprograms that are declared, but never called in a given program. Eliminate is a GNAT-specific pragma, it is described in the next section. By placing the list of Eliminate pragmas in the GNAT configuration file `gnat.adc' and recompiling your program, you may decrease the size of its executable, because the compiler will not generate code for those unused subprograms.

gnatelim is an ASIS-based tool, and it needs as its input data a set of tree files representing all the components of a program to process. It also needs a bind file for a main subprogram. (See 18.3 Preparing Tree and Bind Files for gnatelim for full details)

18.2 Eliminate pragma

The syntax of Eliminate pragma is

pragma Eliminate (Library_Unit_Name, Subprogram_Name);

Library_Unit_Name

full expanded Ada name of a library unit

Subprogram_Name

a simple or expanded name of a subprogram declared within this compilation unit

The effect of an Eliminate pragma placed in the GNAT configuration file `gnat.adc' is:

• If the subprogram denoted by Subprogram_Name is declared within the library unit having Library_Unit_Name as its defining program unit name, then the compiler will not generate code for this subprogram. It applies to all overloaded subprograms denoted by Subprogram_Name.

• If a subprogram mentioned in some Eliminate pragma as unused is actually used (called) in a program, then the compiler will produce a diagnosis in place where it is called.

18.3 Preparing Tree and Bind Files for gnatelim

gnatelim can process only full Ada programs (partitions) and it needs a set of tree files representing the whole program (partition) to be presented in the current directory. It also needs a bind file for the main subprogram of the program (partition) to be presented in the current directory.

Let Main_Prog be the name of a main subprogram, and suppose this subprogram is in a file named `main_prog.ads' or `main_prog.adb'.

To create a minimal set of tree files covering the whole program, call gnatmake for this program as follows:

$ gnatmake -c -f -gnatc -gnatt Main_Prog

The -c gnatmake option turns off the bind and link phases, which are impossible anyway, because sources are compiled with -gnatc option, which turns off code generation.

the -f gnatmake option is used to force recompilation of all the needed sources.

To create a bind file for gnatelim, run gnatbind for the main subprogram. gnatelim can work with either an Ada or a C bind file, if both are present, it works with the Ada bind file. To avoid problems with creating a consistent data for gnatelim, it is advised to use the following procedure. It creates all the data needed by gnatelim from scratch and therefore guarantees their consistency:

1. creating a bind file:

   $ gnatmake -c Main_Prog $ gnatbind main_prog

2. creating a set of tree files:

   $ gnatmake -f -c -gnatc -gnatt Main_Prog

Note, that gnatelim needs neither object nor ALI files, so they can be deleted at this stage.

18.4 Running gnatelim

gnatelim has the following command-line interface:

$ gnatelim [options] name

name should be a full expanded Ada name of a main subprogram of a program (partition).

gnatelim options:

-v

Verbose mode: gnatelim version information is printed (in the form of Ada comments) to the standard output file. Various debugging information and information reflecting some details of the analysis doing by gnatelim are output to the standard error file.

-a

Will also indicate subprograms from the GNAT runtime that could be eliminated.

-m

Will check if tree files are missing for an accurate result.

gnatelim directs its output to the standard output, so to produce a proper GNAT configuration file `gnat.adc', redirection can be used:

$ gnatelim Main_Prog > gnat.adc

or

$ gnatelim Main_Prog >> gnat.adc

In order to append the gnatelim output to the existing contents of `gnat.adc'.

18.5 Correcting the List of Eliminate Pragmas

It may happen that gnatelim try to eliminate subprograms which cannot really be eliminated because they are actually called in the program although this only happens in very rare cases. In this case, the compiler will generate an error message of the form:

file.adb:106:07: cannot call eliminated subprogram "My_Prog"

You have to correct the `gnat.adc' file manually by suppressing the faulty Eliminate pragmas. It is advised to recompile your program from scratch after that, because you need a consistent `gnat.adc' file during the complete compilation in order to get an meaningful result.

18.6 Making your Executables smaller

To get a smaller executable for your program, you have to recompile the program completely, having the `gnat.adc' file with a set of Eliminate pragmas created by gnatelim in your current directory:

$ gnatmake -f Main_Prog

(you will need -f option for gnatmake to recompile everything with the set of pragmas Eliminate you have got from gnatelim).

Be aware that a set of Eliminate pragmas is specific to each program. Therefore, it is not advised to merge sets of Eliminate pragmas created for different programs in one `gnat.adc' file.

18.7 Summary of the gnatelim Usage Cycle

Here is a summary of the steps to be taken in order to reduce the size of your executables with gnatelim. You may use other GNAT options to control the optimization level, to produce the debugging information, to set search path, etc.

1. Produce a bind file and a set of tree files

   $ gnatmake -c Main_Prog $ gnatbind main_prog $ gnatmake -f -c -gnatc -gnatt Main_Prog

2. Generate a list of Eliminate pragmas

   $ gnatelim Main_Prog >[>] gnat.adc

3. Recompile the application

   $ gnatmake -f Main_Prog