Next: , Previous: Running gnatmake, Up: Building with gnatmake

4.1.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.
--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 with the specified name.

--create-missing-dirs
When using project files (-P`project'), automatically create missing object directories, library directories and exec directories.
--single-compile-per-obj-dir
Disallow simultaneous compilations in the same object directory when project files are used.
--subdirs=`subdir'
Actual object directory of each project file is the subdirectory subdir of the object directory specified or defaulted in the project file.
--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.

-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 (-P`file`) 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.

-eI`nnn'
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 (see 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.

-j`n'
Use n processes to carry out the (re)compilations. On a multiprocessor machine compilations will occur in parallel. If n is 0, then the maximum number of parallel compilations is the number of core processors on the platform. 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
Same as --create-missing-dirs

-P`project'
Use project file project. Only one such switch can be used. 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 (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.
-vP`x'
Indicate the verbosity of the parsing of GNAT project files. See 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.
-X`name'=`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. 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

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

-aL`dir'
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 -aI`dir' or -I`dir'. 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.

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

-A`dir'
Equivalent to -aL`dir' -aI`dir'.


-I`dir'
Equivalent to -aO`dir' -aI`dir'.

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

-L`dir'
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):