10.5.2 Commands Dealing with Files

Several linker script commands deal with files.

CRT0_STARTUP(object file)

This command identifies which primary startup module should be loaded from the compiler libraries. The primary startup module defines reserved symbol __resetPRI and is responsible for initializing the C runtime environment. Multiple versions of this module exist in order to support architectural differences between device families. Although the linker expects to find this command in every linker script, a default startup module will be selected if the command is missing (as might be the case with custom linker scripts in legacy projects).

CRT1_STARTUP(object file)

This command identifies which alternate startup module should be loaded from the compiler libraries. The alternate startup module defines reserved symbol __resetALT and is responsible for initializing the C runtime environment without data initialization. Multiple versions of this module exist in order to support architectural differences between device families. Although the linker expects to find this command in every linker script, a default startup module will be selected if the command is missing (as might be the case with custom linker scripts in legacy projects).

INCLUDE filename

Include the linker script filename at this point. The file will be searched for in the current directory, and in any directory specified with the -L option. Calls to INCLUDE may be nested up to 10 levels deep.

INPUT(file, file, ...) 
INPUT(file file ...) 

The INPUT command directs the linker to include the named files in the link, as though they were named on the command line. The linker will first try to open the file in the current directory. If it is not found, the linker will search through the archive library search path. See the description of -L in --library-path dir (-L dir).

If INPUT (-lfile) is used, xc32-ld will transform the name to libfile.a, as with the command line argument -l.

When the INPUT command appears in an implicit linker script, the files will be included in the link at the point at which the linker script file is included. This can affect archive searching.

GROUP(file, file, ...)
GROUP(file file ...)

The GROUP command is like INPUT, except that the named files should all be archives, and they are searched repeatedly until no new undefined references are created. See the description of -( in -( archives -), --start-group archives, --end-group.

OPTIONAL(file, file, ...)
OPTIONAL(file file ...)

The OPTIONAL command is analogous to the INPUT command, except that the named files are not required for the link to succeed. This is particularly useful for specifying archives (or libraries) that may or may not be installed with the compiler.

OUTPUT(filename)

The OUTPUT command names the output file. Using OUTPUT(filename) in the linker script is exactly like using -o filename on the command line (see --output file (-o file)). If both are used, the command line option takes precedence.

SEARCH_DIR(path)

The SEARCH_DIR command adds path to the list of paths where the linker looks for archive libraries. Using SEARCH_DIR(path) is exactly like using -L path on the command line (see --library-path dir (-L dir)). If both are used, then the linker will search both paths. Paths specified using the 
command line option are searched first.

STARTUP(filename)

The STARTUP command is just like the INPUT command, except that filename will become the first input file to be linked, as though it were specified first on the command line.