#define<\/code> or #include<\/code>. However, the less experienced may not really know the difference between preprocessor directives and the actual program code. This article aims to explain this difference, which preprocessor directives are available, how to use them and what alternatives there are. And perhaps there will be some aspects that will also be of interest to the “older hands”. I will cover the following: <\/p>\n\n\n- What is the preprocessor, what are preprocessor directives?<\/a><\/li>\n
- Including files – #include<\/a><\/li>\n
- Macros – #define<\/a>\n
\n- Simple macros without passing variables<\/a>\n
\n- Pitfalls with simple macros<\/a><\/li>\n
- Alternatives to #define (const\/constexpr, enum)<\/a><\/li>\n<\/ul>\n<\/li>\n
- Macros with passing variables<\/a>\n
\n- macros vs. functions<\/a><\/li>\n
- “Arduino macros”<\/a><\/li>\n<\/ul>\n<\/li>\n
- Predefined macros<\/a><\/li>\n<\/ul>\n<\/li>\n
- Conditional inclusion of code – #ifdef, #ifndef & Co<\/a>\n
\n- Application example 1: Avoiding double reading of files<\/a><\/li>\n
- Application example 2: Debugging<\/a><\/li>\n
- Application example 3: MCU-specific code<\/a>\n
\n- Where can I find the board or MCU #defines?<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n
- Warnings and errors – #warning, #error<\/a><\/li>\n
- Manipulating the line counter and file name – #line<\/a><\/li>\n
- The multifunctional tool – #pragma<\/a>\n
\n- #pragma once<\/a><\/li>\n
- #pragma poison<\/a><\/li>\n
- #pragma message \/ warning \/ error<\/a><\/li>\n
- #pragma diagnostic<\/a><\/li>\n
- #pragma pack()<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n
What is the preprocessor, what are preprocessor directives?<\/h2>\n\n
The preprocessor is a program or component that is used before the actual compilation or execution of a code. It is often used in programming languages such as C and C++ (including Arduino code) to process source code before compilation. Essentially, the preprocessor performs the following tasks: <\/p>\n
\n- Replacement of strings by macros.<\/li>\n
- Inclusion of files.<\/li>\n
- Conditional inclusion or exclusion of code.<\/li>\n
- Control of compiler behavior (messages, errors, warnings).<\/li>\n<\/ul>\n
Preprocessor directives are the functions of the preprocessor. They are easy to identify as they begin with the hash character #. In contrast to instructions in the actual program code, they are not terminated with a semicolon, but with the end of the line. <\/p>\n\n
Including files – #include<\/h2>\n\n
As you know, you integrate files such as library files via #include<\/code>. This can be written as #include <Dateiname\/Pfad><\/code> and #include \"Dateiname\/Pfad\"<\/code>: <\/p>\n\n#include <...><\/code>: The compiler searches for the file in the standard include paths. These paths usually lead to folders called “libraries” or “include”. <\/li>\n#include \"...\"<\/code>: The compiler first searches for the file in the current directory. If it does not find it there, it continues the search in the standard include paths. <\/li>\n<\/ul>\nFor example, if you have created a file called config.h for your project, there is a good chance that a file with the same name already exists somewhere. In this case, you could avoid including the wrong file by saving your config.h in the folder of your “.ino” file and including it via #include \"...\"<\/code>. <\/p>\n\nMacros – #define<\/h2>\n\nSimple macros without passing variables<\/h3>\n\n
To create a macro, use #define. In its simplest form, it looks like this: <\/p>\n
#define identifier replacement<\/code><\/p>\ne.g.:<\/p>\n
#define LED_PIN 10<\/code><\/p>\nBy simple macros, I mean macros without any further passing of variables. In this case, #define<\/code> basically does the same as the search and replace function of a word-processing program. The identifier (officially: the macro name) LED_PIN<\/code> is replaced by 10 everywhere in your program. In the compiled program, it is no longer possible to see whether the 10 or the identifier was used in the source code. <\/p>\nOn “spelling”: it is common practice to write macro names in capital letters. Of course, it also works with lower case letters, but you will be doing yourself and others a favor if you stick to such conventions. <\/p>\n
In the depths of the libraries belonging to the Arduino package, you will see many macro names that begin and sometimes end with one or two underscores, such as “__AVR_ATmega328P__”, “_VECTORS_SIZE” or “__PACKED_STRUCT”. The underscores provide a certain level of protection – as long as you do not use them yourself. <\/p>\n\n
Pitfalls with simple macros<\/h4>\n\n
The “replacement”, i.e. the “macro value”, only gets its data type in the context of the program code. Which data type you mean and which data type the compiler makes of it may be two different things. See the following little sketch: <\/p>\n<\/p>\n
#define A_DEF 30000\n#define B_DEF 30000U\n\/* alternative 1: *\/\n\/\/ static const int A_DEF = 30000;\n\/\/ static const unsigned int B_DEF = 30000;\n\/* alternative 2: *\/\n\/\/ static constexpr int A_DEF = 30000;\n\/\/ static constexpr unsigned int B_DEF = 30000;\n\n\nvoid setup() {\n Serial.begin(115200);\n \/\/ delay(2000); \n \n Serial.print(\"A_DEF + 10000: \");\n Serial.println(A_DEF + 10000); \n Serial.print(\"B_DEF + 10000: \");\n Serial.println(B_DEF + 10000); \n}\n\nvoid loop() {}<\/pre>\n\n\n
And here is the output on an ATmega328P-based board:<\/p>\n\n![\"Preprocessor](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2025\/02\/output_out_of_range.png\")
<\/a>Output of out_of_range.ino<\/figcaption><\/figure>\n\nA_DEF<\/code> is obviously interpreted as a signed integer. Since I have chosen a board on which an integer has a size of 2 bytes, there is an overflow and correspondingly a negative result. Although the compiler issues a warning, it is easy to overlook. The numeric literal operator “U” in the definition of the macro B_DEF<\/code> provides a remedy, as it tells the compiler that the value should be “unsigned”. Alternatively, you can append “L” for long, “UL” for unsigned long, F for float or D for double. Lower case is also possible. <\/p>\nAnother obvious pitfall is the name collision. The compiler warns of a “redefinition” in such a case, but it does not lead to termination. Therefore, it can also easily be overlooked. <\/p>\n\n
Alternatives to #define (const\/constexpr, enum)<\/h4>\n\nconst and constexpr<\/h5>\n\n
The use of constants (const<\/code>) or constant expressions (constexpr<\/code>) is preferable to simple #define<\/code> directives, especially for larger programs. They express much more clearly what the values mean. <\/p>\nOn the difference const<\/code> vs. constexpr<\/code>: A constant const<\/code> may be assigned its value during runtime, with a constant expression constexpr<\/code> must happen during compilation.<\/p>\nThe addition static<\/code> ensures that a constant is only initialized once, and static<\/code> can also prevent the constant from being visible in other files. The exact effect of static<\/code> depends on where exactly the constant has been defined (e.g. inside or outside of functions and classes). However, this goes too far here. <\/p>\n\nenum <\/h5>\n\n
You use an enumeration enum<\/code> for constants that form a group, such as the primary colors in this example:<\/p>\n<\/p>\nenum COLOR {\n RED = 0xFF000, \/\/ RGB-value\n GREEN = 0x00FF00,\n BLUE = 0x0000FF\n};\n\nvoid setup() {\n Serial.begin(115200);\n COLOR myFavoriteColor = GREEN;\n if (myFavoriteColor == GREEN){\n Serial.println(\"My favorite color is green\");\n }\n}\n\nvoid loop () {}<\/pre>\n\n\n
Often it is not a matter of assigning specific values to the enum<\/code> elements, but simply of having an identifier, e.g:<\/p>\n<\/p>\nenum DAY_OF_THE_WEEK {\n MON, TUE, WED, THU, FRI, SAT, SUN\n};<\/pre>\n\n\n
Macros with passing variables<\/h3>\n\n
The #define<\/code> macros can also take variables. This still makes them a search and replace tool, but a more complex version. Here are some examples that also show a few pitfalls: <\/p>\n<\/p>\n\n#define A_PLUS_B(a,b) a+b\n#define A_PLUS_B_BETTER(a,b) (a+b)\n#define SQUARE(a) a*a\n#define SQUARE_BETTER(a) (a)*(a)\n#define MAP_RANGE(a) map(a, 0, 100, 0, -500)\n#define MAKE_STRING(a) #a\n#define MERGE(a,b) a##b\n\nvoid setup() {\n Serial.begin(115200);\n \/\/ delay(2000); \n \n Serial.print(\"3 * A_PLUS_B(1,2): \");\n Serial.println(3 * A_PLUS_B(1,2));\n \n Serial.print(\"3 * A_PLUS_B_BETTER(1,2): \");\n Serial.println(3 * A_PLUS_B_BETTER(1,2));\n\n Serial.print(\"SQUARE(1+2): \");\n Serial.println(SQUARE(1+2));\n\n Serial.print(\"SQUARE_BETTER(1+2): \");\n Serial.println(SQUARE_BETTER(1+2));\n\n Serial.print(\"MAP_RANGE(50): \");\n Serial.println(MAP_RANGE(50));\n\n Serial.print(\"MAKE_STRING(ABC123): \");\n Serial.println(MAKE_STRING(ABC123));\n \n String mergedString(MERGE(1,2)); \/\/ = String mergedString(12);\n Serial.print(\"MERGE(1,2) as String: \");\n Serial.println(mergedString);\n \n int mergedInt = MERGE(1,2); \/\/ = int mergedInt = 12;\n Serial.print(\"MERGE(1,2) as Integer: \");\n Serial.println(mergedInt); \n}\n\nvoid loop() {}<\/pre>\n<\/div>\n\n\n
Here is the output:<\/p>\n\n![\"Preprocessor](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2025\/02\/output_macros-1.png\")
<\/a>Output of macros_with_variables.ino<\/figcaption><\/figure>\n\nAnd here are a few explanations:<\/p>\n
\nA_PLUS_B(1,2)<\/code> is replaced by 1+2<\/code>.\n\n- Pitfall:
3*1+2<\/code> is 5!<\/li>\n<\/ul>\n<\/li>\nA_PLUS_B_BETTER(1,2)<\/code> is replaced by (1+2)<\/code>.\n\n- So:
3*(1+2) = 9<\/code>.<\/li>\n<\/ul>\n<\/li>\nSQUARE(1+2)<\/code> is replaced by 1+2*1+2<\/code> \u2192 pitfall!<\/li>\nSQUARE_BETTER(1+2)<\/code> is replaced by (1+2)*(1+2)<\/code> and returns the expected result.<\/li>\nMAP_RANGE(50)<\/code> is replaced by map(50, 0, 100, 0, -500);<\/code>.<\/li>\nMAKE_STRING(ABC123)<\/code> is replaced by the character string ABC123<\/code>.
\n- The hash character # preceeding the “a” is an operator that instructs the preprocessor to replace “a” with a character string.<\/li>\n<\/ul>\n<\/li>\n
MERGE(1,2)<\/code> is replaced by 12<\/code>.\n\n- The operator ## concatenates a and b.<\/li>\n
- The datatype of “12” is determined by the context (here: integer or string)<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n
macros vs. functions<\/h4>\n\n
In the last example, we passed integer values to the macro A_PLUS_B<\/code> as parameters. The cool thing is that the macro also works with float variables or strings. And the whole thing in a single-line definition! To achieve the same with a function would be a bit more complex. You can either solve this by overloading: <\/p>\n<\/p>\nvoid setup() {\n Serial.begin(115200);\n\n int aInt = 1;\n int bInt = 2; \n int cInt = aPlusB(aInt, bInt);\n Serial.print(\"aPlusB(aInt,bInt) = \");\n Serial.println(cInt);\n\n String aStr = \"1\";\n String bStr = \"2\";\n String cStr = aPlusB(aStr, bStr); \n Serial.print(\"aPlusB(aStr,bStr) = \");\n Serial.println(cStr); \n}\nvoid loop() {}\n\nint aPlusB(int a, int b) {\n return a+b;\n}\n\nString aPlusB(String a, String b) {\n return a+b;\n}<\/pre>\n\n\n
… or you apply templates:<\/p>\n<\/p>\n
void setup() {\n Serial.begin(115200);\n\n int aInt = 1;\n int bInt = 2; \n int cInt = aPlusB<int>(aInt, bInt);\n Serial.print(\"aPlusB(aInt,bInt) = \");\n Serial.println(cInt);\n\n String aStr = \"1\";\n String bStr = \"2\";\n String cStr = aPlusB<String>(aStr, bStr); \n Serial.print(\"aPlusB(aStr, bStr) = \");\n Serial.println(cStr); \n}\nvoid loop() {}\n\ntemplate <typename T>\nT aPlusB(T a, T b) { \n return a+b;\n}<\/pre>\n\n\n
Both variants provide the following output:<\/p>\n\n![\"Output](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2025\/02\/output_template_ino.png\")
Output of overload.ino and template.ino<\/figcaption><\/figure>\n\nOverloading and templates require more effort, but these variants are simply safer. The following, for example, is accepted by the macro A_PLUS_B<\/code> (or the compiler) without complaint: <\/p>\n<\/p>\nString a = \"1\";\nint b = 2;\nSerial.println(A_PLUS_B(a, b));<\/pre>\n\n\n
Maybe that’s what you wanted – or maybe it was an oversight.<\/p>\n\n
“Arduino macros”<\/h4>\n\n
The Arduino program package makes extensive use of macros. Some of them just shall make the program code easier to understand. For example, LOW and INPUT simply mean 0, OUTPUT and HIGH are 1. <\/p>\n\n
Then there is a series of “function-macros”. A simple example is the “min” macro, which returns the smaller of two values you passed to it: <\/p>\n
#define min(a,b) ((a)<(b)?(a):(b))<\/code><\/p>\n\nHowever, some of the macros are also quite complex and make use of other macros. One example of this is the “F” macro that you know from Serial.print(F(\"......\"));<\/code>: <\/p>\n\n#define F(string_literal) (reinterpret_cast<const __FlashStringHelper *>(PSTR(string_literal)))<\/code><\/p>\nIt uses the PSTR macro:<\/p>\n
#define PSTR(s) ((const PROGMEM char *)(s))<\/code><\/p>\n\nPredefined macros<\/h3>\n\n
Predefined macros are part of the preprocessor and are not defined via #define<\/code>. The most common predefined macros can be found in the following sketch: <\/p>\n<\/p>\nvoid setup() {\n Serial.begin(115200);\n Serial.print(\"Date: \");\n Serial.println(__DATE__); \/\/ Compiling date\n Serial.print(\"Time: \");\n Serial.println(__TIME__); \/\/ Compiling time\n Serial.print(\"File: \");\n Serial.println(__FILE__); \/\/ Compiled file\n Serial.print(\"Line: \");\n Serial.println(__LINE__); \/\/ Current line\n Serial.print(\"C++ : \");\n Serial.println(__cplusplus); \/\/ C++ Version (201103 = ISO C++ 2011)\n}\n\nvoid loop() {}<\/pre>\n\n\n
Here is the output:<\/p>\n\n![\"Predefined](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2025\/02\/output_predef_macros.png\")
<\/a>Output predef_macros.ino<\/figcaption><\/figure>\n\nConditional inclusion of code – #ifdef, #ifndef & Co<\/h2>\n\n
You can use #define<\/code> to include parts of the source code or have them ignored by the compiler.<\/p>\n#ifdef MACRO_NAME<\/code> checks whether MACRO_NAME<\/code> has been defined or not. If MACRO_NAME<\/code> has been defined, the subsequent lines of code are included. With #ifndef<\/code> it is exactly the opposite. <\/p>\nIn the simplest case, there is a #endif<\/code> in the rest of the source code, which ends the conditional inclusion. However, branching is also possible with #else<\/code> or #elif<\/code>. In principle, it is exactly as you know it from if<\/code>, else<\/code> and else if<\/code>. Nesting is also possible. However, this can quickly become confusing. <\/p>\nEquivalent to #ifdef MACRO_NAME<\/code> is #if defined(MACRO_NAME)<\/code>. This notation is used for logical operations, such as #if defined(NAME_1) && defined(NAME_2)<\/code>. You can also use #if<\/code> to check other logical conditions, such as #if A>B<\/code> or #if !(A==B)<\/code>. <\/p>\nAt the end, each #if<\/code>, #ifdef<\/code> or #ifndef<\/code> must be completed by #endif<\/code>. <\/p>\nA #undef MACRO_NAME<\/code> does what you would expect: it terminates the definition of MACRO_NAME<\/code>.<\/p>\n\nHere is an example sketch:<\/p>\n<\/p>\n
\n#define YIN\n#define YANG\n\nvoid setup() {\n Serial.begin(115200);\n \/\/ delay(2000); \n\n#ifdef YIN \/\/ or: #if defined(YIN)\n Serial.println(\"YIN is defined\");\n#elif defined(YANG)\n Serial.println(\"YIN is not defined, but YANG\");\n#endif\n\n#ifdef YANG\n Serial.println(\"YANG is defined\");\n#else \n Serial.println(\"YANG is not defined, YIN might be defined\");\n#endif\n\n#ifndef YANG\n Serial.println(\"YANG is not defined\");\n#endif\n\n#if defined(YIN) || defined(YANG)\n Serial.println(\"YIN and \/ or YANG are defined\");\n#endif\n\n#if defined(YIN) && defined(YANG)\n Serial.println(\"YIN and YANG are defined\");\n#elif defined(YIN) \n Serial.println(\"Only YIN is defined\");\n#endif\n\n#undef YANG\n#ifndef YANG\n Serial.println(\"YANG is not defined (anymore?)\");\n#endif\n\n}\n\nvoid loop() {}<\/pre>\n\u00a0<\/p>\n<\/div>\n
\n\n
The sketch provides the following output:<\/p>\n\n![\"Preprocessor](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2025\/02\/output_conditional_inclusion.png\")
<\/a>Output of conditional_inclusion.ino<\/figcaption><\/figure>\n\nIf you like, you can now comment out #define YIN<\/code> and \/ or #define YANG<\/code> and see how the output changes. <\/p>\n\nApplication example 1: Avoiding double reading of files<\/h3>\n\n
As a concrete example, let’s take a look at the SPI library file SPI.h of the Arduino Renesas package( you can find ithere<\/a> ). Many libraries of SPI-based components include SPI.h automatically. If you use several components, SPI.h could be read in several times. This is prevented by including the entire code in SPI.h with the following construction: <\/p>\n<\/p>\n#ifndef _SPI_H_INCLUDED\n#define _SPI_H_INCLUDED\n...... Code ........\n#endif\n<\/pre>\n\n\n
_SPI_H_INCLUDED<\/code> can only be defined once, and therefore the code can only be read once.<\/p>\n\nApplication example 2: Debugging<\/h3>\n\n
In the development phase of a project, it can be useful to output intermediate values, sensor settings, status data or similar on the serial monitor. On the other hand, Serial.print()<\/code> instructions in particular are both slow and memory-hungry. In such cases, it is advisable to “switch on” or “switch off” this code using conditional inclusion. There are many libraries that offer such a debug option. <\/p>\nHowever, there is another stumbling block here. Take a look at the following simple example. The main sketch uses the function sumUp()<\/code>, which is defined in sum.h and sum.cpp. sumUp()<\/code> simply adds three numbers. If DEBUG<\/code> is defined, the intermediate steps should be output, otherwise only the final result. <\/p>\n<\/p>\n\/\/ #define DEBUG\n\/\/ #include \"sum_config.h\"\n#include \"Arduino.h\"\n#ifndef _SUM_UP\n#define _SUM_UP\nint sumUp(int, int, int);\n#endif<\/pre>\n\n<\/p>\n
#include \"sum.h\"\nint sumUp(int s1, int s2, int s3){\n int result = 0;\n result += s1;\n#ifdef DEBUG\n Serial.print(\"Interim sum 1: \");\n Serial.println(result);\n#endif\n result += s2;\n#ifdef DEBUG\n Serial.print(\"Interim sum 2: \");\n Serial.println(result);\n#endif\n result += s3;\n return result;\n}\n<\/pre>\n\n<\/p>\n
#ifndef _SUM_CONF\n#define _SUM_CONF\n\/\/ uncomment the following line to activate DEBUG\n\/\/ #define DEBUG\n#endif<\/pre>\n\n\n
If you run the sketch as it is, you may expect the detailed output (bottom left), as DEBUG<\/code> is defined in the main sketch. However, you will get the output on the right. <\/p>\n\n![\"Output](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2025\/02\/output_sum_main.png\")
<\/a>Output of sum_main.ino with and without DEBUG<\/figcaption><\/figure>\n\nThe problem is that the preprocessor does not adhere to the sequence, but executes the #include<\/code> directives first. You can solve the problem by uncommenting #define DEBUG<\/code> in sumUp.h. To make it easier for the user and to minimize the risk of accidentally commenting out something incorrect, configuration files are often used in such cases. Therefore, alternatively uncomment #include \"sum_config.h\"<\/code> in sum.h and #define DEBUG<\/code> in sum_config.h. <\/p>\n\nApplication example 3: MCU-specific code<\/h3>\n\n
The Arduino ecosystem tries to make code as universal as possible, i.e. independent of the board or microcontroller (MCU) used. Nevertheless, there are things that do not work (equally) everywhere, such as SoftwareSerial. As a concrete example, let’s take a look at an example sketch of the DFRobotDFPlayerMini library(click here<\/a> for the full sketch). <\/p>\n<\/p>\n#if (defined(ARDUINO_AVR_UNO) || defined(ESP8266)) \/\/ Using a soft serial port\n#include <SoftwareSerial.h>\nSoftwareSerial softSerial(\/*rx =*\/4, \/*tx =*\/5);\n#define FPSerial softSerial\n#else\n#define FPSerial Serial1\n#endif<\/pre>\n\n\n
Only if the board is an AVR-based Arduino UNO (e.g. R3) or an ESP8266-based board, SoftwareSerial is included and the object softSerial<\/code> is created, otherwise Serial1<\/code> (HardwareSerial) is used. softSerial<\/code> or Serial1<\/code> are renamed to FPSerial<\/code> so that no distinction needs to be made between HardwareSerial and SoftwareSerial in the further course. <\/p>\nHowever, the example also shows that there are pitfalls. For example, the sketch does not work with an Arduino Nano (Classic) or an Arduino Pro Mini. They are not an Arduino UNO, they are not ESP8266-based, they do not have Serial1<\/code> and therefore fall through the cracks. I would rather have chosen __AVR_ATmega328P__<\/code> or ARDUINO_ARCH_AVR<\/code> as ARDUINO_AVR_UNO<\/code>. <\/p>\n\nWhere can I find the board or MCU #defines?<\/h4>\n\n
Unfortunately, there is not the one<\/em> big table where you can find all the definitions for the different architectures, boards and microcontrollers (at least I haven’t found one). But you can help yourself in other ways: <\/p>\nSet up the board of your choice in the Arduino IDE and compile any sketch. Then click on the window with the compiler messages and click CTRL\/f. Enter “-D” in the search window. This marks the places where definitions are located (their origin is: board.txt and platform.txt). You might have to scroll to the right to find the marked locations. <\/p>\n
For a WEMOS D1 Mini Board I found the definitions in the following line (shortened output):<\/p>\n
C:\\Users\\Ewald\\AppData\\Local\\Arduino15\\packages\\esp8266\\……..-DESP8266<\/span>…..-DARDUINO_ESP8266_WEMOS_D1MINI <\/span>-DARDUINO_ARCH_ESP8266<\/span>…..<\/p>\n
![\"\"](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2025\/02\/output_compiler_wemos_d1_mini-1.png\")
<\/a>