Include Directive

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.

#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 a special instruction to the compiler and is not a line of code. Only C statements require a semicolon at the end.

1 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.

2 Header File is in Project Directory

#include "filename.h"

If the header file is inside your project's directory, all you need is to 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.

3 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 operating system independent and may be used on Windows machines that traditionally use a backslash '\' as the directory separator. A backslash will work here, 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.

4 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 OSX machines. Using this form will harm your ability to use the file on different platforms and should generally be avoided.

#include Example

Below is one possible way an include file might be used. 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.

main.h

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.

main.c

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.

© 2016 Microchip Technology, Inc.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.