#include directive (C/C++)
Tells the preprocessor to include the contents of a specified file at the point where the directive appears.
Syntax
#include « path-spec «
#include path-spec >
Remarks
You can organize constant and macro definitions into include files (also known as header 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.
For information about how to reference assemblies in a C++ application that’s compiled by using /clr , see #using directive.
Both syntax forms cause the #include directive to be replaced by the entire contents of the specified file. The difference between the two forms is the order of the paths that the preprocessor searches when the path is incompletely specified. The following table shows the difference between the two syntax forms.
1) In the same directory as the file that contains the #include statement.
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) Along the path that’s specified by each /I compiler option.
1) Along the path that’s specified by each /I compiler option.
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. A parent file is the file that contains the #include directive. For example, if you include a file named file2 in a file named file1, file1 is the parent file.
Include files can be nested: An #include directive can appear in a file that’s named by another #include directive. For example, file2 could include file3. In 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 in the directory of the parent file. Then it 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. If the file isn’t found, the search moves to directories that are specified by the /I (Additional include directories) compiler option. Finally, the directories that are specified by the INCLUDE environment variable are searched.
Within the Visual Studio development environment, the INCLUDE environment variable is ignored. The values specified in the project properties for include directories are used instead. For more information about how to set the include directories in Visual Studio, see Include Directories and Additional Include Directories.
This example shows file inclusion by using angle brackets:
The example adds the contents of the file named stdio.h to the source program. 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:
The 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.
Nesting of include files can continue up to 10 levels. When processing of the nested #include is finished, the preprocessor continues to insert the enclosing parent include file into the original source file.
Microsoft-specific
To locate the source files to include, the preprocessor first searches the directories specified by the /I compiler option. If the /I option isn’t present, or if it fails, the preprocessor uses the INCLUDE environment variable to find any include files within angle brackets. The INCLUDE environment variable and /I compiler option can contain multiple paths, separated by semicolons ( ; ). 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.
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.
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.
For include files that are specified as #include «path-spec» , directory search begins in the directory of the parent file and then proceeds through the directories of any grandparent files. That is, the search begins relative to the directory that contains the source file that’s being processed. If there’s no grandparent file and the file still isn’t found, the search continues as if the file name were enclosed in angle brackets.
END Microsoft-specific
#include директива (C/C++)
Указывает препроцессору включить содержимое указанного файла в точку, где появляется директива.
Синтаксис
#include « path-spec «
#include path-spec >
Комментарии
Определения констант и макросов можно упорядочить во включаемые файлы (также называемые файлами заголовков), а затем использовать #include директивы для их добавления в любой исходный файл. Включаемые файлы также позволяют внедрять объявления внешних переменных и сложных типов данных. Типы можно определять и именовать только один раз во включаемом файле, созданном с этой целью.
Спецификация пути — это имя файла, которому при необходимости может предшествовать спецификация каталога. Имя файла должно указывать на существующий файл. Синтаксис path-spec зависит от операционной системы, в которой компилируется программа.
Сведения о том, как ссылаться на сборки в приложении C++, скомпилированном с помощью /clr , см. в разделе #using Директива .
Обе формы синтаксиса приводят к замене #include директивы всем содержимым указанного файла. Разница между двумя формами заключается в порядке путей, которые выполняет препроцессор, когда путь указан не полностью. В приведенной ниже таблице показывается различие между этими формами синтаксиса.
1) В том же каталоге, что и файл, содержащий инструкцию #include .
2) В каталоги открытых в настоящее время файлов включите в обратном порядке, в котором они были открыты. Поиск начинается в каталоге родительского включаемого файла, а затем выполняется в каталогах всех включаемых файлов-прародителей.
3) По пути, заданному каждым /I параметром компилятора.
1) По пути, указанному каждым /I параметром компилятора.
Как только препроцессор найдет файл с заданным именем, поиск останавливается. Если вы заключаете полную, однозначную спецификацию пути для включаемого файла в двойные кавычки ( » » ), препроцессор выполняет поиск только этой спецификации пути и игнорирует стандартные каталоги.
Если имя файла, заключенное в двойные кавычки, является неполным спецификацией пути, препроцессор сначала выполняет поиск в каталоге родительского файла. Родительский файл — это файл, содержащий директиву #include . Например, если включить файл с именем file2 в файл с именем file1, file1 будет родительским файлом.
Включаемые файлы могут быть вложенными: #include директива может отображаться в файле с именем другой #include директивы. Например, file2 может включать file3. В этом случае file1 по-прежнему будет родительским для file2, но это будет бабушка и дедушка file3.
Если вложенные файлы и компиляция выполняется в командной строке, поиск по каталогу начинается в каталоге родительского файла. Затем он проходит через каталоги любых файлов бабушек и дедушек. Таким образом, поиск начинается относительно каталога, в котором находится исходный файл, обрабатываемый в текущий момент. Если файл не найден, поиск перемещается в каталоги, указанные параметром компилятора /I (Дополнительные каталоги включения). Наконец, выполняется поиск каталогов, указанных в переменной INCLUDE среды.
В среде INCLUDE разработки Visual Studio переменная среды игнорируется. Вместо этого используются значения, указанные в свойствах проекта для каталогов include. Дополнительные сведения о настройке каталогов включения в Visual Studio см. в разделах Каталоги включения и Дополнительные каталоги включения.
В приведенном ниже примере демонстрируется включение файлов с помощью угловых скобок:
В примере содержимое файла с именем stdio.h добавляется в исходную программу. Угловые скобки приводят к тому, что препроцессор выполняет поиск каталогов, указанных INCLUDE переменной среды для stdio.h , после поиска каталогов, указанных параметром /I компилятора.
В следующем примере демонстрируется включение файлов, заданных в кавычках:
В примере содержимое файла, указанного параметром defs.h , добавляется в исходную программу. Кавычки означают, что препроцессор сначала попытается найти этот файл в каталоге, содержащем родительский исходный файл.
Для включаемых файлов поддерживается до 10 уровней вложения. Когда обработка вложенного #include объекта завершена, препроцессор продолжает вставлять вложенный родительский файл include в исходный файл.
Только для систем Майкрософт
Чтобы найти исходные файлы для включения, препроцессор сначала выполняет поиск в каталогах, указанных параметром /I компилятора. /I Если параметр отсутствует или если он завершается сбоем, препроцессор использует INCLUDE переменную среды для поиска включаемого файла в угловых скобках. Переменная INCLUDE среды и /I параметр компилятора могут содержать несколько путей, разделенных точкой с запятой ( ; ). Если в параметре или в INCLUDE переменной /I среды отображается несколько каталогов, препроцессор ищет их в том порядке, в котором они отображаются.
Представим себе следующую команду:
приводит к тому, что препроцессор выполняет поиск в каталоге D:\msvc\include\ для включения файлов, таких как stdio.h . Ниже еще один пример:
SET INCLUDE=D:\msvc\include CL myprog.c Эта инструкция действуют точно так же. Если найти файл в обоих наборах каталогов не удастся, возникает неустранимая ошибка компилятора.
Если имя файла полностью указано для включаемого файла с путем к двоеточию (например, F:\MSVC\SPECIAL\INCL\TEST.H ), препроцессор следует за путем.
Для включаемых файлов, указанных как #include «path-spec» , поиск в каталоге начинается в каталоге родительского файла, а затем переходит к каталогам всех файлов бабушки и дедушки. То есть поиск начинается относительно каталога, содержащего исходный файл, который обрабатывается. Если файл бабушки и дедушки не найден, поиск продолжится так, как если бы имя файла было заключено в угловые скобки.
КОНЕЦ Только для систем Майкрософт