8.1 Linker Interface Syntax

The linker supports a plethora of command-line options, but in actual practice few of them are used in any particular context. The general form of a command to run the linker looks like the following.

xc32-ld [options] files

The linker options are case sensitive and are described in sections following. The files are one or more object files (.o extension) or library archive files (.a extension) which will be linked together to form the final output.

For instance, a frequent use of xc32-ld is to link object files and archives to produce a binary file. To link a file hello.o:

xc32-ld -o output hello.o -lpic32

This tells xc32-ld to produce a file called output as the result of linking the file hello.o with the library archive libpic32.a.

When linking a C application, there are typically several library archives that are included in the link command. The list of archives may be specified within --start-group, --end-group options to help resolve circular references:

xc32-ld -o output hello.o --start-group -lpic32 -lm -lc --end-group

The command-line options to xc32-ld may be specified in any order, and may be repeated at will. Repeating most options with a different argument will either have no further effect, or override prior occurrences (those further to the left on the command line) of that option. Options that may be meaningfully specified more than once are noted in the descriptions below.

Non-option arguments are object files that are to be linked together. They may follow, precede or be mixed in with command-line options, except that an object file argument may not be placed between an option and its argument.

Usually the linker is invoked with at least one object file, but you can specify other forms of binary input files using -l and the script command language. If no binary input files are specified, the linker does not produce any output, and issues the message ‘No input files’.

If the linker cannot recognize the format of an object file, it will assume that it is a linker script. A script specified in this way augments the main linker script used for the link (either the default linker script or the one specified by using -T). This feature permits the linker to link against a file that appears to be an object or an archive, but actually merely defines some symbol values, or uses INPUT or GROUP to load other objects.

For options whose names are a single letter, option arguments must either follow the option letter without intervening white space, or be given as separate arguments immediately following the option that requires them.

For options whose names are multiple letters, either one dash or two can precede the option name; for example, -trace-symbol and --trace-symbol are equivalent. There is one exception to this rule. Multiple-letter options that begin with the letter o can only be preceded by two dashes.

Arguments to multiple-letter options must either be separated from the option name by an equals sign, or be given as separate arguments immediately following the option that requires them. For example, --trace-symbol srec and --trace-symbol=srec are equivalent. Unique abbreviations of the names of multiple-letter options are accepted.