Директива #include (C/C++)
Указывает препроцессору, что содержимое заданного файла необходимо обработать так, как если бы оно находилось в исходной программе в той точке, в которой располагается эта директива.
#include "path-spec"
#include <path-spec>
Заметки
Определения констант и макросов можно объединить во включаемые файлы, а затем добавить их в исходный файл при помощи директивы #include. Включаемые файлы также позволяют внедрять объявления внешних переменных и сложных типов данных. Типы можно определять и именовать только один раз во включаемом файле, созданном с этой целью.
Параметр path-spec означает имя файла, перед которым может находиться спецификация каталога (необязательно). Имя файла должно указывать на существующий файл. Синтаксис параметра path-spec зависит от того, в какой операционной системе компилируется программа.
Сведения о том, как ссылаться на сборки в приложении С++, компилируемом с параметром /clr, см. в разделе #using.
Какая бы из двух форм синтаксиса ни использовалась, вместо директивы подставляется все содержимое указанного включаемого файла. Различие между ними заключается в том, в каком порядке препроцессор ищет файлы заголовков, если путь указан не полностью. В приведенной ниже таблице показывается различие между этими формами синтаксиса.
Форма синтаксиса |
Действие |
|---|---|
Форма в кавычках |
Препроцессор ищет включаемые файлы в следующем порядке:
|
Форма с угловыми скобками |
Препроцессор ищет включаемые файлы в следующем порядке:
|
Как только препроцессор найдет файл с заданным именем, поиск останавливается. Если путь к включаемому файлу задан полностью и однозначно и окружен двойными кавычками (" "), то препроцессор ищет файл только по заданному пути, а стандартные каталоги пропускает.
Если имя файла в двойных кавычках представляет собой неполную спецификацию пути, то препроцессор сначала просматривает каталог "родительского" файла. Родительский файл — это файл, содержащий директиву #include. Например, если файл file2 включен в файл file1, то родительским файлом будет считаться file1.
Включаемые файлы могут быть вложенными, т. е. директива #include может использоваться в файле, который указан другой директивой #include. Например, файл file2 может включать file3. В этом случае файл file1 останется родительским файлом для file2, однако для file3 он будет уже "прародителем".
Если используются вложенные файлы и компиляция выполняется из командной строки, то поиск начинается с каталогов родительских файлов, а затем выполняется в каталогах всех файлов-прародителей. Таким образом, поиск начинается относительно каталога, в котором находится исходный файл, обрабатываемый в текущий момент. Если файл не найден, поиск перемещается в каталоги, заданные параметром компилятора /I. Наконец, производится поиск в каталогах, указанных в переменной среды INCLUDE.
Если компиляция выполняется в среде разработки, то переменная среды INCLUDE игнорируется. Дополнительные сведения о том, как задать каталоги для писка включаемых файлов (это относится также к переменной среды LIB), см. в разделе VC++ Directories, Projects, Options Dialog Box.
В приведенном ниже примере демонстрируется включение файлов с помощью угловых скобок:
#include <stdio.h>
В этом примере в исходную программу добавляется содержимое файла с именем STDIO.H. Угловые скобки указывают препроцессору, что файл STDIO.H необходимо искать сначала в каталогах, заданных в параметре компилятора /I, а затем — заданных в переменной среды INCLUDE.
В следующем примере демонстрируется включение файлов, заданных в кавычках:
#include "defs.h"
В этом примере в исходную программу добавляется содержимое файла с именем DEFS.H. Кавычки означают, что препроцессор сначала попытается найти этот файл в каталоге, содержащем родительский исходный файл.
Для включаемых файлов поддерживается до 10 уровней вложения. Когда вложенная директива #include будет обработана, препроцессор продолжит вставлять все окружающие ее включаемые файлы в оригинальный исходный файл.
Блок, относящийся только к системам Microsoft
Чтобы найти включаемые исходные файлы, препроцессор сначала просматривает каталоги, заданные параметром компилятора /I. Если параметр /I не указан или вызывает ошибку, то препроцессор ищет все включаемые файлы, заданные в угловых скобках, в каталогах, которые определены в переменной среды INCLUDE. Переменная среды INCLUDE и параметр компилятора /I могут содержать несколько путей, разделенные точкой с запятой (;). Если параметром /I или переменной среды INCLUDE задано несколько каталогов, то препроцессор просматривает их в том порядке, в котором они указаны.
Представим себе следующую команду:
CL /ID:\MSVC\INCLUDE MYPROG.C
Она дает препроцессору указание просмотреть папку D:\MSVC\INCLUDE\ и найти в ней включаемые файлы (например, STDIO.H). Ниже еще один пример:
SET INCLUDE=D:\MSVC\INCLUDE
CL MYPROG.C
Эта инструкция действуют точно так же. Если найти файл в обоих наборах каталогов не удастся, возникает неустранимая ошибка компилятора.
Если имя включаемого файла определено полностью, включая путь с двоеточием (например, F:\MSVC\SPECIAL\INCL\TEST.H), то препроцессор проходит по этому пути.
Если включаемый файл задан директивой #include "path-spec", то поиск начинается с каталога родительского файла, а затем выполняется в каталогах всех файлов-прародителей. Таким образом, поиск начинается относительно каталога, в котором находится исходный файл с обрабатываемой директивой #include. Если у файла нет прародителей, а включаемый файл найти не удалось, то поиск продолжается так, как если бы его имя было заключено в угловые скобки.
Завершение блока, относящегося только к системам Microsoft