Директива #include (C/C++) | Microsoft Learn
- Статья
- Чтение занимает 4 мин
Указывает препроцессору включить содержимое указанного файла в точку, где отображается директива.
Синтаксис
#include "путь — спецификация"#include <путь — спецификация>
Можно организовать константы и определения макросов в включаемые файлы (также известные как заголовочные файлы), а затем использовать #include директивы для добавления их в любой исходный файл.
Путь-Spec — это имя файла, которому при необходимости может предшествовать Спецификация каталога. Имя файла должно указывать на существующий файл. Синтаксис инструкции path-Spec зависит от операционной системы, в которой компилируется программа.
Сведения о том, как ссылаться на сборки в приложении C++, скомпилированном с помощью /clr , см. в разделе #using директива.
Обе синтаксические формы приводят #include к замене директивы всем содержимым указанного файла. Различие между двумя формами — это порядок путей, которые препроцессор ищет при неполном указании пути. В приведенной ниже таблице показывается различие между этими формами синтаксиса.
| Форма синтаксиса | Действие |
|---|---|
| Форма в кавычках | Препроцессор ищет включаемые файлы в следующем порядке: 1) в том же каталоге, что и файл, содержащий 2) в каталогах открытых в данный момент файлов включения в порядке, в котором они были открыты. Поиск начинается в каталоге родительского включаемого файла, а затем выполняется в каталогах всех включаемых файлов-прародителей. 3) вдоль пути, указанного в каждом 4) вдоль путей, указанных в |
| Форма с угловыми скобками | Препроцессор ищет включаемые файлы в следующем порядке: 1) вдоль пути, указанного в каждом 2) при компиляции происходит в командной строке вместе с путями, заданными |
Как только препроцессор найдет файл с заданным именем, поиск останавливается. При заключении полной, неоднозначной спецификации пути для включаемого файла между двойными кавычками ( " " ) препроцессор выполняет поиск только по этой спецификации пути и игнорирует стандартные каталоги.
Если имя файла, заключенное в двойные кавычки, является неполным указанием пути, препроцессор сначала выполняет поиск в каталоге родительского файла. Родительский файл — это файл, содержащий #include директиву. Например, если включить файл с именем file2 в файл с именем file1, то файл file1 будет родительским.
Включаемые файлы могут быть вложенными: #include директива может находиться в файле с именем другой #include директивы. Например, file2 может включать файл3. В этом случае file1 будет по-прежнему являться родителем file2, но это было бы бабушке файл3.
Если включаемые файлы являются вложенными и при компиляции происходит в командной строке, поиск в каталоге начинается в каталоге родительского файла. Затем он переходит по каталогам всех файлов «бабушке». Таким образом, поиск начинается относительно каталога, в котором находится исходный файл, обрабатываемый в текущий момент.
Если файл не найден, Поиск перемещается в каталоги, заданные /I параметром компилятора (дополнительные каталоги включаемых файлов) . Наконец, выполняется поиск каталогов, заданных INCLUDE переменной среды.
в среде INCLUDE разработки Visual Studio переменная среды игнорируется. Вместо них используются значения, указанные в свойствах проекта для каталогов включения. дополнительные сведения о настройке каталогов включения в Visual Studio см. в разделе включаемые каталоги и дополнительные каталоги включаемыхданных.
В приведенном ниже примере демонстрируется включение файлов с помощью угловых скобок:
#include <stdio.h>
В этом примере в исходную программу добавляется содержимое файла с именем stdio.h . Угловые скобки приводят препроцессору для поиска в каталогах, заданных INCLUDE переменной среды для stdio.h , после того, как он выполняет поиск в каталогах, заданных /I параметром компилятора.
В следующем примере демонстрируется включение файлов, заданных в кавычках:
#include "defs.h"
В примере добавляется содержимое файла, указанного defs.h в исходной программе. Кавычки означают, что препроцессор сначала попытается найти этот файл в каталоге, содержащем родительский исходный файл.
Для включаемых файлов поддерживается до 10 уровней вложения. После завершения обработки вложенного #include объекта препроцессор сохраняет вложенный родительский файл в исходный исходный файл.
Только для систем Майкрософт
Чтобы найти исходные файлы для включения, препроцессор сначала выполняет поиск в каталогах, заданных /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" , поиск по каталогу начинается в каталоге родительского файла, а затем продолжается через каталоги всех файлов бабушкх.
То есть поиск начинается относительно каталога, содержащего обрабатываемый исходный файл. Если файл «бабушке» отсутствует, и файл по-прежнему не найден, поиск продолжается так, как если бы имя файла было заключено в угловые скобки.
КОНЕЦ Только для систем Майкрософт
См. также раздел
Директивы препроцессора/I (Дополнительные каталоги включаемых каталогов)
Директива include — Win32 apps
Twitter LinkedIn Facebook Адрес электронной почты
- Статья
- Чтение занимает 2 мин
Директива препроцессора, которая вставляет содержимое указанного файла в исходную программу в точке, где отображается директива.
| #include «filename« |
|---|
| <имя файла #include> |
Параметры
| Элемент | Описание |
|---|---|
| filename | Имя файла, включаемого в него, при необходимости предшествует спецификации каталога. Имя файла должно указывать существующий файл. |
Директива #include приводит к замене директивы всем содержимым указанного файла. Препроцессор перестает выполнять поиск, как только он находит файл с указанным именем; Если указать полную, однозначно заданную спецификацию пути для файла, препроцессор выполняет поиск только по указанному пути.
Примечание
Средство компилятора эффектов имеет встроенный обработчик включения с помощью переключателя /I. Однако при выполнении компилятора из API можно предоставить настраиваемый обработчик включения, реализовав интерфейс ID3DXInclude.
Разница между двумя формами синтаксиса заключается в том порядке, в котором препроцессор выполняет поиск файлов заголовков при неполном указании пути, как показано в следующей таблице.
| #include «filename« | Выполняет поиск включаемого файла:
|
| имя файла #include> | Выполняет поиск включаемого файла:
|
Сведения о настройке путей включения для проекта см. в документации среды разработки.Примеры
В следующем примере препроцессор заменяет директиву #include с содержимым stdio.h. Так как в примере используется формат угловой скобки, препроцессор будет искать файл только в каталогах, перечисленных параметром компилятора /I и переменной среды INCLUDE.
#include <stdio.h>
См. также раздел
Директивы препроцессора (DirectX HLSL)
Интерфейс ID3D10Include
Средство компилятора эффектов
директива #include (C/C++) | Microsoft Learn
- Статья
- 4 минуты на чтение
Указывает препроцессору включить содержимое указанного файла в точку, где появляется директива.
Синтаксис
#include "спецификация пути"
#include <спецификация пути>5
Вы можете организовать определения констант и макросов в включаемых файлах (также известных как файлы заголовков ), а затем использовать директивы #include для добавления их в любой исходный файл. Включаемые файлы также полезны для включения объявлений внешних переменных и сложных типов данных. Типы могут быть определены и названы только один раз во включаемом файле, созданном для этой цели.
Спецификация пути — это имя файла, которому может предшествовать спецификация каталога. Имя файла должно называть существующий файл. Синтаксис path-spec зависит от операционной системы, в которой скомпилирована программа.
Сведения о том, как ссылаться на сборки в приложении C++, скомпилированном с использованием /clr , см. в разделе #using директива.
Обе формы синтаксиса вызывают #include для замены всего содержимого указанного файла. Разница между этими двумя формами заключается в порядке путей, которые ищет препроцессор, когда путь указан не полностью. В следующей таблице показаны различия между двумя формами синтаксиса.
| Форма синтаксиса | Действие |
|---|---|
| Заявленная форма | Препроцессор ищет включаемые файлы в следующем порядке: 1) В том же каталоге, что и файл, содержащий 2) В каталогах открытых в данный момент включаемых файлов, в порядке, обратном их открытию. Поиск начинается в каталоге родительского включаемого файла и продолжается вверх по каталогам любых родительских включаемых файлов. 3) По пути, указанному каждой опцией компилятора 4) По путям, указанным в переменной среды |
| Форма уголка | Препроцессор ищет включаемые файлы в следующем порядке: 1) По пути, указанному каждой опцией компилятора 2) При компиляции происходит в командной строке, по путям, которые указаны переменной окружения |
Препроцессор прекращает поиск, как только находит файл с заданным именем. Если вы заключите полную и недвусмысленную спецификацию пути к включаемому файлу в двойные кавычки ( " " ), препроцессор ищет только эту спецификацию пути и игнорирует стандартные каталоги.
Если имя файла, заключенное в двойные кавычки, представляет собой неполную спецификацию пути, препроцессор сначала ищет каталог родительского файла . Родительский файл — это файл, содержащий директиву #include .
Например, если вы включаете файл с именем файл2 в файл с именем файл1 , файл1 является родительским файлом.
Включаемые файлы могут быть вложенными : Директива #include может появиться в файле, который назван другой директивой #include . Например, файл2 может включать файл3 . В этом случае file1 по-прежнему будет родителем file2 , но будет прародителем file3 .
Если включаемые файлы вложены друг в друга и компиляция выполняется из командной строки, поиск в каталоге начинается с каталога родительского файла. Затем он проходит через каталоги любых родительских файлов. То есть поиск начинается относительно каталога, содержащего исходный код, который в данный момент обрабатывается. Если файл не найден, поиск перемещается в каталоги, указанные /I (Дополнительные включаемые каталоги) параметр компилятора.
Наконец, выполняется поиск в каталогах, указанных в переменной среды INCLUDE .
В среде разработки Visual Studio переменная среды INCLUDE игнорируется. Вместо этого используются значения, указанные в свойствах проекта для включаемых каталогов. Дополнительные сведения о настройке включаемых каталогов в Visual Studio см. в разделах Включаемые каталоги и Дополнительные включаемые каталоги.
В этом примере показано включение файлов с помощью угловых скобок:
#include
В этом примере содержимое файла с именем stdio.h добавляется в исходную программу. Угловые скобки заставляют препроцессор искать каталоги, указанные переменной среды INCLUDE для stdio.h , после того как он ищет каталоги, указанные параметром компилятора /I .
В следующем примере показано включение файла с использованием формы в кавычках:
#include "defs.h"
h"
В этом примере содержимое файла, заданного параметром defs.h , добавляется в исходную программу. Кавычки означают, что препроцессор сначала ищет каталог, содержащий родительский исходный файл.
Вложенность включаемых файлов может продолжаться до 10 уровней. Когда обработка вложенных #include завершена, препроцессор продолжает вставлять прилагаемый родительский включаемый файл в исходный исходный файл.
Специально для Microsoft
Чтобы найти исходные файлы для включения, препроцессор сначала выполняет поиск в каталогах, указанных параметром компилятора /I . Если параметр /I отсутствует или не работает, препроцессор использует переменную среды INCLUDE для поиска любых включаемых файлов в угловых скобках. Переменная среды INCLUDE и параметр компилятора /I могут содержать несколько путей, разделенных точкой с запятой ( ; ).
Если в параметре /I или в переменной окружения INCLUDE появляется более одного каталога, препроцессор ищет их в том порядке, в котором они появляются.
Например, команда
CL /ID:\msvc\include myprog.c
заставляет препроцессор искать в каталоге D:\msvc\include\ включаемые файлы, такие как stdio.h . Команды
КОМПЛЕКТ ВКЛЮЧАЕТ=D:\msvc\include CL myprog.c
имеют тот же эффект. Если оба набора поисков завершатся неудачно, будет сгенерирована фатальная ошибка компилятора.
Если имя файла указано полностью для включаемого файла, путь которого включает двоеточие (например, F:\MSVC\SPECIAL\INCL\TEST.H ), препроцессор следует пути.
Для включаемых файлов, указанных как #include "path-spec" , поиск в каталоге начинается с каталога родительского файла, а затем продолжается в каталогах любых родительских файлов.
То есть поиск начинается относительно каталога, содержащего обрабатываемый исходный файл. Если родительского файла нет и файл все еще не найден, поиск продолжается, как если бы имя файла было заключено в угловые скобки.
END Специально для Microsoft
См. также
Директивы препроцессора
/I (Дополнительные включаемые каталоги)
Включает | Asciidoctor Docs
Вы можете включить содержимое из другого файла в текущий документ AsciiDoc, используя директиву include. Включенный контент может быть в формате AsciiDoc или в любом другом текстовом формате. То, где это содержимое включено в документ, определяет, как оно будет обработано.
Что такое директива включения?
Директива include импортирует содержимое из отдельного файла или URL-адреса в содержимое текущего документа.
Когда текущий документ обрабатывается, синтаксис директивы include заменяется содержимым файла include.
Думайте о директиве include как о расширителе файлов.
Директива include является директивой препроцессора, что означает, что она не знает об окружающем контексте.
Когда полезна директива include?
Директива include полезна, когда вы хотите:
Разделите большой документ на файлы меньшего размера для лучшей организации и упрощения реструктуризации. [1]
Вставьте исходный код из внешних файлов, в которых хранится код.
Заполнить таблицы выходными данными, такими как данные CSV, из других программ.
Создайте варианты документа, объединив директиву include с условными директивами препроцессора.
Повторное использование фрагментов содержимого и шаблонного содержимого, например определений терминов, заявлений об отказе от ответственности и т. д., несколько раз в одном документе.
Синтаксис директивы Include
Директива include должна быть размещена на отдельной строке со следующим синтаксисом: ) ,indent= depth ,opts=необязательно]
Требуется цель.
Целью может быть абсолютный путь, путь относительно текущего документа или URL-адрес.
Поскольку директива include является строковым выражением, цель может содержать символы пробела.
Однако цель не должна начинаться с символа пробела (поскольку это превратит ее в термин списка описания).
Абсолютный или относительный путь за пределами каталога самого внешнего документа будет учитываться только в том случае, если безопасный режим небезопасен.
Целевой URL-адрес будет разрешен только в том случае, если это позволяют настройки безопасности процессора (например, разрешить-ури-чтение ).
См. Включение контента по URI.
Атрибуты leveloffset, lines, tag(s), indent и opts являются необязательными, поэтому простейший случай сводится к следующему:
include::partial.adoc[]
отделяйте их пустой строкой, если только вы не намерены примыкать к содержимому включаемых файлов, чтобы оно стало непрерывным.
Например, если вы используете директиву include для включения отдельных глав, директивы include должны быть смещены друг от друга на пустую строку.
Эта стратегия позволяет избежать использования пустых строк, импортированных из включаемого файла, для разделения глав.
Вместо этого это разделение должно быть закодировано в родительском документе.
include::chapter01.adoc[] включить::chapter02.adoc[] include::chapter03.adoc[]
С другой стороны, если вы используете директиву include для размещения смежных строк, таких как записи общих атрибутов документа, то вы должны поместить директивы include на соседние строки, чтобы избежать вставки пустых строк. линии.
= Название документа Имя автора include::attributes-settings.adoc[] include::attributes-urls.adoc[] :url-пример: https://example.org Тело документа.
В любом случае не полагайтесь на пустые строки на границах включаемого файла. И обратите внимание, где в этом включаемом файле используются пустые строки.
Обработка включения
Хотя директива включения выглядит как блочный макрос, это не макрос и поэтому не обрабатывается как .
Это директива препроцессора; важно понимать разницу.
Директива препроцессора обрабатывается при чтении строк документа, но до анализа структуры документа. Следовательно, он не знает о структуре окружающего документа. Директива препроцессора просто добавляет строки в программу чтения или удаляет строки. Директива include — это директива препроцессора, которая всегда добавляет строки.
Лучший способ думать о директиве include — представить, что она заменяется строками из включаемого файла (т. е. импортированными строками). Только после того, как строки из цели директивы include будут добавлены в текущий документ, синтаксический анализатор читает и интерпретирует эти строки.
| Директива include отключена, когда Asciidoctor запускается в безопасном режиме. В безопасном режиме директива include преобразуется в ссылку в выходном документе. См. Безопасные режимы, чтобы узнать больше. |
Экранирование директивы include
Если вы не хотите, чтобы директива include обрабатывалась, вы должны экранировать ее, используя обратную косую черту.
\include::just-example.ext[]
Экранирование директивы необходимо , даже если она появляется в дословном блоке , поскольку она не знает о структуре окружающего документа.
Разрешение включаемого файла
Путь, используемый в директиве include, может быть относительным или абсолютным.
Если путь относительный, процессор разрешает путь, используя следующие правила:
Если директива include используется в основном документе (верхнего уровня), относительные пути разрешаются относительно базового каталога. (Базовый каталог по умолчанию является каталогом основного документа и может быть переопределен из интерфейса командной строки или API).
Если директива include используется в файле, который сам был включен, путь разрешается относительно включающего (т. е. текущего) файла.
Эти значения по умолчанию позволяют легко рассуждать о том, как разрешается путь к включаемому файлу.
Если процессор не может найти файл (возможно, из-за того, что вы неправильно указали путь), вы все равно сможете преобразовать документ. Однако во время преобразования вы получите следующее предупреждающее сообщение:
asciidoctor: ПРЕДУПРЕЖДЕНИЕ: my-document.adoc: строка 3: включаемый файл не найден: /.../content.adoc
Следующее сообщение также будет вставлено в вывод:
Неразрешенная директива в my-document.adoc - include::content.adoc[]
Чтобы устранить проблему, отредактируйте путь к файлу и снова запустите конвертер.
Если вы не хотите, чтобы процессор AsciiDoc выдавал предупреждение, а отбрасывал включение, которое не может быть найдено, добавьте opts=необязательный атрибут директивы include.
Если вы храните файлы AsciiDoc во вложенных папках на разных уровнях, относительные пути к файлам могут быстро стать неудобными и негибкими. Обычный шаблон, который поможет здесь, заключается в определении путей в атрибутах, определенных в заголовке, а затем добавлении префикса всех путей включения со ссылкой на один из этих атрибутов:
:includedir: _includes :исходный_каталог: .
./src/main/java
include::{includedir}/fragment1.adoc[]
[источник, java]
----
include::{исходный_каталог}/org/asciidoctor/Asciidoctor.java[]
---- Имейте в виду, что независимо от того, как Asciidoctor разрешает путь к файлу, доступ к этому файлу ограничен настройкой безопасного режима, в котором запущен Asciidoctor. Если путь нарушает ограничения безопасности, он может быть усечен.
AsciiDoc против файлов, отличных от AsciiDoc
Директива include выполняет простое слияние файлов, поэтому она работает с любым текстовым файлом. Содержимое всего включенного контента нормализовано. Это означает, что кодировка принудительно устанавливается в UTF-8 (или преобразуется из UTF-16 в UTF-8, если файл содержит спецификацию), а завершающие пробелы и конечные строки удаляются из каждой строки и заменяются переводом строки Unix. Эта нормализация важна для работы процессора AsciiDoc.
Если файл распознается как файл AsciiDoc (т. е. имеет одно из следующих расширений: .