9.1 Syntax

The linker supports many command line options, but in actual practice few of them are used in any particular context.

xc32-ld [@options-file] [options] file...

For example, xc32-ld links object files and archives to produce a binary file. To link a file hello.o:

xc32-ld -o output hello.o -lpic30

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

When linking a C application, there are typically several archives (also known as “libraries”) which 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 -lpic30 -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 (i.e., those farther 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 (lowercase 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 with names that 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 with names that 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 equal 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.