#include dyrektywa (C/C++)

Informuje preprocesor o dołączeniu zawartości określonego pliku w punkcie, w którym pojawia się dyrektywa.

Składnia

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

Uwagi

Definicje stałych i makr można organizować w plikach dołączanych (nazywanych również plikami nagłówkowymi), a następnie użyć #include dyrektyw, aby dodać je do dowolnego pliku źródłowego. Dołączanie plików jest również przydatne do dołączania deklaracji zmiennych zewnętrznych i złożonych typów danych. Typy mogą być definiowane i nazwane tylko raz w pliku dołączania utworzonym w tym celu.

Specyfikacja ścieżki to nazwa pliku, która może być opcjonalnie poprzedzona specyfikacją katalogu. Nazwa pliku musi nazwać istniejący plik. Składnia specyfikacji ścieżki zależy od systemu operacyjnego, na którym jest kompilowany program.

Aby uzyskać informacje na temat odwoływanie się do zestawów w aplikacji języka C++, która jest kompilowana przy użyciu metody /clr, zobacz #using dyrektywę.

Obie formy składni powodują #include zastąpienie dyrektywy całą zawartością określonego pliku. Różnica między dwoma formularzami jest kolejnością ścieżek, które preprocesor wyszukuje, gdy ścieżka jest nieukończono określona. W poniższej tabeli przedstawiono różnicę między dwiema formularzami składni.

Formularz składniowy	Akcja
Formularz cytowany	Preprocesor wyszukuje pliki dołączane w następującej kolejności: 1) W tym samym katalogu co plik zawierający instrukcję #include . 2) W katalogach aktualnie otwartych plików dołączanych, w odwrotnej kolejności, w której zostały otwarte. Wyszukiwanie rozpoczyna się w katalogu pliku dołączania nadrzędnego i jest kontynuowane w górę przez katalogi wszystkich dziadków dołączania plików. 3) Wzdłuż ścieżki określonej przez każdą /I opcję kompilatora. 4) Wzdłuż ścieżek określonych przez zmienną środowiskową INCLUDE .
Formularz nawiasu kątowego	Preprocesor wyszukuje pliki dołączane w następującej kolejności: 1) Wzdłuż ścieżki określonej przez każdą /I opcję kompilatora. 2) Podczas kompilowania odbywa się w wierszu polecenia, wzdłuż ścieżek określonych przez zmienną środowiskową INCLUDE .

Preprocesor zatrzymuje wyszukiwanie zaraz po znalezieniu pliku, który ma daną nazwę. Jeśli ujęta jest kompletna, jednoznaczna specyfikacja ścieżki dla pliku dołączania między podwójnymi cudzysłowami (" "), preprocesor wyszukuje tylko tę specyfikację ścieżki i ignoruje katalogi standardowe.

Jeśli nazwa pliku ujęta w podwójny cudzysłów jest niekompletną specyfikacją ścieżki, preprocesor najpierw przeszukuje katalog pliku nadrzędnego . Plik nadrzędny to plik, który zawiera dyrektywę #include . Jeśli na przykład dołączysz plik o nazwie file2 do pliku o nazwie file1, plik1 jest plikiem nadrzędnym.

Dołączanie plików może być zagnieżdżone: #include dyrektywa może pojawić się w pliku o nazwie innej #include dyrektywy. Na przykład plik2 może zawierać plik3. W tym przypadku plik1 nadal byłby rodzicem pliku2, ale byłby to dziadek pliku3.

Gdy pliki dołączania są zagnieżdżone, a kompilowanie odbywa się w wierszu polecenia, wyszukiwanie katalogów rozpoczyna się w katalogu pliku nadrzędnego. Następnie przechodzi przez katalogi wszelkich plików dziadków. Oznacza to, że wyszukiwanie rozpoczyna się względem katalogu zawierającego aktualnie przetwarzane źródło. Jeśli plik nie zostanie znaleziony, wyszukiwanie zostanie przeniesione do katalogów określonych przez /I opcję kompilatora (Dodatkowe katalogi dołączania). Na koniec przeszukiwane są katalogi określone przez zmienną INCLUDE środowiskową.

W środowisku programistycznym programu Visual Studio zmienna INCLUDE środowiskowa jest ignorowana. Zamiast tego są używane wartości określone we właściwościach projektu dla katalogów dołączania. Aby uzyskać więcej informacji na temat ustawiania katalogów dołączania w programie Visual Studio, zobacz Dołączanie katalogów i Dodatkowe katalogi dołączania.

W tym przykładzie pokazano dołączanie plików przy użyciu nawiasów kątowych:

#include <stdio.h>

Przykład dodaje zawartość pliku o nazwie stdio.h do programu źródłowego. Nawiasy kątowe powodują, że preprocesor wyszukuje katalogi określone przez zmienną INCLUDE środowiskową dla stdio.h, po wyszukiwaniu katalogów określonych przez opcję kompilatora /I .

W następnym przykładzie pokazano dołączenie pliku przy użyciu cytowanego formularza:

#include "defs.h"

Przykład dodaje zawartość pliku określonego przez defs.h program źródłowy. Cudzysłów oznacza, że preprocesor najpierw przeszukuje katalog zawierający nadrzędny plik źródłowy.

Zagnieżdżanie plików dołączanych może trwać do 10 poziomów. Po zakończeniu przetwarzania zagnieżdżonego #include preprocesor kontynuuje wstawianie otaczającego pliku nadrzędnego dołączania do oryginalnego pliku źródłowego.

Specyficzne dla firmy Microsoft

Aby zlokalizować pliki źródłowe do uwzględnienia, preprocesor najpierw wyszukuje katalogi określone przez opcję kompilatora /I . /I Jeśli opcja nie jest obecna lub nie powiedzie się, preprocesor używa INCLUDE zmiennej środowiskowej do znalezienia plików dołączanych w nawiasach kątowych. Opcja INCLUDE zmiennej środowiskowej i /I kompilatora może zawierać wiele ścieżek rozdzielonych średnikami (;). Jeśli w ramach /I opcji lub w zmiennej INCLUDE środowiskowej pojawi się więcej niż jeden katalog, preprocesor wyszukuje je w kolejności ich wyświetlania.

Na przykład polecenie

CL /ID:\msvc\include myprog.c

powoduje, że preprocesor wyszukuje w katalogu D:\msvc\include\ pliki dołączane, takie jak stdio.h. Polecenia

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

mają taki sam efekt. Jeśli oba zestawy wyszukiwań nie powiedzie się, zostanie wygenerowany błąd kompilatora krytycznego.

Jeśli nazwa pliku jest w pełni określona dla pliku dołączania, który ma ścieżkę zawierającą dwukropek (na przykład F:\MSVC\SPECIAL\INCL\TEST.H), preprocesor jest zgodny ze ścieżką.

W przypadku plików dołączanych, które są określone jako #include "path-spec", wyszukiwanie katalogów rozpoczyna się w katalogu pliku nadrzędnego, a następnie przechodzi przez katalogi wszystkich plików dziadków. Oznacza to, że wyszukiwanie rozpoczyna się względem katalogu zawierającego przetwarzany plik źródłowy. Jeśli nie ma pliku dziadka i plik nadal nie zostanie znaleziony, wyszukiwanie będzie kontynuowane tak, jakby nazwa pliku była ujęta w nawiasy kątowe.

KONIEC specyficzny dla firmy Microsoft

Zobacz też

Dyrektywy preprocesora
/I (Dodatkowe katalogi dołączania)