5. Linking Using 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.

5.1 Running gnatlink
5.2 Switches for gnatlink
5.3 Setting Stack Size from gnatlink
5.4 Setting Heap Size from gnatlink

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. 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 5.3 Setting Stack Size from gnatlink and 5.4 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.

5.2 Switches for gnatlink

The following switches are available with the gnatlink utility:

`-A'

The binder has generated code in Ada. This is the default.

`-C'

If instead of generating a file in Ada, the binder has generated one in C, then the linker needs to know about it. Use this switch to signal to gnatlink that the binder has generated C code rather than Ada code.

`-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 the gcc manual page for further details. You would normally use the `-b' or `-V' switch instead.

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

5.3 Setting Stack Size from gnatlink

Under Windows systems, it is possible to specify the program stack size from gnatlink using either:

• using `-Xlinker' linker option

  $ gnatlink hello -Xlinker --stack=0x10000,0x1000

  This sets the stack reserve size to 0x10000 bytes and the stack commit size to 0x1000 bytes.

• using `-Wl' linker option

  $ gnatlink hello -Wl,--stack=0x1000000

  This sets the stack reserve size to 0x1000000 bytes. Note that with `-Wl' option it is not possible to set the stack commit size because the coma is a separator for this option.

5.4 Setting Heap Size from gnatlink

Under Windows systems, it is possible to specify the program heap size from gnatlink using either:

• using `-Xlinker' linker option

  $ gnatlink hello -Xlinker --heap=0x10000,0x1000

  This sets the heap reserve size to 0x10000 bytes and the heap commit size to 0x1000 bytes.

• using `-Wl' linker option

  $ gnatlink hello -Wl,--heap=0x1000000

  This sets the heap reserve size to 0x1000000 bytes. Note that with `-Wl' option it is not possible to set the heap commit size because the coma is a separator for this option.