10.4.2. File Search Path Options¶

The options listed in the subsections below control how the linker locates files, such as object libraries. On the tiarmclang command-line they should be passed to the linker using the -Wl or -Xlinker option as described in Passing Options to the Linker.

Option Summary
Alter the Library Search Algorithm (--library, --search_path)
- Name an Alternate Library Directory (--search_path Option)
- Exhaustively Read and Search Libraries (--reread_libs and --priority Options)
Automatic Library Selection (--disable_auto_rts Option)

10.4.2.1. Option Summary ¶

--library (-l)¶: Names an archive library or link command filename as linker input. See Alter the Library Search Algorithm (--library, --search_path).

--disable_auto_rts¶: Disables the automatic selection of a run-time-support library. See Automatic Library Selection (--disable_auto_rts Option).

--priority (-priority)¶: Satisfies unresolved references by the first library that contains a definition for that symbol. See Exhaustively Read and Search Libraries (--reread_libs and --priority Options).

--reread_libs (-x)¶: Forces rereading of libraries, which resolves back references. See Exhaustively Read and Search Libraries (--reread_libs and --priority Options).

--search_path (-i)¶: Alters library-search algorithms to look in a directory named with pathname before looking in the default location. This option must appear before the --library option. See Name an Alternate Library Directory (--search_path Option).

10.4.2.2. Alter the Library Search Algorithm (--library, --search_path)¶

Usually, when you want to specify a file as linker input, you simply enter the filename; the linker looks for the file in the current directory. For example, suppose the current directory contains the library object.lib. If this library defines symbols that are referenced in the file file1.c.o, this is how you link the files:

tiarmclang file1.c.o object.lib

If you want to use a file that is not in the current directory, use the --library linker option. The --library option’s short form is -l. The syntax for this option is:

--library=[pathname] filename

The filename is the name of an archive, an object file, or linker command file. You can specify up to 128 search paths.

The --library option is not required when one or more members of an object library are specified for input to an output section. For more information about allocating archive members, see Specifying Library or Archive Members as Input to Output Sections.

You can adjust the linker’s directory search algorithm using the --search_path linker option. When the --library option is applied to a file name specification, the linker searches for object files, object libraries, and linker command files in this order:

It searches directories named with the --search_path linker option. The --search_path option must appear before the --library option on the command line or in a command file.
It searches the current directory.

For example, let’s suppose you have an object library named my.lib in the current work directory, and another version of the library with the same name in a sub-directory called old_libs. We can choose which version of my.lib will be used in a link with the help of the --search_path (-I) and --library (-l) options.

In the following tiarmclang command, the my.lib in the current work directory will be incorporated in the link since the reference to my.lib is not prefixed with the --library or -l option:

%> tiarmclang -mcpu=cortex-m4 use_my_lib.c -o a.out -Wl,-I./old_libs,my.lib,-llnk.cmd

If the -l option is used as a prefix to the reference to my.lib, the linker will find and use the version of my.lib from the old_lib directory in the link:

%> tiarmclang -mcpu=cortex-m4 use_my_lib.c -o a.out -Wl,-I./old_libs,-lmy.lib,-llnk.cmd

10.4.2.2.1. Name an Alternate Library Directory (--search_path Option)¶

The --search_path option names an alternate directory that contains input files. The --search_path option’s short form is -I. The syntax for this option is:

--search_path=pathname

The pathname names a directory that contains input files.

When the linker is searching for input files named with the --library option, it searches through directories named with --search_path first. Each --search_path option specifies only one directory, but you can have several --search_path options per invocation. When you use the --search_path option to name an alternate directory, it must precede any --library option used on the command line or in a command file.

For example, assume that there are two archive libraries called r.lib and lib2.lib that reside in ld and ld2 directories. The commands below show the directories that r.lib and lib2.lib reside in, how to set environment variable, and how to use both libraries during a link:

UNIX (Bourne shell)¶

tiarmclang f1.c.o f2.c.o -Wl,--search_path=/ld,--search_path=/ld2,--library=r.lib,--library=lib2.lib

Windows¶

tiarmclang f1.c.o f2.c.o -Wl,--search_path=\ld,--search_path=\ld2,--library=r.lib,--library=lib2.lib

10.4.2.2.2. Exhaustively Read and Search Libraries (--reread_libs and --priority Options)¶

There are two ways to exhaustively search for unresolved symbols:

Reread libraries if you cannot resolve a symbol reference (--reread_libs).
Search libraries in the order that they are specified (--priority).

The linker normally reads input files, including archive libraries, only once when they are encountered on the command line or in the command file. When an archive is read, any members that resolve references to undefined symbols are included in the link. If an input file later references a symbol defined in a previously read archive library, the reference is not resolved.

With the --reread_libs option, you can force the linker to reread all libraries. The linker rereads libraries until no more references can be resolved. Linking using --reread_libs may be slower, so you should use it only as needed. For example, if a.lib contains a reference to a symbol defined in b.lib, and b.lib contains a reference to a symbol defined in a.lib, you can resolve the mutual dependencies by listing one of the libraries twice, as in:

tiarmclang -Wl,--library=a.lib,--library=b.lib,--library=a.lib

or you can force the linker to do it for you.

The --priority option provides an alternate search mechanism for libraries. Using --priority causes each unresolved reference to be satisfied by the first library that contains a definition for that symbol. For example:

objfile  references A
lib1     defines B
lib2     defines A, B; obj defining A references B

% tiarmclang objfile lib1 lib2

Under the existing model, objfile resolves its reference to A in lib2, pulling in a reference to B, which resolves to the B in lib2.

Under --priority, objfile resolves its reference to A in lib2, pulling in a reference to B, but now B is resolved by searching the libraries in order and resolves B to the first definition it finds, namely the one in lib1.

The --priority option is useful for libraries that provide overriding definitions for related sets of functions in other libraries without having to provide a complete version of the whole library.

For example, suppose you want to override versions of malloc and free defined in the libc.a without providing a full replacement for libc.a. Using --priority and linking your new library before libc.a guarantees that all references to malloc and free resolve to the new library.

The --priority option supports linking programs with a Runtime Operating System (RTOS) where situations like the one illustrated above occur.

10.4.2.3. Automatic Library Selection (--disable_auto_rts Option)¶

The --disable_auto_rts option disables the automatic selection of a run-time-support (RTS) library. See Invoking the Compiler for more on the automatic selection process.