6. The GNAT Make Program gnatmake

6.1 Running gnatmake
6.2 Switches for gnatmake
6.3 Mode Switches for gnatmake
6.4 Notes on the Command Line
6.5 How gnatmake Works
6.6 Examples of gnatmake Usage

1. Edit some sources to fix bugs.

2. Add enhancements.

3. Compile all sources affected.

4. Rebind and relink.

5. Test.

The third step can be tricky, because not only do the modified files have to be compiled, but any files depending on these files must also be recompiled. The dependency rules in Ada can be quite complex, especially in the presence of overloading, use clauses, generics and inlined subprograms.

gnatmake automatically takes care of the third and fourth steps of this process. It determines which sources need to be compiled, compiles them, and binds and links the resulting object files.

Unlike some other Ada make programs, the dependencies are always accurately recomputed from the new sources. The source based approach of the GNAT compilation model makes this possible. This means that if changes to the source program cause corresponding changes in dependencies, they will always be tracked exactly correctly by gnatmake.

6.1 Running gnatmake

The usual form of the gnatmake command is

$ gnatmake [switches] file_name [file_names] [mode_switches]

The only required argument is one file_name, which specifies a compilation unit that is a main program. Several file_names can be specified: this will result in several executables being built. If switches are present, they can be placed before the first file_name, between file_names or after the last file_name. If mode_switches are present, they must always be placed after the last file_name and all switches.

If you are using standard file extensions (`.adb' and `.ads'), then the extension may be omitted from the file_name arguments. However, if you are using non-standard extensions, then it is required that the extension be given. A relative or absolute directory path can be specified in a file_name, in which case, the input source file will be searched for in the specified directory only. Otherwise, the input source file will first be searched in the directory where gnatmake was invoked and if it is not found, it will be search on the source path of the compiler as described in 3.3 Search Paths and the Run-Time Library (RTL).

All gnatmake output (except when you specify `-M') is to `stderr'. The output produced by the `-M' switch is send to `stdout'.

6.2 Switches for gnatmake

You may specify any of the following switches to gnatmake:

`--version'

Display Copyright and version, then exit disregarding all other options.

`--help'

If `--version' was not used, display usage, then exit disregarding all other options.

`--GCC=compiler_name'

Program used for compiling. The default is `gcc'. You need to use quotes around compiler_name if compiler_name contains spaces or other separator characters. As an example `--GCC="foo -x -y"' will instruct gnatmake to use foo -x -y as your compiler. A limitation of this syntax is that the name and path name of the executable itself must not include any embedded spaces. Note that switch `-c' is always inserted after your command name. Thus in the above example the compiler command that will be used by gnatmake will be foo -c -x -y. If several `--GCC=compiler_name' are used, only the last compiler_name is taken into account. However, all the additional switches are also taken into account. Thus, `--GCC="foo -x -y" --GCC="bar -z -t"' is equivalent to `--GCC="bar -x -y -z -t"'.

`--GNATBIND=binder_name'

Program used for binding. The default is `gnatbind'. You need to use quotes around binder_name if binder_name contains spaces or other separator characters. As an example `--GNATBIND="bar -x -y"' will instruct gnatmake to use bar -x -y as your binder. Binder switches that are normally appended by gnatmake to `gnatbind' are now appended to the end of bar -x -y. A limitation of this syntax is that the name and path name of the executable itself must not include any embedded spaces.

`--GNATLINK=linker_name'

Program used for linking. The default is `gnatlink'. You need to use quotes around linker_name if linker_name contains spaces or other separator characters. As an example `--GNATLINK="lan -x -y"' will instruct gnatmake to use lan -x -y as your linker. Linker switches that are normally appended by gnatmake to `gnatlink' are now appended to the end of lan -x -y. A limitation of this syntax is that the name and path name of the executable itself must not include any embedded spaces.

`--subdirs=subdir'

Actual object directory of each project file is the subdirectory subdir of the object directory specified or defaulted in the project file.

`--single-compile-per-obj-dir'

Disallow simultaneous compilations in the same object directory when project files are used.

`--unchecked-shared-lib-imports'

By default, shared library projects are not allowed to import static library projects. When this switch is used on the command line, this restriction is relaxed.

`--source-info=<source info file>'

Specify a source info file. This switch is active only when project files are used. If the source info file is specified as a relative path, then it is relative to the object directory of the main project. If the source info file does not exist, then after the Project Manager has successfully parsed and processed the project files and found the sources, it creates the source info file. If the source info file already exists and can be read successfully, then the Project Manager will get all the needed information about the sources from the source info file and will not look for them. This reduces the time to process the project files, especially when looking for sources that take a long time. If the source info file exists but cannot be parsed successfully, the Project Manager will attempt to recreate it. If the Project Manager fails to create the source info file, a message is issued, but gnatmake does not fail. gnatmake "trusts" the source info file. This means that if the source files have changed (addition, deletion, moving to a different source directory), then the source info file need to be deleted and recreated.

`--create-map-file'

When linking an executable, create a map file. The name of the map file has the same name as the executable with extension ".map".

`--create-map-file=mapfile'

When linking an executable, create a map file. The name of the map file is "mapfile".

`-a'

Consider all files in the make process, even the GNAT internal system files (for example, the predefined Ada library files), as well as any locked files. Locked files are files whose ALI file is write-protected. By default, gnatmake does not check these files, because the assumption is that the GNAT internal files are properly up to date, and also that any write protected ALI files have been properly installed. Note that if there is an installation problem, such that one of these files is not up to date, it will be properly caught by the binder. You may have to specify this switch if you are working on GNAT itself. The switch `-a' is also useful in conjunction with `-f' if you need to recompile an entire application, including run-time files, using special configuration pragmas, such as a Normalize_Scalars pragma.

By default gnatmake -a compiles all GNAT internal files with gcc -c -gnatpg rather than gcc -c.

`-b'

Bind only. Can be combined with `-c' to do compilation and binding, but no link. Can be combined with `-l' to do binding and linking. When not combined with `-c' all the units in the closure of the main program must have been previously compiled and must be up to date. The root unit specified by file_name may be given without extension, with the source extension or, if no GNAT Project File is specified, with the ALI file extension.

`-c'

Compile only. Do not perform binding, except when `-b' is also specified. Do not perform linking, except if both `-b' and `-l' are also specified. If the root unit specified by file_name is not a main unit, this is the default. Otherwise gnatmake will attempt binding and linking unless all objects are up to date and the executable is more recent than the objects.

`-C'

Use a temporary mapping file. A mapping file is a way to communicate to the compiler two mappings: from unit names to file names (without any directory information) and from file names to path names (with full directory information). A mapping file can make the compiler's file searches faster, especially if there are many source directories, or the sources are read over a slow network connection. If `-P' is used, a mapping file is always used, so `-C' is unnecessary; in this case the mapping file is initially populated based on the project file. If `-C' is used without `-P', the mapping file is initially empty. Each invocation of the compiler will add any newly accessed sources to the mapping file.

`-C=file'

Use a specific mapping file. The file, specified as a path name (absolute or relative) by this switch, should already exist, otherwise the switch is ineffective. The specified mapping file will be communicated to the compiler. This switch is not compatible with a project file (-Pfile) or with multiple compiling processes (-jnnn, when nnn is greater than 1).

`-d'

Display progress for each source, up to date or not, as a single line

completed x out of y (zz%)

If the file needs to be compiled this is displayed after the invocation of the compiler. These lines are displayed even in quiet output mode.

`-D dir'

Put all object files and ALI file in directory dir. If the `-D' switch is not used, all object files and ALI files go in the current working directory.

This switch cannot be used when using a project file.

`-eInnn'

Indicates that the main source is a multi-unit source and the rank of the unit in the source file is nnn. nnn needs to be a positive number and a valid index in the source. This switch cannot be used when gnatmake is invoked for several mains.

`-eL'

Follow all symbolic links when processing project files. This should be used if your project uses symbolic links for files or directories, but is not needed in other cases.

This also assumes that no directory matches the naming scheme for files (for instance that you do not have a directory called "sources.ads" when using the default GNAT naming scheme).

When you do not have to use this switch (i.e. by default), gnatmake is able to save a lot of system calls (several per source file and object file), which can result in a significant speed up to load and manipulate a project file, especially when using source files from a remote system.

`-eS'

Output the commands for the compiler, the binder and the linker on standard output, instead of standard error.

`-f'

Force recompilations. Recompile all sources, even though some object files may be up to date, but don't recompile predefined or GNAT internal files or locked files (files with a write-protected ALI file), unless the `-a' switch is also specified.

`-F'

When using project files, if some errors or warnings are detected during parsing and verbose mode is not in effect (no use of switch -v), then error lines start with the full path name of the project file, rather than its simple file name.

`-g'

Enable debugging. This switch is simply passed to the compiler and to the linker.

`-i'

In normal mode, gnatmake compiles all object files and ALI files into the current directory. If the `-i' switch is used, then instead object files and ALI files that already exist are overwritten in place. This means that once a large project is organized into separate directories in the desired manner, then gnatmake will automatically maintain and update this organization. If no ALI files are found on the Ada object path (3.3 Search Paths and the Run-Time Library (RTL)), the new object and ALI files are created in the directory containing the source being compiled. If another organization is desired, where objects and sources are kept in different directories, a useful technique is to create dummy ALI files in the desired directories. When detecting such a dummy file, gnatmake will be forced to recompile the corresponding source file, and it will be put the resulting object and ALI files in the directory where it found the dummy file.

`-jn'

Use n processes to carry out the (re)compilations. On a multiprocessor machine compilations will occur in parallel. In the event of compilation errors, messages from various compilations might get interspersed (but gnatmake will give you the full ordered list of failing compiles at the end). If this is problematic, rerun the make process with n set to 1 to get a clean list of messages.

`-k'

Keep going. Continue as much as possible after a compilation error. To ease the programmer's task in case of compilation errors, the list of sources for which the compile fails is given when gnatmake terminates.

If gnatmake is invoked with several `file_names' and with this switch, if there are compilation errors when building an executable, gnatmake will not attempt to build the following executables.

`-l'

Link only. Can be combined with `-b' to binding and linking. Linking will not be performed if combined with `-c' but not with `-b'. When not combined with `-b' all the units in the closure of the main program must have been previously compiled and must be up to date, and the main program needs to have been bound. The root unit specified by file_name may be given without extension, with the source extension or, if no GNAT Project File is specified, with the ALI file extension.

`-m'

Specify that the minimum necessary amount of recompilations be performed. In this mode gnatmake ignores time stamp differences when the only modifications to a source file consist in adding/removing comments, empty lines, spaces or tabs. This means that if you have changed the comments in a source file or have simply reformatted it, using this switch will tell gnatmake not to recompile files that depend on it (provided other sources on which these files depend have undergone no semantic modifications). Note that the debugging information may be out of date with respect to the sources if the `-m' switch causes a compilation to be switched, so the use of this switch represents a trade-off between compilation time and accurate debugging information.

`-M'

Check if all objects are up to date. If they are, output the object dependences to `stdout' in a form that can be directly exploited in a `Makefile'. By default, each source file is prefixed with its (relative or absolute) directory name. This name is whatever you specified in the various `-aI' and `-I' switches. If you use gnatmake -M `-q' (see below), only the source file names, without relative paths, are output. If you just specify the `-M' switch, dependencies of the GNAT internal system files are omitted. This is typically what you want. If you also specify the `-a' switch, dependencies of the GNAT internal files are also listed. Note that dependencies of the objects in external Ada libraries (see switch `-aL'dir in the following list) are never reported.

`-n'

Don't compile, bind, or link. Checks if all objects are up to date. If they are not, the full name of the first file that needs to be recompiled is printed. Repeated use of this option, followed by compiling the indicated source file, will eventually result in recompiling all required units.

`-o exec_name'

Output executable name. The name of the final executable program will be exec_name. If the `-o' switch is omitted the default name for the executable will be the name of the input file in appropriate form for an executable file on the host system.

This switch cannot be used when invoking gnatmake with several `file_names'.

`-p or --create-missing-dirs'

When using project files (-Pproject), create automatically missing object directories, library directories and exec directories.

`-Pproject'

Use project file project. Only one such switch can be used. See section 12.1 gnatmake and Project Files.

`-q'

Quiet. When this flag is not set, the commands carried out by gnatmake are displayed.

`-s'

Recompile if compiler switches have changed since last compilation. All compiler switches but -I and -o are taken into account in the following way: orders between different "first letter" switches are ignored, but orders between same switches are taken into account. For example, `-O -O2' is different than `-O2 -O', but `-g -O' is equivalent to `-O -g'.

This switch is recommended when Integrated Preprocessing is used.

`-u'

Unique. Recompile at most the main files. It implies -c. Combined with -f, it is equivalent to calling the compiler directly. Note that using -u with a project file and no main has a special meaning (see section 12.1.4 Project Files and Main Subprograms).

`-U'

When used without a project file or with one or several mains on the command line, is equivalent to -u. When used with a project file and no main on the command line, all sources of all project files are checked and compiled if not up to date, and libraries are rebuilt, if necessary.

`-v'

Verbose. Display the reason for all recompilations gnatmake decides are necessary, with the highest verbosity level.

`-vl'

Verbosity level Low. Display fewer lines than in verbosity Medium.

`-vm'

Verbosity level Medium. Potentially display fewer lines than in verbosity High.

`-vh'

Verbosity level High. Equivalent to -v.

`-vPx'

Indicate the verbosity of the parsing of GNAT project files. See section 12.1.1 Switches Related to Project Files.

`-x'

Indicate that sources that are not part of any Project File may be compiled. Normally, when using Project Files, only sources that are part of a Project File may be compile. When this switch is used, a source outside of all Project Files may be compiled. The ALI file and the object file will be put in the object directory of the main Project. The compilation switches used will only be those specified on the command line. Even when `-x' is used, mains specified on the command line need to be sources of a project file.

`-Xname=value'

Indicate that external variable name has the value value. The Project Manager will use this value for occurrences of external(name) when parsing the project file. See section 12.1.1 Switches Related to Project Files.

`-z'

No main subprogram. Bind and link the program even if the unit name given on the command line is a package name. The resulting executable will execute the elaboration routines of the package and its closure, then the finalization routines.

gcc switches

Any uppercase or multi-character switch that is not a gnatmake switch is passed to gcc (e.g. `-O', `-gnato,' etc.)

Source and library search path switches:

`-aIdir'

When looking for source files also look in directory dir. The order in which source files search is undertaken is described in 3.3 Search Paths and the Run-Time Library (RTL).

`-aLdir'

Consider dir as being an externally provided Ada library. Instructs gnatmake to skip compilation units whose `.ALI' files have been located in directory dir. This allows you to have missing bodies for the units in dir and to ignore out of date bodies for the same units. You still need to specify the location of the specs for these units by using the switches `-aIdir' or `-Idir'. Note: this switch is provided for compatibility with previous versions of gnatmake. The easier method of causing standard libraries to be excluded from consideration is to write-protect the corresponding ALI files.

`-aOdir'

When searching for library and object files, look in directory dir. The order in which library files are searched is described in 4.4 Search Paths for gnatbind.

`-Adir'

Equivalent to `-aLdir -aIdir'.

`-Idir'

Equivalent to `-aOdir -aIdir'.

`-I-'

Do not look for source files in the directory containing the source file named in the command line. Do not look for ALI or object files in the directory where gnatmake was invoked.

`-Ldir'

Add directory dir to the list of directories in which the linker will search for libraries. This is equivalent to `-largs -L'dir. Furthermore, under Windows, the sources pointed to by the libraries path set in the registry are not searched for.

`-nostdinc'

Do not look for source files in the system default directory.

`-nostdlib'

Do not look for library files in the system default directory.

`--RTS=rts-path'

Specifies the default location of the runtime library. GNAT looks for the runtime in the following directories, and stops as soon as a valid runtime is found (`adainclude' or `ada_source_path', and `adalib' or `ada_object_path' present):

• <current directory>/$rts_path

• <default-search-dir>/$rts_path

• <default-search-dir>/rts-$rts_path

The selected path is handled like a normal RTS path.

6.3 Mode Switches for gnatmake

The mode switches (referred to as mode_switches) allow the inclusion of switches that are to be passed to the compiler itself, the binder or the linker. The effect of a mode switch is to cause all subsequent switches up to the end of the switch list, or up to the next mode switch, to be interpreted as switches to be passed on to the designated component of GNAT.

`-cargs switches'

Compiler switches. Here switches is a list of switches that are valid switches for gcc. They will be passed on to all compile steps performed by gnatmake.

`-bargs switches'

Binder switches. Here switches is a list of switches that are valid switches for gnatbind. They will be passed on to all bind steps performed by gnatmake.

`-largs switches'

Linker switches. Here switches is a list of switches that are valid switches for gnatlink. They will be passed on to all link steps performed by gnatmake.

`-margs switches'

Make switches. The switches are directly interpreted by gnatmake, regardless of any previous occurrence of `-cargs', `-bargs' or `-largs'.

6.4 Notes on the Command Line

This section contains some additional useful notes on the operation of the gnatmake command.

• If gnatmake finds no ALI files, it recompiles the main program and all other units required by the main program. This means that gnatmake can be used for the initial compile, as well as during subsequent steps of the development cycle.

• If you enter gnatmake file.adb, where `file.adb' is a subunit or body of a generic unit, gnatmake recompiles `file.adb' (because it finds no ALI) and stops, issuing a warning.

• In gnatmake the switch `-I' is used to specify both source and library file paths. Use `-aI' instead if you just want to specify source paths only and `-aO' if you want to specify library paths only.

• gnatmake will ignore any files whose ALI file is write-protected. This may conveniently be used to exclude standard libraries from consideration and in particular it means that the use of the `-f' switch will not recompile these files unless `-a' is also specified.

• gnatmake has been designed to make the use of Ada libraries particularly convenient. Assume you have an Ada library organized as follows: obj-dir contains the objects and ALI files for of your Ada compilation units, whereas include-dir contains the specs of these units, but no bodies. Then to compile a unit stored in main.adb, which uses this Ada library you would just type

  $ gnatmake -aIinclude-dir -aLobj-dir main

• Using gnatmake along with the `-m (minimal recompilation)' switch provides a mechanism for avoiding unnecessary recompilations. Using this switch, you can update the comments/format of your source files without having to recompile everything. Note, however, that adding or deleting lines in a source files may render its debugging info obsolete. If the file in question is a spec, the impact is rather limited, as that debugging info will only be useful during the elaboration phase of your program. For bodies the impact can be more significant. In all events, your debugger will warn you if a source file is more recent than the corresponding object, and alert you to the fact that the debugging information may be out of date.

6.5 How gnatmake Works

Generally gnatmake automatically performs all necessary recompilations and you don't need to worry about how it works. However, it may be useful to have some basic understanding of the gnatmake approach and in particular to understand how it uses the results of previous compilations without incorrectly depending on them.

First a definition: an object file is considered up to date if the corresponding ALI file exists and if all the source files listed in the dependency section of this ALI file have time stamps matching those in the ALI file. This means that neither the source file itself nor any files that it depends on have been modified, and hence there is no need to recompile this file.

gnatmake works by first checking if the specified main unit is up to date. If so, no compilations are required for the main unit. If not, gnatmake compiles the main program to build a new ALI file that reflects the latest sources. Then the ALI file of the main unit is examined to find all the source files on which the main program depends, and gnatmake recursively applies the above procedure on all these files.

This process ensures that gnatmake only trusts the dependencies in an existing ALI file if they are known to be correct. Otherwise it always recompiles to determine a new, guaranteed accurate set of dependencies. As a result the program is compiled "upside down" from what may be more familiar as the required order of compilation in some other Ada systems. In particular, clients are compiled before the units on which they depend. The ability of GNAT to compile in any order is critical in allowing an order of compilation to be chosen that guarantees that gnatmake will recompute a correct set of new dependencies if necessary.

When invoking gnatmake with several file_names, if a unit is imported by several of the executables, it will be recompiled at most once.

Note: when using non-standard naming conventions (see section 2.4 Using Other File Names), changing through a configuration pragmas file the version of a source and invoking gnatmake to recompile may have no effect, if the previous version of the source is still accessible by gnatmake. It may be necessary to use the switch -f.

6.6 Examples of gnatmake Usage

gnatmake hello.adb

Compile all files necessary to bind and link the main program `hello.adb' (containing unit Hello) and bind and link the resulting object files to generate an executable file `hello'.

gnatmake main1 main2 main3

Compile all files necessary to bind and link the main programs `main1.adb' (containing unit Main1), `main2.adb' (containing unit Main2) and `main3.adb' (containing unit Main3) and bind and link the resulting object files to generate three executable files `main1', `main2' and `main3'.

gnatmake -q Main_Unit -cargs -O2 -bargs -l

Compile all files necessary to bind and link the main program unit Main_Unit (from file `main_unit.adb'). All compilations will be done with optimization level 2 and the order of elaboration will be listed by the binder. gnatmake will operate in quiet mode, not displaying commands it is executing.