Creating and Including Header Files
Although it's feasible to write an entire advanced C program in a single source file, accomplishing that task would be unnecessarily tedious and edits would require more effort than otherwise necessary. By using the C preprocessor, you can break complex applications down into multiple files, while still retaining the same functionality.
The #include directive provides a mechanism for including the contents of another file while compiling a primary file. You've seen this many times with the stdio.h include.
Quite often, these included files are in separate source files that exist solely to provide function declarations, macro definitions, and other nonfunction code. These included files are called header files.
Two common kinds of header files are system header files and your own header files. System header files define macros (both constants and functions) that allow your C code to work on a particular operating system. When your program needs to use one of those macros, you must include the appropriate header file so the compiler can figure out what you're talking about.
You include system header files by using angle brackets < > around the filename in the directive. This tells the preprocessor to grab that code out of the standard location for your operating system:
#include <stdio.h> #include <ctype.h>
You include your own header files by using double quotation marks around the filename:
#include "myfile.h"
The preprocessor will search the user's source code directories for the file. Or, if a directory is specified, the preprocessor will find the file more quickly. Both of these examples give the file's relative location:
#include "./myfile.h" #include "includes/myfile.h"
Over the next few pages, you'll learn how to create and include your own header files, thus making your applications more modular and easier to maintain.
Creating header files
A header file is just a standard text file, given the .h extension to signify its header nature. Normally you would place these headers files in the same directory as the rest of the application files or in their own special folder within the application's directory (Figure 8.11).
Figure 8.11. Maintaining a logical directory structure is even more important as you begin developing your own header files.
You can use header files to store any pieces of code that the application needs. For example, a header file might define various macros, contain additional #include directives, create function declarations, and so on.
Our next example will place three mathematical macros in their own header file, so that they may be made available to multiple applications with relative ease.
To create and include a header file
1. | Create a new text file in your IDE or text editor. |
2. | Add detailed comments explaining the purpose of this file (Script 8.5): /* * my_math.h - Script 8.5 * This header file defines three Script 8.5. Creating your own header files like this one allows you to place several directives in one common location.
It's a good idea with header files to include even more comments than your standard C files, since the header files may not be apparently related to an application. You can mention such things as creation date, purpose of the file, who created it, the last time it was modified, what contingencies exist, and so forth. |
3. | Add a #define directive to create the MIN macro: #define MIN(X,Y) ( ((X) < (Y)) ? (X) This is the same code that was used in the previous example, but now it's in its own file. |
4. | Add another #define directive to create a MAX macro: #define MAX(X,Y) ( ((X) > (Y)) ? (X) This macro's code is exactly like MIN's, except that it checks if X is greater than Y instead of less than. |
5. | |
6. | Save the file as my_math.h. |
macros.
*
* Created by Larry Ullman - July
2004.
*
*/
: (Y) )
: (Y) )
✓ Tips
Although included files can contain any fragments of code, they are typically reserved for declaring functions, defining macros, and declaring variables, structs (user-defined data types), and constants.
For good examples of how to separate your functions and declarations into header and source files, take a look at the various system header files on your computer or available for viewing online (see Appendix B, “Resources”).
Although this chapter demonstrates how to create and include your own header files, don't forget that the #include directive is most often used to incorporate C header files that are part of the base C library.