12. Customizing Macros

Preprocessor macros in C, C++, and Objective C (introduced by #define) have a syntax different from the main language—for example, a macro declaration is not terminated by a semicolon, and if it is more than a line long, line breaks in it must be escaped with backslashes. CC Mode has some commands to manipulate these, see Customizing Macro Backslashes.

Normally, the lines in a multi-line macro are indented relative to each other as though they were code. You can suppress this behavior by setting the following user option:

User Option: c-syntactic-indentation-in-macros

Enable syntactic analysis inside macros, which is the default. If this is nil, all lines inside macro definitions are analyzed as cpp-macro-cont.

Sometimes you may want to indent particular directives (e.g. #pragma) as though they were statements. To do this, see Indenting Directives.

Because a macro can expand into anything at all, near where one is invoked CC Mode can only indent and fontify code heuristically. Sometimes it gets it wrong. Usually you should try to design your macros so that they “look like ordinary code” when you invoke them. However, two situations are so common that CC Mode handles them specially: that is when certain macros needn’t (or mustn’t) be followed by a ‘;’, and when certain macros (or compiler directives) expand to nothing. You need to configure CC Mode to handle these macros properly, see Macros with semicolons and Noise Macros.

12.1 Customizing Macro Backslashes

CC Mode provides some tools to help keep the line continuation backslashes in macros neat and tidy. Their precise action is customized with these variables:

User Option: c-backslash-column

User Option: c-backslash-max-column

These variables control the alignment columns for line continuation backslashes in multiline macros. They are used by the functions that automatically insert or align such backslashes, e.g. c-backslash-region and c-context-line-break.

c-backslash-column specifies the minimum column for the backslashes. If any line in the macro goes past this column, then the next tab stop (i.e. next multiple of tab-width) in that line is used as the alignment column for all the backslashes, so that they remain in a single column. However, if any lines go past c-backslash-max-column then the backslashes in the rest of the macro will be kept at that column, so that the lines which are too long “stick out” instead.

Don’t ever set these variables to nil. If you want to disable the automatic alignment of backslashes, use c-auto-align-backslashes.

User Option: c-auto-align-backslashes

Align automatically inserted line continuation backslashes if non-nil. When line continuation backslashes are inserted automatically for line breaks in multiline macros, e.g. by c-context-line-break, they are aligned with the other backslashes in the same macro if this flag is set.

If c-auto-align-backslashes is nil, automatically inserted backslashes are preceded by a single space, and backslashes get aligned only when you explicitly invoke the command c-backslash-region (C-c C-\).

12.2 Macros with semicolons

Macros which needn’t (or mustn’t) be followed by a semicolon when you invoke them, macros with semicolons, are very common. These can cause CC Mode to parse the next line wrongly as a statement-cont (see section Function Symbols) and thus mis-indent it. At the top level, a macro invocation before a defun start can cause, for example, c-beginning-of-defun (C-M-a) not to find the correct start of the current function.

You can prevent these by specifying which macros have semicolons. It doesn’t matter whether or not such a macro has a parameter list:

User Option: c-macro-names-with-semicolon

This buffer-local variable specifies which macros have semicolons. After setting its value, you need to call c-make-macro-with-semi-re for it to take effect. It should be set to one of these values:

nil

There are no macros with semicolons.

a list of strings

Each string is the name of a macro with a semicolon. Only valid #define names are allowed here. For example, to set the default value, you could write the following into your ‘.emacs’:

(setq c-macro-names-with-semicolon '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS"))

a regular expression

This matches each symbol which is a macro with a semicolon. It must not match any string which isn’t a valid #define name. For example:

(setq c-macro-names-with-semicolon "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>")

Function: c-make-macro-with-semi-re

Call this (non-interactive) function, which sets internal variables, each time you change the value of c-macro-names-with-semicolon after the major mode function has run. It takes no arguments, and its return value has no meaning. This function is called by CC Mode’s initialization code, after the mode hooks have run.

12.3 Noise Macros

In CC Mode, noise macros are macros which expand to nothing, or compiler directives (such as GCC’s __attribute__) which play no part in the syntax of the C (etc.) language. Some noise macros are followed by arguments in parentheses (possibly optionally), others are not.

Noise macros can easily confuse CC Mode’s analysis of function headers, causing them to be mis-fontified, or even mis-indented. You can prevent this confusion by specifying the identifiers which constitute noise macros.

User Option: c-noise-macro-names

This variable is a list of names of noise macros which never have parenthesized arguments. Each element is a string, and must be a valid identifier. Alternatively, the variable may be a regular expression which matches the names of such macros. Such a noise macro is treated as whitespace by CC Mode. It must not also be in, or be matched by c-noise-macro-with-parens-names.

User Option: c-noise-macro-with-parens-names

This variable is a list of names of noise macros which optionally have arguments in parentheses. Each element of the list is a string, and must be a valid identifier. Alternatively, the variable may be a regular expression which matches the names of such macros. Such a noise macro must not also be in, or be matched by c-noise-macro-names. For performance reasons, such a noise macro, including any parenthesized arguments, is specially handled, but it is only handled when used in declaration contexts(53).

The two compiler directives __attribute__ and __declspec have traditionally been handled specially in CC Mode; for example they are fontified with font-lock-keyword-face. You don’t need to include these directives in c-noise-macro-with-parens-names, but doing so is OK.

Function: c-make-noise-macro-regexps

Call this (non-interactive) function, which sets internal variables, on changing the value of c-noise-macro-names or c-noise-macro-with-parens-names after the major mode’s function has run. This function is called by CC Mode’s initialization code, after the mode hooks have run.

12.4 Indenting Directives

Sometimes you may want to indent particular preprocessor directives (e.g. #pragma) as though they were statements. To do this, first set up c-cpp-indent-to-body-directives to include the directive name(s), then enable the “indent to body” feature with c-toggle-cpp-indent-to-body.

User Option: c-cpp-indent-to-body-directives

This variable is a list of names of CPP directives (not including the introducing ‘#’) which will be indented as though statements. Each element is a string, and must be a valid identifier. The default value is ("pragma").

If you add more directives to this variable, or remove directives from it, whilst “indent to body” is active, you need to re-enable the feature by calling c-toggle-cpp-indent-to-body for these changes to take effect(54).

Function: c-toggle-cpp-indent-to-body

With M-x c-toggle-cpp-indent-to-body, you enable or disable the “indent to body” feature. When called programmatically, it takes an optional numerical argument. A positive value will enable the feature, a zero or negative value will disable it.

You should set up c-cpp-indent-to-body-directives before calling this function, since the function sets internal state which depends on that variable.

This document was generated on September 26, 2026 using texi2html 1.82.