10.4.3. Command File Preprocessing Options

The options listed in the subsections below control how the linker preprocesses linker command files. 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.

10.4.3.1. Option Summary

--define

Predefines name as a preprocessor macro. See Linker Command File Preprocessing (--disable_pp, --define and --undefine Options).

--undefine

Removes the preprocessor macro name. See Linker Command File Preprocessing (--disable_pp, --define and --undefine Options).

--disable_pp

Disables preprocessing for command files. See Linker Command File Preprocessing (--disable_pp, --define and --undefine Options).

--honor_cmdfile_order

Specify the order of output sections according to the order listed in a linker command file. This will also honor other placement constraints, such as placement to a specific memory address, before falling back to command file order.

10.4.3.2. Linker Command File Preprocessing (--disable_pp, --define and --undefine Options)

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:

  • --disable_pp - Disables preprocessing for command files

  • --define=name[=val] - Predefines &name* as a preprocessor macro

  • --undefine=name - Removes the macro name

The compiler has --define and --undefine options with the same meanings. However, the linker options are distinct; only --define and --undefine options passed to the linker with -Wl or -Xlinker affect linker preprocessing. For example:

tiarmclang --define=FOO=1 main.c -Wl,--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 uses the same search paths to find #include files as it does to find libraries. That is, #include files are searched in the following places:

  1. If the #include file name is in quotes (rather than <brackets>), in the directory of the current file

  2. In the list of directories specified with --search_path options or environment variables (see Alter the Library Search Algorithm (--library, --search_path)).

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

The linker provides the built-in macro definitions in the following list. 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.

  • __DATE__ Expands to the compilation date in the form “mmm dd yyyy

  • __FILE__ Expands to the current source filename

  • __TI_COMPILER_VERSION__ Defined to a 7-9 digit integer, depending on if X has 1, 2, or 3 digits. The number does not contain a decimal. For example, version 3.2.1 is represented as 3002001. The leading zeros are dropped to prevent the number being interpreted as an octal.

  • __TI_EABI__ Defined to 1 if EABI is enabled; otherwise, it is undefined.

  • __TI_ARM__ Always defined |

  • __TI_ARM_V6M0__ Defined to 1 if the v6M0 architecture (Cortex-M0) is targeted (the -mcpu=cortex-m0 option is used); otherwise, it is undefined.

  • __TI_ARM_V7__ Defined to 1 if any v7 architecture (Cortex) is targeted; otherwise, it is undefined.

  • __TI_ARM_V7M__ Defined to 1 if any Cortex-M architecture is targeted; otherwise, it is undefined.

  • __TI_ARM_V7M3__ Defined to 1 if the v7M3 architecture (Cortex-M3) is targeted (the -mcpu=cortex-m3 option is used); otherwise, it is undefined.

  • __TI_ARM_V7M4__ Defined to 1 if the v7M4 architecture (Cortex-M4) is targeted (the -mcpu=cortex-m4 option is used); otherwise, it is undefined.

  • __TI_ARM_V7R4__ Defined to 1 if the v7R4 architecture (Cortex-R4) is targeted (the -mcpu=cortex-r4 option is used); otherwise, it is undefined.

  • __TI_ARM_V7R5__ Defined to 1 if the v7R5 architecture (Cortex-R5) is targeted (the -mcpu=cortex-r5 option is used); otherwise, it is undefined.

  • __TIME__ Expands to the compilation time in the form “hh:mm:ss