The linker preprocesses linker command files using a standard C preprocessor. Therefore, the command files can contain well-known preprocessing directives such as #define, #include, and #if / #endif.

Three linker options control the preprocessor:

The compiler has --define and --undefine options with the same meanings. However, the linker options are distinct; only --define and --undefine options specified after --run_linker are passed to the linker. For example:

cl2000 --define=FOO=1 main.c --run_linker --define=BAR=2 lnk.cmd

The linker sees only the --define for BAR; the compiler only sees the --define for FOO.

When one command file #includes another, preprocessing context is carried from parent to child in the usual way (that is, macros defined in the parent are visible in the child). However, when a command file is invoked other than through #include, either on the command line or by the typical way of being named in another command file, preprocessing context is not carried into the nested file. The exception to this is --define and --undefine options, which apply globally from the point they are encountered. For example:

  --define GLOBAL
  #define LOCAL
  #include "incfile.cmd"     /* sees GLOBAL and LOCAL */
  nestfile.cmd               /* only sees GLOBAL      */

Two cautions apply to the use of --define and --undefine in command files. First, they have global effect as mentioned above. Second, since they are not actually preprocessing directives themselves, they are subject to macro substitution, probably with unintended consequences. This effect can be defeated by quoting the symbol name. For example:

  --define MYSYM=123
  --undefine MYSYM     /* expands to --undefine 123 (!) */
  --undefine "MYSYM"   /* ahh, that's better            */

The linker searches for an #include file in the following order until the file is found:

1. If the #include file name is in quotes (rather than <brackets>), search the directory that contains the current file.
2. If the --include_path compiler option was used (before the --run_linker or -z option), search the path specified with that option.
3. If the C2000_C_DIR environment variable is defined, search directories pointed to by that definition. See Section 9.5.17.2.

There are two exceptions: relative pathnames (such as "../name") always search relative to the current directory, and absolute pathnames (such as "/usr/tools/name") bypass search paths entirely.

The linker provides the built-in macro definitions listed in Table 9-10. The availability of these macros within the linker is determined by the command-line options used, not the build attributes of the files being linked. If these macros are not set as expected, confirm that your project's command line uses the correct compiler option settings.