Include directive

Many programming languages and other computer files have a directive, often called include, import, or copy, that causes the contents of the specified file to be inserted into the original file. These included files are called header files or copybooks. They are often used to define the physical layout of program data, pieces of procedural code, and/or forward declarations while promoting encapsulation and the reuse of code or data.

Header files

In computer programming, a header file is a file that allows programmers to separate certain elements of a program's source code into reusable files. Header files commonly contain forward declarations of classes, subroutines, variables, and other identifiers. Programmers who wish to declare standardized identifiers in more than one source file can place such identifiers in a single header file, which other code can then include whenever the header contents are required. This is to keep the interface in the header separate from the implementation.^[1]

The C standard library and the C++ standard library traditionally declare their standard functions in header files.

Some newer compiled languages (such as Java and C#) do not use forward declarations; identifiers are recognized automatically from source files and read directly from dynamic library symbols. This means header files are not needed.

Purpose

The include directive allows libraries of code to be developed which help to:

ensure that everyone uses the same version of a data layout definition or procedural code throughout a program,
easily cross-reference where components are used in a system,
easily change programs when needed (only one file must be edited), and
save time by reusing data layouts.

Example

An example situation which benefits from the use of an include directive is when referring to functions in a different file. Suppose there is some C source file containing a function add, which is referred to in a second file by first declaring its external existence and type (with a function prototype) as follows:

int add(int, int);

int triple(int x)
{
    return add(x, add(x, x));
}

One drawback of this approach is that the function prototype must be present in all files that use the function. Another drawback is that if the return type or arguments of the function are changed, all of these prototypes would need to be updated. Putting the prototype in a single, separate file avoids these issues. Assuming the prototype is moved to the file add.h, the second source file can then become:

#include "add.h"

int triple(int x)
{
    return add(x, add(x,x));
}

Now, every time the code is compiled, the latest function prototypes in add.h will be included in the files using them, avoiding potential errors.

Language support

C/C++

In the C and C++ programming languages, the #include preprocessor directive causes the compiler to replace that line with the entire text of the contents of the named source file (if included in quotes: "") or named header (if included in angle brackets: <>);^[2] a header doesn't need to be a source file.^[3] Inclusion continues recursively on these included contents, up to an implementation-defined nesting limit. Headers need not have names corresponding to files: in C++ standard headers are typically identified with words, like "vector", hence #include <vector>, while in C standard headers have identifiers in the form of filenames with a ".h" extension, as in #include <stdio.h>. A "source file" can be any file, with a name of any form, but is most commonly named with a ".h" extension and called a "header file" (sometimes ".hpp" or ".hh" to distinguish C++ headers), though files with .c, .cc, and .cpp extensions may also be included (particularly in the single compilation unit technique), and sometimes other extensions are used.

These two forms of #include directive can determine which header or source file to include in an implementation-defined way. In practice, what is usually done is that the angle-brackets form searches for source files in a standard system directory (or set of directories), and then searches for source files in local or project-specific paths (specified on the command line, in an environment variable, or in a Makefile or other build file), while the form with quotes does not search in a standard system directory, only searching in local or project-specific paths.^[4] In case there is no clash, the angle-brackets form can also be used to specify project-specific includes, but this is considered poor form. The fact that headers need not correspond to files is primarily an implementation technicality, and is used to omit the .h extension in including C++ standard headers; in common use, "header" means "header file".

For example:

#include <stdio.h>  // Include the contents of the standard header 'stdio.h' (probably a file 'stdio.h').
#include <vector>  // Include the contents of the standard header 'vector' (probably a file 'vector.h').
#include "user_defined.h"  // Include the contents of the file 'user_defined.h'.

In C and C++, problems may be faced if two (or more) include files contain the same third file. One solution is to avoid include files from including any other files, possibly requiring the programmer to manually add extra include directives to the original file. Another solution is to use include guards.^[5]

Since C++20, headers can also be imported as header units, that is, separate translation units synthesized from a header.^[6] They are meant to be used alongside modules. The syntax used in that case is

export_optional import header-name;

For example:

import <stdio.h>; // supporting this is optional
import <vector>; // supporting this is mandated by the standard
export import "user_defined.h";

Header units are provided for all the C++ standard library headers.^[7]

COBOL

COBOL (and also RPG IV) allows programmers to copy copybooks into the source of the program in a similar way to header files, but it also allows for the replacement of certain text in them with other text. The COBOL keyword for inclusion is COPY, and replacement is done using the REPLACING ... BY ... clause. An include directive has been present in COBOL since COBOL 60, but changed from the original INCLUDE^[8] to COPY by 1968.^[9]

Fortran

Fortran does not require header files per se. However, Fortran 90 and later have two related features: include statements and modules. The former can be used to share a common file containing procedure interfaces, much like a C header, although the specification of an interface is not required for all varieties of Fortran procedures. This approach is not commonly used; instead, procedures are generally grouped into modules that can then be referenced with a use statement within other regions of code. For modules, header-type interface information is automatically generated by the compiler and typically put into separate module files, although some compilers have placed this information directly into object files. The language specification itself does not mandate the creation of any extra files, even though module procedure interfaces are almost universally propagated in this manner.

Pascal

Most Pascal compilers support the $i or $include compiler directive, in which the $i or $include directive immediately follows the start of a comment block in the form of

{$i filename.pas}
(*$I filename.inc*)
{$include filename.inc}
(*INCLUDE filename.pas*)

Where the $i or $include directive is not case sensitive, and filename.pas or filename.inc is the name of the file to be included. (It has been common practice to name Pascal's include files with the extension .inc, but this is not required.) Some compilers, to prevent unlimited recursion, limit invoking an include file to a certain number, prohibit invoking itself or any currently open file, or are limited to a maximum of one include file at a time, e.g. an include file cannot include itself or another file. However, the program that includes other files can include several, just one at a time.

PHP

In PHP, the include directive causes another PHP file to be included and evaluated.^[10] Similar commands are require, which upon failure to include will produce a fatal exception and halt the script,^[11] and include_once and require_once, which prevent a file from being included or required again if it has already been included or required, avoiding the C's double inclusion problem.

Other languages

There are many forms of the include directive, such as:

include ... (Fortran, MASM)
 (HTML SSI)
import ...; (Java)
import ... from ... (JavaScript as in ECMAScript)
var ... = require("...") (JavaScript with CommonJS)
<%@ include ... %> (JSP)
{$I ...} (UCSD Pascal, Turbo Pascal)
%include ... (PL/I)
import ... (Python)
/COPY QCPYLESRC,QBC (RPG IV – first argument is the filename, second argument is the copybook)
use ...; (Rust)
using ...; (C#)
local ... = require("...") (Lua)
import ...; (D)

Modern languages (e.g. Haskell and Java) tend to avoid copybooks or includes, preferring modules and import/export systems for namespace control. Some of these languages (such as Java and C#) do not use forward declarations and, instead, identifiers are recognized automatically from source files and read directly from dynamic library symbols (typically referenced with import or using directives), meaning header files are not needed.

References

^ Alan Griffiths (2005). "Separating Interface and Implementation in C++". ACCU. Retrieved 2013-05-07.
^ C11 standard, 6.10.2 Source file inclusion, pp. 164–165
^ C11 standard, 7.1.2 Standard headers, p. 181, footnote 182: "A header is not necessarily a source file, nor are the < and > delimited sequences in header names necessarily valid source file names.
^ Stallman, Richard M. (July 1992). "The C Preprocessor" (PDF). Archived from the original (PDF) on 4 September 2012. Retrieved 19 February 2014.
^ Pike, Rob (21 Feb 1989), Notes on programming in C, Cat-v document archive, retrieved 9 Dec 2011
^ "Merging Modules - P1103R3" (PDF).
^ "P1502R1 - Standard library header units for C++20".
^ "COBOL Initial Specifications for a COmmon Business Oriented Language" (PDF). Department of Defense. April 1960. p. IX-9. Archived from the original (PDF) on 12 February 2014. Retrieved 11 February 2014.
^ "The COPY Statement". CODASYL COBOL Journal of Development 1968. July 1969. LCCN 73601243.
^ "include". php.net. The PHP Group. Retrieved 20 February 2014.
^ "require". php.net. The PHP Group. Retrieved 20 February 2014.

External links

[1] Alan Griffiths (2005). "Separating Interface and Implementation in C++". ACCU. Retrieved 2013-05-07.

[2] C11 standard, 6.10.2 Source file inclusion, pp. 164–165

[3] C11 standard, 7.1.2 Standard headers, p. 181, footnote 182: "A header is not necessarily a source file, nor are the < and > delimited sequences in header names necessarily valid source file names.

[4] Stallman, Richard M. (July 1992). "The C Preprocessor" (PDF). Archived from the original (PDF) on 4 September 2012. Retrieved 19 February 2014.

[5] Pike, Rob (21 Feb 1989), Notes on programming in C, Cat-v document archive, retrieved 9 Dec 2011

[6] "Merging Modules - P1103R3" (PDF).

[7] "P1502R1 - Standard library header units for C++20".

[8] "COBOL Initial Specifications for a COmmon Business Oriented Language" (PDF). Department of Defense. April 1960. p. IX-9. Archived from the original (PDF) on 12 February 2014. Retrieved 11 February 2014.

[9] "The COPY Statement". CODASYL COBOL Journal of Development 1968. July 1969. LCCN 73601243.

[10] "include". php.net. The PHP Group. Retrieved 20 February 2014.

[11] "require". php.net. The PHP Group. Retrieved 20 February 2014.

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]