9.5.2 Commands Dealing with Files

Include Command

The INCLUDE filename command 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 Command

The INPUT(file, file, ...) or INPUT(file file ...) 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 the -L option in 8.3.9 L: Library Path Option.

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 Command

The GROUP(file, file, ...) or GROUP(file file ...) 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 archives in 8.3.1 Start-group/End-group Options.

As_needed Command

The AS_NEEDED(file, file, ...) or AS_NEEDED(file file ...) command can appear only inside of the INPUT or GROUP commands, among other filenames. The files listed will be handled as if they appear directly in the INPUT or GROUP commands; however, if the file is an ELF shared library, that will be added only when it is actually needed. This construct essentially enables the --as-needed command-line option for all the files listed with this command and then restores previous setting afterwards.

Optional Command

The OPTIONAL(file, file, ...) 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. The default linker scripts provided with the XC32 compiler use the OPTIONAL directive to link the device-specific peripheral libraries.

Output Command

The OUTPUT(filename) command names the output file. Using this command in the linker script has a similar effect to using the -o filename option on the command line (see 8.3.13 O: Specify Output File). If both are used, the command line option takes precedence.

Search_dir Command

The SEARCH_DIR(path) command adds path to the list of paths where the linker looks for archive libraries. Using this command in the linker script has a similar effect to using the -L path option on the command line (see 8.3.9 L: Library Path Option). If both are used, then the linker will search both paths. Paths specified using the command line option are searched first.

Startup Command

The STARTUP(filename) 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.