7.6.9 Options for Linking

Table 7-16. Linking Options
Option	Definition
`--fill=options`	Fill unused program memory. The format is: `--fill=[wn:]expression[@address[:end_address] \| unused]` `address` and `end_address` will specify the range of program memory addresses to fill. If `end_address` is not provided then the `expression` will be written to the specific memory location at address address. The optional literal value `unused` may be specified to indicate that all unused memory will be filled. If none of the location parameters are provided, all unused memory will be filled. `expression` will describe how to fill the specified memory. The following options are available: A single value `xc16-ld --fill=0x12345678@unused` Range of values `xc16-ld --fill=1,2,3,4,097@0x9d000650:0x9d000750` An incrementing value `xc16-ld --fill=7+=911@unused` By default, the linker will fill using data that is instruction-word length. For 16-bit devices, the default fill width is 24 bits. However, you may specify the value width using`[wn:]`, where `n` is the fill value's width and `n` belongs to [1, 3]. Multiple fill options may be specified on the command line; the linker will always process fill options at specific locations first.
`--gc-sections`	Remove dead functions from code at link time. Support is for ELF projects only. In order to make the best use of this feature, add the  `-ffunction-sections` option to the compiler command line.
`-Ldir`	Add directory `dir` to the list of directories to be searched for libraries specified by the command-line option `-l`.
`-legacy-libc`	Use legacy include files and libraries (v3.24 and before). The format of include file and libraries changed in v3.25 to match HI-TECH C compiler format.
`-llibrary`	Search the library named `library` when linking. The linker searches a standard list of directories for the library, which is actually a file named `liblibrary.a`. The linker then uses this file as if it had been specified precisely by name. It makes a difference where in the command you write this option; the linker processes libraries and object files in the order they are specified. Thus, `foo.o -lz bar.o` searches library `z` after file `foo.o` but before `bar.o`. If `bar.o` refers to functions in `libz.a`, those functions may not be loaded. The directories searched include several standard system directories, plus any that you specify with `-L`. Normally the files found this way are library files (archive files whose members are object files). The linker handles an archive file by scanning through it for members which define symbols that have so far been referenced but not defined. But if the file that is found is an ordinary object file, it is linked in the usual fashion. The only difference between using an `-l` option (e.g., `-lmylib`) and specifying a file name (e.g., `libmylib.a`) is that `-l` searches several directories, as specified. By default the linker is directed to search: `<install-path>\lib` for libraries specified with the `-l` option. This behavior can be overridden using the environment variables defined in the Predefined Macro Names section.
`-nodefaultlibs`	Do not use the standard system libraries when linking. Only the libraries you specify will be passed to the linker. The compiler may generate calls to `memcmp`, `memset` and `memcpy`. These entries are usually resolved by entries in the standard compiler libraries. These entry points should be supplied through some other mechanism when this option is specified.
`-nostdlib`	Do not use the standard system startup files or libraries when linking. No startup files and only the libraries you specify will be passed to the linker.  The compiler may generate calls to `memcmp`, `memset` and `memcpy`. These entries are usually resolved by entries in standard compiler libraries. These entry points should be supplied through some other mechanism when this option is specified.
`-s`	Remove all symbol table and relocation information from the executable.
`-T script`	Specify the linker script file, `script`, to be used at link time. This option is translated into the equivalent `-T` linker option.
`-u symbol`	Pretend `symbol` is undefined to force linking of library modules to define the symbol. It is legitimate to use `-u` multiple times with different symbols to force loading of additional library modules.
`-Wl,option`	Pass `option` as an option to the linker. If `option` contains commas, it is split into multiple options at the commas. For example, to generate a map file, use `-W1, -Map=Project.map`.
`-Xlinker option`	Pass `option` as an option to the linker. You can use this to supply system-specific linker options that the compiler does not know how to recognize.

--fill=options

Fill unused program memory. The format is:

--fill=[wn:]expression[@address[:end_address] | unused]

address and end_address will specify the range of program memory addresses to fill. If end_address is not provided then the expression will be written to the specific memory location at address address. The optional literal value unused may be specified to indicate that all unused memory will be filled. If none of the location parameters are provided, all unused memory will be filled. expression will describe how to fill the specified memory. The following options are available:

A single value

xc16-ld --fill=0x12345678@unused

Range of values

xc16-ld --fill=1,2,3,4,097@0x9d000650:0x9d000750

An incrementing value

xc16-ld --fill=7+=911@unused

By default, the linker will fill using data that is instruction-word length. For 16-bit devices, the default fill width is 24 bits. However, you may specify the value width using[wn:], where n is the fill value's width and n belongs to [1, 3].

Multiple fill options may be specified on the command line; the linker will always process fill options at specific locations first.

--gc-sections

Remove dead functions from code at link time.

Support is for ELF projects only. In order to make the best use of this feature, add the  -ffunction-sections option to the compiler command line.

-Ldir

Add directory dir to the list of directories to be searched for libraries specified by the command-line option -l.

-legacy-libc

Use legacy include files and libraries (v3.24 and before).

The format of include file and libraries changed in v3.25 to match HI-TECH C compiler format.

-llibrary

Search the library named library when linking.

The linker searches a standard list of directories for the library, which is actually a file named liblibrary.a. The linker then uses this file as if it had been specified precisely by name.

It makes a difference where in the command you write this option; the linker processes libraries and object files in the order they are specified. Thus, foo.o -lz bar.o searches library z after file foo.o but before bar.o. If bar.o refers to functions in libz.a, those functions may not be loaded.

The directories searched include several standard system directories, plus any that you specify with -L.

Normally the files found this way are library files (archive files whose members are object files). The linker handles an archive file by scanning through it for members which define symbols that have so far been referenced but not defined. But if the file that is found is an ordinary object file, it is linked in the usual fashion. The only difference between using an -l option (e.g., -lmylib) and specifying a file name (e.g., libmylib.a) is that -l searches several directories, as specified.

By default the linker is directed to search:

<install-path>\lib

for libraries specified with the -l option.

This behavior can be overridden using the environment variables defined in the Predefined Macro Names section.

-nodefaultlibs

Do not use the standard system libraries when linking. Only the libraries you specify will be passed to the linker. The compiler may generate calls to memcmp, memset and memcpy. These entries are usually resolved by entries in the standard compiler libraries. These entry points should be supplied through some other mechanism when this option is specified.

-nostdlib

Do not use the standard system startup files or libraries when linking. No startup files and only the libraries you specify will be passed to the linker.  The compiler may generate calls to memcmp, memset and memcpy. These entries are usually resolved by entries in standard compiler libraries. These entry points should be supplied through some other mechanism when this option is specified.

-s

Remove all symbol table and relocation information from the executable.

-T
                            script

Specify the linker script file, script, to be used at link time. This option is translated into the equivalent -T linker option.

-u symbol

Pretend symbol is undefined to force linking of library modules to define the symbol. It is legitimate to use -u multiple times with different symbols to force loading of additional library modules.

-Wl,option

Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas.

For example, to generate a map file, use -W1, -Map=Project.map.

-Xlinker
                            option

Pass option as an option to the linker. You can use this to supply system-specific linker options that the compiler does not know how to recognize.