6.1 Operation

A command to the linker takes the following form:

hlink [options] files

The options are zero or more case-insensitive linker options, each of which modifies the behavior of the linker in some way. The files is one or more object files and zero or more library files (.a extension).

The options recognized by the linker are listed in the table below and are discussed in the paragraphs that follow.

Table 6-1. Linker Command-line Options
Option	Effect
`-Aclass=low-high ,...`	Specify address ranges for a class.
`-Cpsect=class`	Specify a class name for a global psect.
`-Ctype`	Specify call graph type.
`-Dclass=delta`	Specify a class delta value.
`-Dsymfile`	Produce old-style symbol file.
`-Eerrfile`	Write error messages to errfile.
`-F`	Produce `.o` file with only symbol records.
`-G spec`	Specify calculation for segment selectors.
`-H symfile`	Generate symbol file.
`-H+ symfile`	Generate enhanced symbol file.
`-I`	Ignore undefined symbols.
`-J num`	Set maximum number of errors before aborting.
`-K`	Prevent overlaying function parameter and auto areas.
`-L`	Preserve relocation items in .o file.
`-LM`	Preserve segment relocation items in `.o` file.
`-Mmapfile`	Generate a link map in the named file.
`-N`	Sort symbol table in map file by address order.
`-Nc`	Sort symbol table in map file by class address order.
`-Ns`	Sort symbol table in map file by space address order.
`-Ooutfile`	Specify name of output file.
`-Pspec`	Specify psect addresses and ordering.
`-Qprocessor`	Specify the device type (for cosmetic reasons only).
`-S`	Inhibit listing of symbols in symbol file.
`-Sclass=limit[,bound]`	Specify address limit, and start boundary for a class of psects.
`-Usymbol`	Pre-enter symbol in table as undefined.
`-Vavmap`	Use file avmap to generate an Avocet format symbol file.
`-Wwarnlev`	Set warning level (-9 to 9).
`-Wwidth`	Set map file width (>=10).
`-X`	Remove any local symbols from the symbol file.
`-Z`	Remove trivial local symbols from the symbol file.
`--DISL=list`	Specify disabled messages.
`--EDF=path`	Specify message file location.
`--EMAX=number`	Specify maximum number of errors.
`--fixupoverflow=action`	Specify response when encountering fixup overflows.
`--NORLF`	Do not relocate list file.
`--VER`	Print version number and stop.
`--werror=num`	Promote warnings to errors

If the standard input is a file, then this file is assumed to contain the command-line argument. Lines can be broken by leaving a backslash \ at the end of the preceding line. In this fashion, hlink commands of almost unlimited length can be issued. For example, a link command file called x.lnk and containing the following text:

-Z -Ox.o -Mx.map \
-Ptext=0,data=0/,bss,nvram=bss/. \
x.o y.o z.o

can be passed to the linker by one of the following:

hlink @x.lnk
hlink < x.lnk

Several linker options require memory addresses or sizes to be specified. The syntax for all of these is similar. By default, the number is interpreted as a decimal value. To force interpretation as a HEX number, a trailing H, or h, should be added. For example, 765FH will be treated as a HEX number.

To build projects you will typically use either the MPLAB XC8 C compiler (xc8-cc) driver or the MPLAB XC8 PIC Assembler (pic-as) driver. These will call the linker for you, passing it a set of default linker options. If you need to modify or supply additional linker options when using a driver, use either the -Wl (see Wl: Pass Option To The Linker, Option) or -Xlinker (see Xlinker Option) driver options, which will pass on the suboption to the linker application when it is executed.