C Programming Include Directive

Last modified by Microchip on 2024/06/24 06:29

Sometimes variables and other program elements are declared in a separate file called a header file. Header file names customarily end in .h.

While it is not always a good idea to declare variables in a header file (we'll see why this can be a problem in the discussion on multi-file projects), it is not technically wrong to do so and is even required sometimes (external variables). Declaring non-external variables in header files is sometimes done by those who simply want to eliminate clutter in their source files.

Back to top

#include Syntax

Header files are associated with a program through the #include directive. There are four ways the #include directive may be used. Note that there is never a semicolon ";" at the end of these. #include is a directive or special instruction to the compiler and is not a line of code. Only C statements require a semicolon at the end.

Back to top

Header File is in Compiler Path

#include <filename.h>

Every C compiler comes with a whole series of header files, most of which are for working with the C Standard Library which contains functions and utilities that are a standard part of the language but not built into the language itself. In the case of the MPLAB® XC Compilers, these files are installed along with the compiler in a subdirectory called Include. As long as you use the angle brackets around the filename, you don't need to specify the full path to the file, the compiler will know where to look for it.

Back to top

Header File is in Project Directory

#include "filename.h"

If the header file is inside your project's directory, all you need to do is enclose the filename in double-quotes. Some integrated development environments like MPLAB® X IDE let you specify include directories as part of your project. This tells the IDE (and the IDE tells the compiler) that these directories should be treated as if their files were in your project's directory. If you have specified any include directories, you can use this form to include files from them.

Back to top

Header File is in Project Subdirectory

#include "subdirectory_name/filename.h"

Although it is usually better to add a project subdirectory to the IDE's include directories, this form is still widely used. If the header file resides in a directory inside your project directory, you can use this form with as many subdirectory levels as necessary.

Note that a forward slash / is used. The forward slash is independent of the operating system and may be used on Window® machines that traditionally use a backslash \ as the directory separator. A backslash will work but only on a Windows machine. In the interest of portability across platforms, the forward slash is the preferred syntax. This also works for subdirectories of any directory you specified in your IDE's Include Directories settings.

Back to top

Header File is in a Specific Location Outside of Project Directory

#include "C:\path\to\filename.h"

Finally, in some cases, you may want to specify a file at a very specific location on your machine. However, it is better to add the file's location in your IDE's Include Directories settings.

When using this form, you often need to use paths that are unique to the operating system you are running on. Paths on Windows machines are specified very differently from those on Linux® and Mac OS X® machines. Using this form will harm your ability to use the file on different platforms and should generally be avoided.

Back to top

#include Example

The following is one possible way to use an include file. This exact scenario isn't very common but it serves to illustrate the point of how include files behave. Most of the time, header files are used for function prototypes and external variable declarations, which we will cover later in the class.

1   unsigned int a;
2   unsigned int b;
3   unsigned int c;

The contents of main.h above are included in the main.c file below by the #include directive on line 1 of main.c. This has the same effect as if you copied the contents of main.h and pasted them in main.c in place of the #include directive on line 1.

1    #include "main.h"
3    int main(void)
4   {
5         a = 5;
6         b = 2;
7         c = a+b;
8    }

The two files above are exactly equivalent to the one file below. In fact, after the C preprocessor is run on the project, this is how the file would look when it is passed on to the compiler.

1    unsigned int a;
2    unsigned int b;
3    unsigned int c;
5    int main(void)
6    {
7          a = 5;
8          b = 2;
9          c = a+b;
10    }

Back to top