10.3. Invoking the Linker¶
The default behavior of the tiarmclang compiler is to compile specified C, C++, or assembly source files into temporary object files and then pass those object files along with any explicitly specified object files and any specified linker options to the linker.
Alternately, if you specify only object files as input to the tiarmclang compiler, the compiler passes those files to the linker along with any specified options that are applicable to the link.
10.3.1. Compile and Link¶
The general syntax for invoking the compiler and linker together is:
tiarmclang [options] [source file names] [object file names] [-Wl,<linker options>]
In the following example, assume that the C code in file1.c references a data object that is defined in an object file named file2.o. The specified tiarmclang command compiles file1.c into a temporary object file. That object file, along with file2.o and a linker command file, link_test.cmd, will be input to the linker and linked with applicable object files from the tiarmclang runtime libraries to create an executable output file named test.out:
tiarmclang -mcpu=cortex-m0 file1.c file2.o -o test.out -Wl,link_test.cmd
Note that there is no mention of the tiarmclang runtime libraries on the tiarmclang command-line or inside the link_test.cmd linker command file. When the linker is invoked from the tiarmclang command-line, the tiarmclang compiler implicitly tells the linker where to find applicable runtime libraries like the C runtime library (libc.a). In the above tiarmclang command-line, the -Wl, prefix in front of the specification of the link_test.cmd file name indicates to the compiler that the link_test.cmd file should be input directly into the linker. (You can also use the -Xlinker prefix for this purpose.)
If you add the verbose (-v) option to the above tiarmclang command, you will see exactly how the linker (tiarmlnk) is invoked and with what options. For example, this command:
tiarmclang -mcpu=cortex-m0 -v file1.c file2.o -o test.out -Wl,link_test.cmd
shows the following with regards to how tiarmlnk is invoked by the tiarmclang compiler:
<install directory>/bin/tiarmlnk -I<install directory>/lib
-o test.out /tmp/file1-98472f.o file2.o link_test.cmd
--start-group -llibc++.a -llibc++abi.a -llibc.a -llibsys.a
-llibsysbm.a -llibclang_rt.builtins.a -llibclang_rt.profile.a --end-group
In the above invocation of the linker, the compiler inserts a -I<install directory>/lib option that tells the linker where to find the tiarmclang runtime libraries. The compiler also inserts the --start_group/--end_group options to specifies exactly which runtime libraries will be incorporated into the link.
10.3.2. Link-Only Using tiarmclang¶
When only object files are specified as input to the tiarmclang compiler command, the compiler passes those files to the linker along with any other specified options that are applicable to the link.
tiarmclang [options] [object file names] [-Wl,<linker options>]
As in the default case of “Compile and Link” described above, a -Wl, or -Xlinker prefix must be specified in front of options that are intended for the linker. For example, this tiarmclang command:
tiarmclang -mcpu=cortex-m0 file1.o file2.o -o test.out -Wl,link_test.cmd
will invoke the linker as follows:
<install directory>/bin/tiarmlnk -I<install directory>/lib
-o test.out file1.o file2.o link_test.cmd
--start-group -llibc++.a -llibc++abi.a -llibc.a -llibsys.a
-llibsysbm.a -llibclang_rt.builtins.a -llibclang_rt.profile.a --end-group
As in the “Compile and Link” case, the compiler inserts a -I<install directory>/lib option that tells the linker where to find the tiarmclang runtime libraries. The compiler also inserts the --start_group/--end_group option list that specifies exactly which runtime libraries will be incorporated into the link.
10.3.3. Passing Options to the Linker¶
The tiarmclang command line provides the following ways to pass options to the linker:
The -Wl option passes a comma-separated list of options to the linker.
The -Xlinker option passes a single option to the linker and can be used multiple times on the same command line.
A linker command file can specify options to pass to the linker.
For example, the following command line passes several linker options using the -Wl option:
tiarmclang -mcpu=cortex-m0 hello.c -o a.out -Wl,-stack=0x8000,--ram_model,link_test.cmd
The following command line passes the same linker options using the -Xlinker option:
tiarmclang -mcpu=cortex-m0 hello.c -o a.out -Xlinker -stack=0x8000 -Xlinker --ram_model -Xlinker link_test.cmd
The following lines from a linker command file, pass the same linker options to the linker:
/*********************************************************************/
/* Example Linker Command File */
/*********************************************************************/
-stack 0x8000 /* SOFTWARE STACK SIZE */
--ram_model /* INITIALIZE VARIABLES AT LOAD TIME */
10.3.4. Wildcards in File, Section, and Symbol Patterns¶
The linker allows file, section, and symbol names to be specified using the asterisk (*) and question mark (?) wildcards. Using * matches any number of characters. Using ? matches a single character. Wildcards can make it easier to handle related objects, provided they follow a suitable naming convention.
For example:
mp3*.o /* matches anything .o that begins with mp3 */
task?.o* /* matches task1.o, task2.c.o, taskX.o55, etc. */
SECTIONS
{
.fast_code: { *.o(*fast*) } > FAST_MEM
.vectors : { vectors.c.o(.vector:part1:*) > 0xFFFFFF00
.str_code : { rts*.lib<str*.c.o>(.text) } > S1ROM
}
10.3.5. Specifying C/C++ Symbols with Linker Options¶
The link-time symbol is the same as the high-level language name.
For more information on symbol names, see tiarmnm - Name Utility. For information specifically about C++ symbol naming, see tiarmdem - C++ Name Demangler Utility. See Using Linker Symbols in C/C++ Applications for information about referring to linker symbols in C/C++ code.