3.8. 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.
3.8.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 c29clang invocation.
Standard system lib directory.
Directories named in -Xlinker --search_path options in the order in which the options are specified in the c29clang invocation.
Directories listed in the C2000_C_DIR environment variable definition.
By default, the cl2000 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 C2000_C_DIR, but the cl2000 compiler also honors the cl2000 environment variable C_DIR. In addition, the cl2000 compiler allows the C2000_C_OPTION environment variable to define a set of compiler options to be used as if they were on the command line.
Unlike the cl2000 compiler, the c29clang 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 c29clang compiler tools are installed.
You may also control the object/library file directory search path using the C2000_C_DIR environment variable when the linker is invoked with either the cl2000 or c29clang compiler. The linker also honors the cl2000 environment variable C_DIR. Use of the C2000_C_OPTION environment variable should be migrated to command line options and environment variables that are supported by the c29clang compiler.
Please note that while the c29lnk linker that is provided with the c29clang compiler tools is identical to the lnk linker that is provided with the cl2000 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 Main Differences Between cl2000 and c29clang chapter.
3.8.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 controlled using the compiler command-line.
cl2000 Option (and alias) |
c29clang Option |
|---|---|
--include_path=<dir list> (-I=<dir list>) (-i=<dir list>) |
-L <dir> |
When using the cl2000 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 cl2000 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 cl2000 compiler command-line or within a linker command file using a ‘-l’ prefix.
The c29clang compiler’s -L option is functionally equivalent to the cl2000 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 c29clang command-line. However, you can specify more than one -L option on the c29clang 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.
cl2000 Option |
c29clang Option |
|---|---|
-z … --search_path=<dir list> |
-Xlinker --search_path=<dir> -Wl,–search_path,<dir> |
When the linker is invoked from the cl2000 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 c29clang 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 c29clang compiler’s -L option, only one directory path may be specified to the --search_path option when passed to the linker from the c29clang compiler command-line.