diretiva #include (C/C++)

Informa o pré-processador para incluir o conteúdo de um arquivo especificado no ponto onde a diretiva aparece.

Sintaxe

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

Comentários

É possível organizar definições de constante e de macro em arquivos de inclusão (também conhecidos como arquivos de cabeçalho) e, em seguida, usar diretivas #include para adicionar essas definições a qualquer arquivo de origem. Os arquivos de inclusão também são úteis para incorporar declarações de variáveis externas e tipos de dados complexos. Os tipos podem ser definidos e nomeados somente uma vez em um arquivo de inclusão criado para essa finalidade.

O path-spec é um nome de arquivo que pode, opcionalmente, ser precedido por uma especificação de diretório. O nome do arquivo deve nomear um arquivo existente. A sintaxe do path-spec depende do sistema operacional em que o programa é compilado.

Para obter informações sobre como referenciar assemblies no aplicativo C++ compilado usando /clr, consulte a#using diretiva .

As duas formas de sintaxe causam a substituição da diretiva #include pelo conteúdo inteiro do arquivo especificado. A diferença entre as duas formas é a ordem em que o pré-processador pesquisa por caminhos quando o caminho é especificado de forma incompleta. A tabela a seguir mostra a diferença entre as duas formas de sintaxe.

Forma de sintaxe	Ação
Forma entre aspas	O pré-processador pesquisa por arquivos de inclusão nesta ordem: 1) No mesmo diretório do arquivo que contém a instrução #include. 2) Nos diretórios dos arquivos de inclusão abertos atualmente, na ordem inversa da qual foram abertos. A pesquisa começará no diretório do arquivo de inclusão pai e continuará para cima até os diretórios de qualquer arquivo de inclusão avô. 3) Ao longo do caminho que é especificado por cada opção do compilador /I. 4) Ao longo dos caminhos que são especificados pela variável de ambiente INCLUDE.
Forma de colchete angular	O pré-processador pesquisa por arquivos de inclusão nesta ordem: 1) Ao longo do caminho que é especificado por cada opção do compilador /I. 2) Quando a compilação ocorre na linha de comando, ao longo dos caminhos que são especificados pela variável de ambiente INCLUDE.

O pré-processador para de pesquisar assim que encontra um arquivo com o nome especificado. Se você delimitar uma especificação de caminho completa e não ambígua para o arquivo de inclusão entre aspas duplas (" "), o pré-processador pesquisará apenas essa especificação de caminho e ignorará os diretórios padrão.

Se o nome do arquivo que estiver dentro das aspas duplas for uma especificação incompleta do caminho, o pré-processador primeiro pesquisará no diretório do arquivo pai. O arquivo pai é o arquivo que contém a diretiva #include. Por exemplo, se você incluir um arquivo chamado arquivo2 em um arquivo chamado arquivo1, arquivo1 será o arquivo pai.

Os arquivos de inclusão podem ser aninhados: uma diretiva #include pode aparecer em um arquivo denominado por outra diretiva #include. Por exemplo, o arquivo2 pode incluir o arquivo3. Nesse caso, arquivo1 ainda deve ser o pai de arquivo2, mas seria avô de arquivo3.

Quando arquivos de inclusão estão aninhados e quando a compilação acontece na linha de comando, a pesquisa por diretórios começa no diretório do arquivo pai. Em seguida, ela prossegue pelos diretórios de todos os arquivos avôs. Ou seja, a pesquisa inicia relativa ao diretório que contém a fonte que está sendo processada atualmente. Se o arquivo não for encontrado, a pesquisa muda para os diretórios especificados pela opção do compilador /I (Diretórios de inclusão adicionais). Por fim, os diretórios que são especificados pela variável de ambiente INCLUDE são pesquisados.

No ambiente de desenvolvimento do Visual Studio, a variável de ambiente INCLUDE é ignorada. Em vez disso, os valores especificados nas propriedades do projeto para diretórios de inclusão são usados. Para obter mais informações sobre como definir os diretórios de inclusão no Visual Studio, consulte Incluir diretórios e Diretórios de inclusão adicionais.

Este exemplo mostra a inclusão de arquivo usando os colchetes angulares:

#include <stdio.h>

Este exemplo adiciona o conteúdo do arquivo chamado stdio.h ao programa de origem. Os colchetes angulares fazem com que o pré-processador procure nos diretórios especificados pela variável de ambiente INCLUDE para stdio.h, e depois procure nos diretórios especificados pela opção do compilador /I.

O exemplo a seguir mostra a inclusão de arquivo usando a forma entre aspas:

#include "defs.h"

Este exemplo adiciona o conteúdo do arquivo especificado por defs.h para o programa de origem. As aspas significam que o pré-processador pesquisa primeiro no diretório que contém o arquivo de origem pai.

O aninhamento dos arquivos de inclusão pode continuar até 10 níveis. Quando o #include aninhado for processado, o pré-processador continuará a inserir o arquivo de inclusão delimitador pai no arquivo de origem original.

Específico da Microsoft

Para localizar os arquivos de origem que podem ser incluídos, o pré-processador primeiro pesquisa nos diretórios especificados pela opção do compilador /I. Se a opção /I não estiver presente ou falhar, o pré-processador usará a variável de ambiente INCLUDE para localizar os arquivos de inclusão entre colchetes angulares. A variável de ambiente INCLUDE e a opção do compilador /I podem conter vários caminhos separados por ponto-e-vírgula (;). Se mais de um diretório aparecer como parte da opção /I ou dentro da variável de ambiente INCLUDE, o pré-processador procurará por eles na ordem em que aparecem.

Por exemplo, o comando

CL /ID:\msvc\include myprog.c

faz com que o pré-processador pesquise no diretório D:\msvc\include\ os arquivos de inclusão, como stdio.h. Os comandos

SET INCLUDE=D:\msvc\include
CL myprog.c

têm o mesmo efeito. Quando ambos os conjuntos de pesquisas falham, um erro fatal de compilador é gerado.

Se o nome de arquivo for totalmente especificado para um arquivo de inclusão que tem um caminho que inclui dois-pontos (por exemplo, F:\MSVC\SPECIAL\INCL\TEST.H), o pré-processador seguirá o caminho.

Para os arquivos de inclusão especificados como #include "path-spec", a pesquisa de diretório começa com os diretórios do arquivo pai e continua pelos diretórios dos arquivos avô. Ou seja, a pesquisa inicia em relação ao diretório que contém o arquivo de origem que está sendo processado atualmente. Se não houver nenhum arquivo avô e o arquivo não tiver sido encontrado ainda, a pesquisa continuará como se o nome do arquivo estivesse dentro de colchetes.

FIM Específico da Microsoft

Confira também

Diretivas de pré-processador
/I (Diretórios de inclusão adicionais)