5.5 XC32 Linker Options

The following are linker feature controls displayed in the MPLAB X IDE and VS Code project property dialogs, along with their corresponding driver options. When used, these options are passed to the linker application xc32-ld and are not relevant for the xc32-gcc driver. For additional linker options, see MPLAB® XC32 Assembler, Linker And Utilities User’s Guide documentation.

Table 5-11. XC32 Linker General Category
Option	Description	Command Line
Heap Size (bytes)	Specify the size of the heap in bytes. Allocate a run-time heap of size bytes for use by C programs. The heap is allocated from unused data memory. If not enough memory is available, an error is reported.	`--defsym=_min_heap_size=<size>` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Minimum stack size (bytes)	Specify the minimum size of the stack in bytes. By default, the linker allocates all unused data memory for the run-time stack. Use this option to ensure that at least a minimum sized stack is available. The actual stack size is reported in the link map output file. If the minimum size is not available, an error is reported.	`--defsym=_min_stack_size=<size>` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Allow overlapped sections	Check to ignore overlaps of section addresses. This feature is provided for diagnostic purposes and should be used only to diagnose a linker error related to section-allocation issues. Uncheck to check for overlaps.	`--[no-]check-sections` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Remove unused sections	Check to enable garbage collection of unused input sections (on some targets). This is typically used with the controls that place data/functions into their own section. Uncheck to disable garbage collection.	`--[no-]gc-sections` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Use response file to link (MPLAB X IDE only)	Pass linker options in a file rather than on the command line. On Windows systems, this option allows you to properly link projects with a large number of object files that would normally overrun the command-line length limitation of the Windows OS.
Write start linear address record	Use the ELF file's entry-point field to write a Start Linear Address (SLA) record (type 0x05) to the hex file. The hex record may be useful for a bootloader that needs to determine the entry point to the application. You can set the value using the `ENTRY` command line the linker script.	`--write-sla` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Additional Linker options (VS Code only)	Type here any additional linker options that do not have dedicated GUI widgets in the Project Properties dialog. The string entered here will be emitted using a -Wl, prefix so that it will be passed directly to the linker.
Additional driver options	Type here any additional driver options that do not have dedicated GUI widgets in the Project Properties dialog. The string entered here will be emitted verbatim with the other driver options.

Table 5-12. XC32 Linker Libraries Option Category
Option	Description	Command Line
Optimization level of Standard Libraries	Select the optimization level with which libraries were built. Equivalent to `-On` option emitted for the link stage of compilation, where `n` is an option below: `0` - Do not optimize. The compiler’s goal is to reduce the cost of compilation and to make debugging produce the expected results. `1` - Optimize. Optimizing compilation takes somewhat longer, and a lot more host memory for a large function. The compiler tries to reduce code size and execution time. `2` - Optimize even more. The compiler performs nearly all supported optimizations that do not involve a space-speed trade-off. `3` - Optimize yet more favoring speed (superset of `-O2`). `s` - Optimize for size. This level enables all `-O2` optimizations that do not typically increase code size. It also performs further optimizations designed to reduce code size.	`-On` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
System Libraries	Add libraries to be linked with the project files. You may add more than one.	`--library=name` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Library directories	Add a library directory to the library search path. You may add more than one.	`--library-path="name"` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Exclude Standard Libraries	Check to not use the standard system startup files or libraries when linking. Only use library directories specified on the command line. Uncheck to use the standard system startup files and libraries.	`-nostdlib` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Do not link crt0 startup code	Exclude the default startup code because the project provides application-specific startup code.	`-nostartfiles` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Do not link device startup code	Do not link the default device-specific startup code (for example, `startup_device.c`)	`-mno-device-startup-code` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.

Table 5-13. XC32 Linker Diagnostics Options Category
Option	Description	Command Line
Generate map file	Create a map file.	`-Map="file"` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Display memory usage	Check to print memory usage report. Uncheck to not print a report.	`--report-mem` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Generate cross-reference file	Check to create a cross-reference table. Uncheck to not create this table.	`--cref` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Warn on section realignment	Check to have warnings printed if the start of a section changes due to alignment. This feature is provided for diagnostic purposes and should be used only to diagnose section-alignment issues. Uncheck to inhibit warning.	`--warn-section-align` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Trace Symbols	Add/remove trace symbols.	`-Y symbol` or `--trace-symbol symbol` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.

Table 5-14. XC32 Linker Symbols and Macros Options Category
Option	Description	Command Line
Linker symbols	Create a global symbol in the output file containing the absolute address (`expr`). You may use this option as many times as necessary to define multiple symbols in the command line. A limited form of arithmetic is supported for the `expr` in this context: you may give a hexadecimal constant or the name of an existing symbol, or use + and - to add or subtract hexadecimal constants or symbols.	`--defsym=sym` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Preprocessor macro definitions	Define preprocessor macros for use in linker scripts (when the option is passed to xc32-gcc directly).	`-Dmacro` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.
Symbols	Specify symbol information in the output.	`-S` or `--strip-debug`; `-s` or `--strip-all` See MPLAB® XC32 Assembler, Linker and Utilities User's Guide.