#include 指令 (C/C++)#include Directive (C/C++)

告知预处理器将已指定文件的内容视为它们在源程序中指令出现处出现的方式处理。Tells the preprocessor to treat the contents of a specified file as if they appear in the source program at the point where the directive appears.

语法Syntax

#include  "path-spec"
#include  <path-spec>

备注Remarks

您可以将常数和宏定义编入包含文件,然后使用 #include指令将它们添加到任何源文件。You can organize constant and macro definitions into include files and then use #include directives to add them to any source file. 包含文件还可用于合并外部变量和复杂数据类型的声明。Include files are also useful for incorporating declarations of external variables and complex data types. 在为此目的而创建的包含文件中,类型只能定义和命名一次。The types may be defined and named only once in an include file created for that purpose.

路径规范可能可跟目录规范是文件名。The path-spec is a file name that may optionally be preceded by a directory specification. 文件名必须命名现有文件。The file name must name an existing file. 语法路径规范取决于其编译该程序的操作系统。The syntax of the path-spec depends on the operating system on which the program is compiled.

有关如何通过使用编译的 c + + 应用程序中引用程序集信息/clr,请参阅#usingFor information about how to reference assemblies in a C++ application that's compiled by using /clr, see #using.

两种语法形式都会导致指令被替换为指定包含文件的整个内容。Both syntax forms cause that directive to be replaced by the entire contents of the specified include file. 两种形式之间的区别在于,在未完全指定路径时预处理器搜索标头文件的顺序。The difference between the two forms is the order in which the preprocessor searches for header files when the path is incompletely specified. 下表显示了这两种语法形式之间的差异。The following table shows the difference between the two syntax forms.

语法形式Syntax Form 操作Action
带引号的形式Quoted form 预处理器按以下顺序搜索包含文件:The preprocessor searches for include files in this order:

1) 中包含的文件所在的目录 #include语句。1) In the same directory as the file that contains the #include statement.

2) 在当前打开的目录包含文件,打开它们的相反顺序。2) In the directories of the currently opened include files, in the reverse order in which they were opened. 搜索从父包含文件的目录中开始进行,然后继续向上到任何祖父包含文件的目录。The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files.

3) 沿每个指定的路径 /I编译器选项。3) Along the path that's specified by each /I compiler option.

4) 跟随 INCLUDE 环境变量指定的路径。4) Along the paths that are specified by the INCLUDE environment variable.
尖括号形式Angle-bracket form 预处理器按以下顺序搜索包含文件:The preprocessor searches for include files in this order:

1) 沿每个指定的路径 /I编译器选项。1) Along the path that's specified by each /I compiler option.

2) 当编译时在命令行,跟随 INCLUDE 环境变量指定的路径。2) When compiling occurs on the command line, along the paths that are specified by the INCLUDE environment variable.

只要找到具有给定名称的文件,预处理器就会停止搜索。The preprocessor stops searching as soon as it finds a file that has the given name. 如果将两个双引号之间的包含文件的完整明确的路径规范 (""),则预处理器只搜索该路径说明并忽略标准目录。If you enclose a complete, unambiguous path specification for the include file between double quotation marks (" "), the preprocessor searches only that path specification and ignores the standard directories.

如果用双引号括起来的文件名是不完整的路径规格,则预处理器将首先搜索“父”文件的目录。If the file name that's enclosed in double quotation marks is an incomplete path specification, the preprocessor first searches the "parent" file's directory. 父文件是包含的文件 #include指令。A parent file is the file that contains the #include directive. 例如,如果包括名为的文件file2中名为的文件file1file1为父文件。For example, if you include a file named file2 in a file named file1, file1 is the parent file.

包含文件可以"嵌套";即 #include指令可以出现在由另一个名为的文件 #include指令。Include files can be "nested"; that is, an #include directive can appear in a file that's named by another #include directive. 例如, file2可能包括file3For example, file2 could include file3. 在这种情况下, file1还是会引起的父file2,但它会的"祖父" file3In this case, file1 would still be the parent of file2, but it would be the "grandparent" of file3.

当嵌套了包含文件并从命令行开始编译时,目录搜索会从父文件的目录开始,然后在所有祖父文件的目录中继续进行。When include files are nested and when compiling occurs on the command line, directory searching begins with the directories of the parent file and then proceeds through the directories of any grandparent files. 即,搜索将相对于包含当前正在处理的源的目录开始。That is, searching begins relative to the directory that contains the source that's currently being processed. 如果找不到该文件,则搜索会移动到由指定的目录/I (附加包含目录)编译器选项。If the file is not found, the search moves to directories that are specified by the /I (Additional include directories) compiler option. 最后,将搜索 INCLUDE 环境变量指定的目录。Finally, the directories that are specified by the INCLUDE environment variable are searched.

从 Visual Studio 开发环境中,将忽略 INCLUDE 环境变量。From the Visual Studio development environment, the INCLUDE environment variable is ignored. 有关如何设置搜索包含文件的目录信息 — 这也适用于 LIB 环境变量,请参阅VC + + Directories Property PageFor information about how to set the directories that are searched for include files—this also applies to the LIB environment variable—see VC++ Directories Property Page.

此示例使用尖括号显示文件包含:This example shows file inclusion by using angle brackets:

#include <stdio.h>

此示例将名为 STDIO.H 文件的内容添加到源程序。This example adds the contents of the file named STDIO.H to the source program. 尖括号会促使预处理器搜索 INCLUDE 环境变量指定 STDIO 的目录。H 之后它将搜索由指定的目录, /I编译器选项。The angle brackets cause the preprocessor to search the directories that are specified by the INCLUDE environment variable for STDIO.H, after it searches directories that are specified by the /I compiler option.

下一个示例用引号形式显示文件包含:The next example shows file inclusion by using the quoted form:

#include "defs.h"

此示例将 DEFS.H 指定的文件的内容添加到源程序。This example adds the contents of the file that's specified by DEFS.H to the source program. 双引号意味着,预处理器将首先搜索包含父源文件的目录。The quotation marks mean that the preprocessor first searches the directory that contains the parent source file.

包含文件的嵌套可扩展至 10 个级别。Nesting of include files can continue up to 10 levels. 当嵌套 #include是处理,预处理器将继续到原始的源文件中插入封闭的包含文件。When the nested #include is processed, the preprocessor continues to insert the enclosing include file into the original source file.

Microsoft 专用Microsoft Specific

若要查找可包含的源文件,预处理器首先搜索由指定的目录 /I编译器选项。To locate includable source files, the preprocessor first searches the directories that are specified by the /I compiler option. 如果 /I选项不存在或失败,则预处理器使用 INCLUDE 环境变量来查找在尖括号内包含文件。If the /I option is not present or fails, the preprocessor uses the INCLUDE environment variable to find any include files within angle brackets. INCLUDE 环境变量和 /I编译器选项可以包含多个路径,之间用分号分隔 (;)。The INCLUDE environment variable and /I compiler option can contain multiple paths, separated by semicolons (;). 如果多个目录显示为的一部分 /I选项,或在 INCLUDE 环境变量,预处理器搜索它们的显示顺序。If more than one directory appears as part of the /I option or within the INCLUDE environment variable, the preprocessor searches them in the order in which they appear.

例如,命令For example, the command

CL /ID:\MSVC\INCLUDE MYPROG.C

会促使预处理器搜索包含文件(如 STDIO.H)的目录 D:\MSVC\INCLUDE\。causes the preprocessor to search the directory D:\MSVC\INCLUDE\ for include files such as STDIO.H. 命令The commands

SET INCLUDE=D:\MSVC\INCLUDE
CL MYPROG.C

具有同样的作用。have the same effect. 如果两组搜索都失败,则会生成严重的编译器错误。If both sets of searches fail, a fatal compiler error is generated.

如果为路径包含冒号的包含文件指定完整的文件名(例如,F:\MSVC\SPECIAL\INCL\TEST.H),则预处理器会遵循该路径。If the file name is fully specified for an include file that has a path that includes a colon (for example, F:\MSVC\SPECIAL\INCL\TEST.H), the preprocessor follows the path.

包含文件指定为#include "path-spec",目录搜索父文件的目录开始,然后在继续进行任何祖父文件的目录。For include files that are specified as #include "path-spec", directory searching begins with the directory of the parent file and then proceeds through the directories of any grandparent files. 也就是说,相对于包含包含的源文件的目录搜索开始 #include正在处理的指令。That is, searching begins relative to the directory that contains the source file that contains the #include directive that's being processed. 如果没有祖父文件且没有找到该文件,则搜索会像文件名括在尖括号中一样继续进行。If there is no grandparent file and the file has not been found, the search continues as if the file name were enclosed in angle brackets.

结束 Microsoft 专用END Microsoft Specific

请参阅See Also

预处理器指令Preprocessor Directives
/I (附加包含目录)/I (Additional include directories)