From the Experts: Accessing files and libraries from a linker command file (LCF)

 Many applications built with TI Code Generation Tools utilize custom linker command files (or LCFs) to control the placement of code and data in target memory. For example, you may want to collect a group of commonly used utility functions into a specific area of target memory. This is simple to do using the available LCF syntax to reference the desired object file or library. However, a problem that many developers run into when they try to do this is a linker generated “file not found” error when accessing an object file or library from inside the LCF. Most often, this error occurs because the syntax used to access the file on the linker command-line does not match the syntax that is used to access the same file in the LCF.

Expanding on the example suggested earlier, imagine that you have an object library, util.lib, which contains definitions of commonly used utility functions that you want to be loaded into a memory area called “UTILMEM”. Assume also that all the utility functions are defined in .text sections in the object file members of util.lib. In your custom LCF, mylnk.cmd, you can control the placement of the utility functions as follows:

SECTIONS
{
   …
   .utils: { util.lib(.text) } > UTILMEM
   …
}

Now assume that the util.lib object library gets put into a sub-directory called “lib” relative to where you are building the application. In order to gain access to util.lib from the build command-line, you can use a combination of the –i (or –-search_path) and –l (or –-library) options to set up a directory search path which the linker can use to find the util.lib library:

%> cl6x <compile options/files> -z –i ./lib –l util.lib mylnk.cmd <link options/files>

In essence, the linker has a few different ways of opening files:The –i option adds the lib sub-directory to the directory search path and the –l option instructs the linker to look through the directories in the directory search path to find the util.lib library. However, if you do not update the reference to util.lib in mylnk.cmd, the linker will fail to find the util.lib library and generate a “file not found” error. The reason is that when the linker encounters the reference to util.lib inside the SECTIONS directive, there is no –l option preceding the reference. Therefore, the linker tries to open util.lib in the current working directory.

  • If there is a path included in the file reference, the linker will look for the file in the specified location. For an absolute path, the linker will try to open the file in the specified directory. For a relative path, the linker will follow the specified path starting from the current working directory and try to open the file at that location.
  • If there is no path included in the file reference, the linker will try to open the file in the current working directory.
  • If a –l (or –-library) option precedes the file reference, then the linker will try to open the referenced file in the first directory in the directory search path where the file is found. The directory search path is set up via  –i (or –-search_path) options on the command-line or within the Code Composer Studio (CCS) options dialog box (if you are building your application in CCS) and environment variables (like C6X_C_DIR, TMS470_C_DIR, C2000_C_DIR, or MSP430_C_DIR depending on what target processor your application is designed to run on). Please see the appropriate Compiler User Guide or the Assembly Language Tools User Guide for more details on using environment variables to help define the directory search path.

Note: As long as a file is referenced in a consistent manner on the command line and throughout any applicable LCFs, the linker should be able to find and open that file.

Returning to our example, you can insert a –l option in front of the reference to util.lib in mylnk.cmd to ensure that the linker will find and open the util.lib library when the application is built:

SECTIONS
{
   …
   .utils: { -l util.lib(.text) } > UTILMEM
   …
}

Another benefit to using the –l option when referencing a file from within an LCF is that if the location of the referenced file changes, you can modify the directory search path to incorporate the new location of the file (by modifying an existing –i option or adding a new one on the command line, for example) without having to modify the LCF.

For more information about linker command files and linker command file syntax:

  • Visit the relevant Assembly Language Tools User Guide from here (especially the section entitled “Linker Command Files”).
  • Visit the Linker Command File Primer wiki article.