The Preprocessor

The preprocessor is a program that performs simple text substitutions on your source code based on a set of commands called preprocessor directives which are those lines beginning with the # symbol in your C or C++ source code. Generally you will not use the preprocessor directly but it will be called by gcc for each C and C++ source file before the compiler is called. The preprocessor for the GNU compiler suite is called cpp.

For more information on what the preprocessor does see the section on the preprocessor in the basics of programming pages.

You will not run the preprocessor directly, but you can pass arguments and options to it from the gcc command line. The following sections describe the most common cases where you will want to do this.

Telling the Preprocessor Where to Find Include Files

You can tell the preprocessor to search extra directories for include files using the -I option or the C_INCLUDE_PATH and CPLUS_INCLUDE_PATH environment variables.

The following command line will tell the preprocessor to search the directory /src/bar/include (\src\bar\include on the current drive in DOS-speak) and the directory include under the current directory for include files used by foo.c. These directories will be searched before the system default directories.

gcc -c -o foo.o -I/src/bar/include -Iinclude foo.c

Including the following lines in Windows 95/98 autoexec.bat file, or setting the equivalent environment variables in the control panel for Windows NT, will search /extra/include/c for include files used by C source files, /extra/include/plus for include files used by C++ source files, and /extra/include/both for include files used by either C or C++. These directories will be searched after any directories specified with the -I option, but before the standard system directories.

SET C_INCLUDE_PATH=/extra/include/c;/extra/include/both
SET CPLUS_INCLUDE_PATH=/extra/include/plus;/extra/include/both

Defining Constants at Compile Time

You can tell the preprocessor to act like you included a #define preprocessor directive as the first line of every source file you are compiling by using the -D option.

gcc -c -o foo.o -DBAR foo.c

The above command line will have the same effect on the compilation of foo.c as if you added the line

#define BAR 1

to the top of foo.c.

gcc -c -o foo.o -DBAZ=fuz foo.c

The above command line will have the same effect as if you added the line

#define BAZ fuz

to the top of foo.c.