2.9. Defining the Object/Library File Directory Search Path¶
At link time, a collection of object files, that either have been freshly generated by the compiler or reside in an existing object library, are combined together to form a linked output file. In typical cases, the linked output file is a static executable, but the linker is also capable of generating a partially linked output file in which relocation entries are preserved and which may be combined with other object files in a subsequent link.
2.9.1. Object/Library File Directory Search Path¶
Within a given linker invocation, an object or library file can be specified explicitly or with a ‘-l’ prefix. Such a specification can be indicated on a command-line invocation of the linker or within a linker command file that is incorporated into a link. If a ‘-l’ prefix is used in an object or library file specification, then the linker will locate the specified file or library using an object/library file directory search path.
The concept is similar to the notion of an include file directory search path in the case where the include file is enclosed in angle brackets (< >).
Specifically, when a ‘-l’ prefix is indicated in an object or library file specification, the linker will search for the specified file in the following locations in this order:
Directories named in -L compiler options in the order in which the options are specified in the tiarmclang invocation
Standard system lib directory
Directories named in -Xlinker --search_path options in the order in which the options are specified in the tiarmclang invocation
Directories listed in the TI_ARM_C_DIR environment variable definition
By default, the armcl compiler begins with an empty object/library file directory search path. The recommended environment variable that serves as a sort of baseline definition of the object/library file directory search path is TI_ARM_C_DIR, but the armcl compiler will also honor legacy environment variables TMS470_C_DIR and C_DIR.
Unlike the armcl compiler, the tiarmclang compiler populates the object/library file directory search path with the standard system lib directory, <install area>/lib/generic, that is set up when the tiarmclang compiler tools are installed.
You may also annotate the object/library file directory search path using the TI_ARM_C_DIR environment variable when the linker is invoked with either the armcl or tiarmclang compiler. The linker will also honor legacy environment variables TMS470_C_DIR and C_DIR.
Please note that while the tiarmlnk linker that is provided with the tiarmclang compiler tools is identical to the armlnk linker that is provided with the armcl compiler tools with respect to these environment variables, the two linker executables are not functionally equivalent in other ways. Some of the significant differences between the executables are discussed in the “Behavioral Differences” chapter.
2.9.2. Adding to the Object/Library File Directory Search Path with Compiler Command-Line Options¶
As indicated above, the definition of the object/library file directory search path can be annotated on the compiler command-line.
armcl Option (and alias) |
tiarmclang Option |
|---|---|
--include_path=<dir list> (-I=<dir list>) (-i=<dir list>) |
-L <dir> |
When using the armcl compiler, the --include_path option allows a user to specify a semi-colon separated list of one or more directory paths that is converted into a --search_path linker option when the armcl compiler is made to invoke the linker. The linker will then follow the rules indicated in the above “Object/Library File Directory Search Path” section when searching for an object or library file that is specified as a linker option on the armcl compiler command-line or within a linker command file using a ‘-l’ prefix.
The tiarmclang compiler’s -L option is functionally equivalent to the armcl compiler’s --include_path option except that the -L option allows only a single directory path to be specified for each -L option on the tiarmclang command-line. However, you can specify more than one -L option on the tiarmclang command-line to add additional directories to the object/library file directory search path. When multiple -L options are specified, they will be translated into multiple --search_path linker options in the order in which they are specified.
You can also pass explicit --search_path options directly to the linker from the compiler command-line.
armcl Option |
tiarmclang Option |
|---|---|
-z … --search_path=<dir list> |
-Xlinker --search_path=<dir> -Wl,–search_path,<dir> |
When the linker is invoked from the armcl compiler command-line, all options that are specified after the -z (or --run_linker) option are passed directly to the linker. In this manner, a user can add one or more directories to the object/library file directory search path.
When invoking the linker from the tiarmclang compiler command-line, options that are intended as input to the linker invocation should be preceded by -Xlinker. You may also pass an option to the linker using the -Wl, option mechanism. For example, if you have a directory called “myobj” under the work directory that you are invoking the compiler from, you can append the ./myobj sub-directory to the object/ library file directory search path with the following option:
-Wl,–search_path,./myobj
As is the case with the tiarmclang compiler’s -L option, only one directory path may be specified to the --search_path option when passed to the linker from the tiarmclang compiler command-line.