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 specify 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. File and Path Names Containing Special Characters¶
A reference to a normal file name, such as file.o in a link command line or in a linker command file is handled as expected by the linker. You can also specify path information or include special characters, like hyphens, in a file name specification. In most cases, a file name specification containing path information should be properly interpreted by the linker, but in some cases, especially when a file name specification contains a special character, like a hyphen, you should enclose the file name specification in double-quotes to ensure that it is properly interpreted.
Specifically in the case of a hyphen, the reason that a file name specification containing a hyphen must be enclosed in double-quotes is because a hyphen can be legitimately interpreted as a subtraction operator.
For example, file or library names containing hyphens referenced in a linker command file without enclosing double-quotes will cause problems at link time:
SECTIONS
{
....
.mytext1 : { lib-with-dashes.lib(.text) } > 0x00010000
.mytext2 : { name-with-dashes.o(.text) } > 0x10000000
...
}
%> tiarmlnk.cmd -mcpu=cortex-m4 name-with-dashes.o -o a.out -Wl,badlnk.cmd,-ma.map
"badlnk.cmd", line 24: error: cannot find file "lib"
"badlnk.cmd", line 24: error: -l must specify a filename
"badlnk.cmd", line 24: error: cannot find file "with"
"badlnk.cmd", line 24: error: cannot find file "dashes.lib"
"badlnk.cmd", line 25: error: cannot find file "name"
"badlnk.cmd", line 25: error: -l must specify a filename
"badlnk.cmd", line 25: error: cannot find file "with"
"badlnk.cmd", line 25: error: cannot find file "dashes.o"
"badlnk.cmd", line 24: warning: no matching section
"badlnk.cmd", line 25: warning: no matching section
"badlnk.cmd", line 24: warning: no matching section
"badlnk.cmd", line 24: warning: no matching section
"badlnk.cmd", line 25: warning: no matching section
"badlnk.cmd", line 25: warning: no matching section
undefined first referenced
symbol in file
--------- ----------------
my_func name-with-dashes.o
error: unresolved symbols remain
error: errors encountered during linking; "a.out" not built
If the referenced file names are enclosed in double-quotes, the link succeeds:
SECTIONS
{
....
.mytext1 : { "lib-with-dashes.lib"(.text) } > 0x00010000
.mytext2 : { "name-with-dashes.o"(.text) } > 0x10000000
...
}
%> tiarmlnk.cmd -mcpu=cortex-m4 name-with-dashes.o -o a.out -Wl,goodlnk.cmd,-ma.map
%> cat a.map
...
SECTION ALLOCATION MAP
output attributes/
section page origin length input sections
-------- ---- ---------- ---------- ----------------
...
.mytext1 0 00010000 00000018
00010000 00000010 lib-with-dashes.lib : my-func.o (.text.my_func)
00010010 00000008 libc.a : printf.c.obj (.tramp.printf.1)
.mytext2 0 10000000 0000001c
10000000 00000014 name-with-dashes.o (.text.main)
10000014 00000008 lib-with-dashes.lib : my-func.o (.tramp.my_func.1)
It is recommended that if your file name specification contains unusual or special characters that might not be interpreted by the linker as an obvious part of a file or path name, then you should try enclosing your file name specification in double-quotes to ensure that it is properly interpreted.
10.3.5. 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.6. 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.