GNAT GPL User's Guide: Linking with gnatlink

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 5. Linking with `gnatlink`

This chapter discusses `gnatlink`, a tool that links an Ada program and builds an executable file. This utility invokes the system linker (via the `gcc` command) with a correct list of object files and library references. `gnatlink` automatically determines the list of files and references for the Ada part of a program. It uses the binder file generated by the `gnatbind` to determine this list.

Note: to invoke `gnatlink` with a project file, use the `gnat` driver (see 12.2 The GNAT Driver and Project Files).

> 5.1 Running `gnatlink` |  |
> 5.2 Switches for `gnatlink` |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.1 Running `gnatlink`

The form of the `gnatlink` command is

    $ gnatlink [switches] mainprog[.ali]
               [non-Ada objects] [linker options]

The arguments of `gnatlink` (switches, main ``ALI'` file, non-Ada objects or linker options) may be in any order, provided that no non-Ada object may be mistaken for a main ``ALI'` file. Any file name ``F'` without the ``.ali'` extension will be taken as the main ``ALI'` file if a file exists whose name is the concatenation of ``F'` and ``.ali'`.

``mainprog.ali'` references the ALI file of the main program. The ``.ali'` extension of this file can be omitted. From this reference, `gnatlink` locates the corresponding binder file ``b~mainprog.adb'` and, using the information in this file along with the list of non-Ada objects and linker options, constructs a linker command file to create the executable.

The arguments other than the `gnatlink` switches and the main ``ALI'` file are passed to the linker uninterpreted. They typically include the names of object files for units written in other languages than Ada and any library references required to resolve references in any of these foreign language units, or in `Import` pragmas in any Ada units.

linker options is an optional list of linker specific switches. The default linker called by gnatlink is `gcc` which in turn calls the appropriate system linker.

One useful option for the linker is ``-s'`: it reduces the size of the executable by removing all symbol table and relocation information from the executable.

Standard options for the linker such as ``-lmy_lib'` or ``-Ldir'` can be added as is. For options that are not recognized by `gcc` as linker options, use the `gcc` switches ``-Xlinker'` or ``-Wl,'`.

Refer to the GCC documentation for details.

Here is an example showing how to generate a linker map:

    $ gnatlink my_prog -Wl,-Map,MAPFILE

Using linker options it is possible to set the program stack and heap size. See H.15 Setting Stack Size from `gnatlink` and H.16 Setting Heap Size from `gnatlink`.

`gnatlink` determines the list of objects required by the Ada program and prepends them to the list of objects passed to the linker. `gnatlink` also gathers any arguments set by the use of `pragma Linker_Options` and adds them to the list of arguments presented to the linker.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.2 Switches for `gnatlink`

The following switches are available with the `gnatlink` utility:

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

``-f'`
  On some targets, the command line length is limited, and `gnatlink` will generate a separate file for the linker if the list of object files is too long. The ``-f'` switch forces this file to be generated even if the limit is not exceeded. This is useful in some cases to deal with special situations where the command line length is exceeded.

``-g'`
  The option to include debugging information causes the Ada bind file (in other words, ``b~mainprog.adb'`) to be compiled with ``-g'`. In addition, the binder does not delete the ``b~mainprog.adb'`, ``b~mainprog.o'` and ``b~mainprog.ali'` files. Without ``-g'`, the binder removes these files by default. The same procedure apply if a C bind file was generated using ``-C'` `gnatbind` option, in this case the filenames are ``b_mainprog.c'` and ``b_mainprog.o'`.

``-n'`
  Do not compile the file generated by the binder. This may be used when a link is rerun with different options, but there is no need to recompile the binder file.

``-v'`
  Causes additional information to be output, including a full list of the included object files. This switch option is most useful when you want to see what set of object files are being used in the link step.

``-v -v'`
  Very verbose mode. Requests that the compiler operate in verbose mode when it compiles the binder file, and that the system linker run in verbose mode.

``-o exec-name'`
  exec-name specifies an alternate name for the generated executable program. If this switch is omitted, the executable has the same name as the main unit. For example, `gnatlink try.ali` creates an executable called ``try'`.

``-b target'`
  Compile your program to run on target, which is the name of a system configuration. You must have a GNAT cross-compiler built if target is not the same as your host system.

``-Bdir'`
  Load compiler executables (for example, `gnat1`, the Ada compiler) from dir instead of the default location. Only use this switch when multiple versions of the GNAT compiler are available. See section `Directory Options' in The GNU Compiler Collection, for further details. You would normally use the ``-b'` or ``-V'` switch instead.

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

``-M=mapfile'`
  When linking an executable, create a map file. The name of the map file is "mapfile".

``--GCC=compiler_name'`
  Program used for compiling the binder file. 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 `gnatlink` to use `foo -x -y` as your compiler. Note that switch ``-c'` is always inserted after your command name. Thus in the above example the compiler command that will be used by `gnatlink` will be `foo -c -x -y`. A limitation of this syntax is that the name and path name of the executable itself must not include any embedded spaces. If the compiler executable is different from the default one (gcc or <prefix>-gcc), then the back-end switches in the ALI file are not used to compile the binder generated source. For example, this is the case with ``--GCC="foo -x -y"'`. But the back end switches will be used for ``--GCC="gcc -gnatv"'`. 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"'`.

``--LINK=name'`
  name is the name of the linker to be invoked. This is especially useful in mixed language programs since languages such as C++ require their own linker to be used. When this switch is omitted, the default name for the linker is `gcc`. When this switch is used, the specified linker is called instead of `gcc` with exactly the same parameters that would have been passed to `gcc` so if the desired linker requires different parameters it is necessary to use a wrapper script that massages the parameters before invoking the real linker. It may be useful to control the exact invocation by using the verbose switch.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html