You copied the Doc URL to your clipboard.

Preprocessing assembly code

The C preprocessor must resolve assembly code that contains C preprocessor directives, for example #include or #define, before assembling.

By default, armclang uses the assembly code source file suffix to determine whether to run the C preprocessor:

  • The .s (lowercase) suffix indicates assembly code that does not require preprocessing.
  • The .S (uppercase) suffix indicates assembly code that requires preprocessing.

The -x option lets you override the default by specifying the language of the subsequent source files, rather than inferring the language from the file suffix. Specifically, -x assembler-with-cpp indicates that the assembly code contains C preprocessor directives and armclang must run the C preprocessor. The -x option only applies to input files that follow it on the command line.


Do not confuse the .ifdef assembler directive with the preprocessor #ifdef directive:

  • The preprocessor #ifdef directive checks for the presence of preprocessor macros, These macros are defined using the #define preprocessor directive or the armclang -D command-line option.
  • The armclang integrated assembler .ifdef directive checks for code symbols. These symbols are defined using labels or the .set directive.

The preprocessor runs first and performs textual substitutions on the source code. This stage is when the #ifdef directive is processed. The source code is then passed onto the assembler, when the .ifdef directive is processed.

To preprocess an assembly code source file, do one of the following:

  • Ensure that the assembly code filename has a .S suffix.

    For example:

    armclang --target=arm-arm-none-eabi -march=armv8-a test.S
  • Use the -x assembler-with-cpp option to tell armclang that the assembly source file requires preprocessing. This option is useful when you have existing source files with the lowercase extension .s.

    For example:

    armclang --target=arm-arm-none-eabi -march=armv8-a -x assembler-with-cpp test.s


If you want to preprocess assembly files that contain legacy armasm-syntax assembly code, then you must either:

  • Use the .S filename suffix.
  • Use separate steps for preprocessing and assembling.

For more information, see Command-line options for preprocessing assembly source code in the Migration and Compatibility Guide.