Przewodnik: importowanie bibliotek STL jako jednostek nagłówka

W tym przewodniku pokazano, jak zaimportować biblioteki standardowej biblioteki szablonów języka C++ (STL) jako jednostki nagłówka w programie Visual Studio. Aby uzyskać jeszcze szybszy i bardziej niezawodny sposób importowania standardowej biblioteki, zobacz Samouczek: importowanie standardowej biblioteki języka C++ przy użyciu modułów.

Importowanie nagłówka STL jako jednostki nagłówka jest prostsze niż używanie wstępnie skompilowanych plików nagłówków. Jednostki nagłówków są łatwiejsze do skonfigurowania i użycia, są znacznie mniejsze na dysku, zapewniają podobne korzyści z wydajności i są bardziej elastyczne niż współużytkowany PCH.

Aby uzyskać bardziej szczegółowe informacje o jednostkach nagłówka i oferowanych przez nie korzyściach, zobacz Co to jest jednostka nagłówka?. Aby porównać jednostki nagłówka z innymi sposobami importowania biblioteki standardowej, zobacz Porównanie jednostek nagłówków, modułów i wstępnie skompilowanych nagłówków.

Wymagania wstępne

Aby użyć jednostek nagłówków, użyj programu Visual Studio 2022 lub nowszego albo programu Visual Studio 2019 w wersji 16.11 lub nowszej. Opcja (lub nowsza) jest wymagana /std:c++20 do używania jednostek nagłówka.

Dwa podejścia do importowania nagłówków STL jako jednostek nagłówka

Aby można było zaimportować nagłówek STL, należy go skompilować do jednostki nagłówka. Jednostka nagłówka to binarna reprezentacja pliku nagłówka. Ma .ifc rozszerzenie.

Zalecaną metodą jest utworzenie biblioteki statycznej zawierającej skompilowane jednostki nagłówka dla nagłówków STL, których chcesz użyć. Następnie odwołaj się do tej biblioteki i import jej jednostek nagłówka. Takie podejście może spowodować szybsze kompilowanie i lepsze ponowne użycie. Aby wypróbować to podejście, zobacz Podejście 1: Tworzenie biblioteki statycznej jednostek nagłówków biblioteki STL.

Innym podejściem jest skanowanie programu Visual Studio pod kątem nagłówków #include STL w projekcie, skompilowanie ich w jednostkach nagłówków, a import nie #include tych nagłówków. Takie podejście jest przydatne, jeśli masz dużą bazę kodu, ponieważ nie musisz zmieniać kodu źródłowego. Takie podejście jest mniej elastyczne niż podejście do biblioteki statycznej, ponieważ nie nadaje się do ponownego tworzenia wbudowanych jednostek nagłówka w innych projektach. Jednak nadal uzyskujesz zaletę wydajności importowania poszczególnych bibliotek STL jako jednostek nagłówka. Aby wypróbować to podejście, zobacz Podejście 2: skanowanie zawiera nagłówki STL do zaimportowania.

Podejście 1. Tworzenie biblioteki statycznej jednostek nagłówków biblioteki STL

Zalecanym sposobem korzystania z bibliotek STL jako jednostek nagłówka jest utworzenie co najmniej jednego projektu biblioteki statycznej. Te projekty powinny składać się z jednostek nagłówka biblioteki STL, których chcesz użyć. Następnie odwołaj się do projektów biblioteki, aby korzystać z tych jednostek nagłówka STL. Podobnie jak w przypadku korzystania z udostępnionych wstępnie skompilowanych nagłówków, ale jest to łatwiejsze.

Jednostki nagłówkowe (i moduły) wbudowane w projekt biblioteki statycznej są automatycznie dostępne do odwoływania się do projektów, ponieważ system projektu automatycznie dodaje odpowiednią /headerUnit opcję wiersza polecenia do kompilatora, aby przywoływały projekty, aby można było zaimportować jednostki nagłówka.

Takie podejście gwarantuje, że jednostka nagłówka dla określonego nagłówka jest kompilowana tylko raz. Umożliwia importowanie niektórych lub wszystkich jednostek nagłówka, co nie jest możliwe w przypadku PCH. Jednostki nagłówka można uwzględnić w dowolnej kolejności.

W poniższym przykładzie utworzysz projekt biblioteki statycznej składającej się z jednostek nagłówka <iostream> i .<vector> Po skompilowaniu rozwiązania odwołujesz się do tego udostępnionego projektu jednostki nagłówka z innego projektu języka C++. Wszędzie import <iostream>; lub import <vector>; znajduje się wbudowana jednostka nagłówka dla tej biblioteki jest używana zamiast tłumaczenia nagłówka za pomocą preprocesora. Zwiększa wydajność kompilacji, podobnie jak pliki PCH, gdy ten sam nagłówek jest uwzględniony w wielu plikach. Nagłówek nie będzie musiał być przetwarzany przez pliki, które go zawierają. Zamiast tego importowana jest już przetworzona skompilowana jednostka nagłówka.

Aby utworzyć bibliotekę statyczną zawierającą biblioteki <iostream> STL i <vector>, wykonaj następujące kroki:

1. Utwórz pusty projekt C++. Nadaj mu nazwę SharedPrj.
   Wybierz pozycję Pusty projekt dla języka C++ z typów projektów dostępnych w oknie Tworzenie nowego projektu:

2. Dodaj nowy plik C++ do projektu. Zmień zawartość pliku na:

   import <iostream>;
   import <vector>;
   

Ustawianie właściwości projektu

Ustaw właściwości projektu, aby udostępnić jednostki nagłówka z tego projektu:

1. W menu głównym programu Visual Studio wybierz pozycję Project SharedPrj Properties (Właściwości udostępnione projektu>), aby otworzyć okno dialogowe Strony właściwości projektu:
2. Wybierz pozycję Wszystkie konfiguracje z listy rozwijanej Konfiguracja , a następnie wybierz pozycję Wszystkie platformy z listy rozwijanej Platforma . Te ustawienia zapewniają, że zmiany mają zastosowanie niezależnie od tego, czy tworzysz debugowanie, czy wydanie.
3. W lewym okienku okna dialogowego Strony właściwości projektu wybierz pozycję Właściwości>konfiguracji Ogólne.
4. Zmień opcję Typ konfiguracji na Statyczna biblioteka (.lib).
5. Zmień standard języka C++ na ISO C++20 Standard (/std:c++20) (lub nowszy).
6. W lewym okienku okna dialogowego Strony właściwości projektu wybierz pozycję Właściwości>konfiguracji C/C++>General.
7. Na liście rozwijanej Skanuj źródła dla zależności modułu wybierz pozycję Tak. (Ta opcja powoduje, że kompilator skanuje kod pod kątem zależności, które mogą być wbudowane w jednostki nagłówka):
8. Wybierz przycisk OK , aby zamknąć okno dialogowe Strony właściwości projektu. Skompiluj rozwiązanie, wybierając pozycję Kompiluj>rozwiązanie kompilacji w menu głównym.

Odwołanie do biblioteki jednostek nagłówka

Aby zaimportować <iostream> jednostki nagłówka i <vector> jako jednostki nagłówka z biblioteki statycznej, utwórz projekt, który odwołuje się do biblioteki statycznej w następujący sposób:

1. Po otwarciu bieżącego rozwiązania w menu programu Visual Studio wybierz pozycję Plik>Dodaj>nowy projekt.

2. W kreatorze Tworzenie nowego projektu wybierz szablon Aplikacja konsolowa języka C++, a następnie wybierz pozycję Dalej.

3. Nadaj nowej nazwie przewodnik po projekcie. Zmień listę rozwijaną Rozwiązanie na Dodaj do rozwiązania. Wybierz pozycję Utwórz , aby utworzyć projekt i dodać go do rozwiązania.

4. Zmień zawartość pliku źródłowego Walkthrough.cpp w następujący sposób:

   import <iostream>;
   import <vector>;
   
   int main()
   {
       std::vector<int> numbers = {0, 1, 2};
       std::cout << numbers[1];
   }
   

Jednostki nagłówka wymagają opcji (lub nowszej /std:c++20 ). Ustaw standard języka, wykonując następujące kroki:

1. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt Przewodnik i wybierz polecenie Właściwości, aby otworzyć okno dialogowe Strony właściwości projektu:
2. W lewym okienku okna dialogowego Wskazówki strony właściwości projektu wybierz pozycję Właściwości>konfiguracji Ogólne.
3. Na liście rozwijanej C++ Language Standard wybierz pozycję ISO C++20 Standard (/std:c++20) (lub nowsze).
4. Wybierz przycisk OK , aby zamknąć okno dialogowe Strony właściwości projektu.

W projekcie Przewodnik dodaj odwołanie do projektu SharedPrj , wykonując następujące czynności:

1. W projekcie Przewodnik wybierz węzeł Odwołania , a następnie wybierz pozycję Dodaj odwołanie. Wybierz pozycję SharedPrj na liście projektów: Dodanie tej odwołania powoduje, że system kompilacji używa jednostek nagłówków utworzonych przez SharedPrj za każdym razem, gdy w import projekcie Przewodnik pasuje do jednej z wbudowanych jednostek nagłówka w sharedPrj.
2. Wybierz przycisk OK , aby zamknąć okno dialogowe Dodawanie odwołania .
3. Kliknij prawym przyciskiem myszy projekt Przewodnik i wybierz polecenie Ustaw jako projekt startowy.
4. Stwórz rozwiązanie. (Użyj Kompiluj>rozwiązanie kompilacji w menu głównym). Uruchom go, aby zobaczyć, że generuje oczekiwane dane wyjściowe:1

Zaletą tego podejścia jest możliwość odwołowania się do projektu biblioteki statycznej z dowolnego projektu w celu ponownego użycia w nim jednostek nagłówka. W tym przykładzie biblioteka statyczna zawiera jednostki nagłówka <vector> i .<iostream>

Możesz utworzyć monolityczny projekt biblioteki statycznej zawierający wszystkie powszechnie używane nagłówki STL, które mają zostać zaimportowane z różnych projektów. Możesz też utworzyć mniejsze projekty bibliotek udostępnionych dla różnych grup bibliotek STL, które mają zostać zaimportowane jako jednostki nagłówka. Następnie odwołuj się do tych udostępnionych projektów jednostek nagłówka zgodnie z potrzebami.

Należy zwiększyć przepływność kompilacji, ponieważ importowanie jednostki nagłówka znacznie zmniejsza pracę, jaką musi wykonać kompilator.

Jeśli używasz tego podejścia z własnymi projektami, skompiluj projekt biblioteki statycznej przy użyciu opcji kompilatora, które są zgodne z projektem odwołującym się do niego. Na przykład projekty STL powinny zostać skompilowane przy użyciu /EHsc opcji kompilatora, aby włączyć obsługę wyjątków, a więc projekty odwołujące się do projektu biblioteki statycznej.

Korzystanie z polecenia /translateInclude

Opcja kompilatora /translateInclude (dostępna w oknie dialogowym Strony właściwości projektu w obszarze C/C++>General>Translate Includes to Import) ułatwia używanie biblioteki jednostek nagłówka w starszych projektach bibliotek #include STL. Sprawia to, że nie trzeba zmieniać #include dyrektyw w import projekcie, jednocześnie zapewniając przewagę importowania jednostek nagłówka zamiast ich dołączania.

Jeśli na przykład korzystasz #include <vector> z projektu i odwołujesz się do biblioteki statycznej zawierającej jednostkę nagłówka dla <vector>programu , nie musisz ręcznie zmieniać #include <vector> elementu import <vector>; w kodzie źródłowym. Zamiast tego kompilator automatycznie traktuje #include <vector> element jako import <vector>;. Aby uzyskać więcej informacji na temat tego podejścia, zobacz Podejście 2: skanowanie zawiera nagłówki STL do zaimportowania. Nie wszystkie pliki nagłówków STL można skompilować do jednostki nagłówka. Dostarczone header-units.json z programem Visual Studio zawiera listę plików nagłówków STL, które można skompilować do jednostek nagłówka. Nagłówek, który opiera się na makrach określających jego zachowanie, często nie można skompilować w jednostce nagłówka.

Instrukcja #include , która nie odnosi się do jednostki nagłówka, jest traktowana jako normalna #include.

Ponowne używanie jednostek nagłówka między projektami

Jednostki nagłówków utworzone przez projekt biblioteki statycznej są automatycznie dostępne dla wszystkich projektów bezpośrednio i pośrednio odwołujące się do projektów. Istnieją ustawienia projektu, które umożliwiają wybranie, które jednostki nagłówka powinny być automatycznie dostępne dla wszystkich odwołujących się projektów. Ustawienia są w ustawieniach projektu w obszarze Katalogi VC++.

1. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt i wybierz polecenie Właściwości, aby otworzyć okno dialogowe Strony właściwości projektu.
2. W okienku po lewej stronie okna dialogowego wybierz pozycję Właściwości konfiguracji Katalogi> VC++:

Następujące właściwości kontrolują widoczność jednostek nagłówka w systemie kompilacji:

• Katalogi dołączania publicznego określają katalogi projektów dla jednostek nagłówka, które powinny zostać automatycznie dodane do ścieżki dołączania w odwołujących się do projektów.
• Publiczne katalogi modułów języka C++ określają, które katalogi projektów zawierają jednostki nagłówka, które powinny być dostępne do odwoływania się do projektów. Ta właściwość umożliwia upublicznienie niektórych jednostek nagłówka. Jest ona widoczna dla innych projektów, dlatego umieść jednostki nagłówka, które chcesz udostępnić tutaj. Jeśli używasz tego ustawienia, dla wygody określ katalogi dołączania publicznego, aby automatycznie dodać nagłówki publiczne do ścieżki Dołączanie w projektach odwołującej się do nich.
• Wszystkie moduły są publiczne: w przypadku używania jednostek nagłówków skompilowanych w ramach projektu DLL symbole muszą być eksportowane z biblioteki DLL. Aby automatycznie wyeksportować symbole modułu, ustaw tę właściwość na Wartość Tak.

Używanie wstępnie utworzonego pliku modułu

Zazwyczaj najprostszym sposobem ponownego użycia jednostek nagłówka między rozwiązaniami jest odwołanie się do udostępnionego projektu jednostki nagłówka z każdego rozwiązania.

Jeśli musisz użyć wbudowanej jednostki nagłówka, dla której nie masz projektu, możesz określić, gdzie znajduje się skompilowany .ifc plik, aby można było go zaimportować w rozwiązaniu. Aby uzyskać dostęp do tego ustawienia:

1. W menu głównym wybierz pozycję Właściwości projektu>, aby otworzyć okno dialogowe Strony właściwości projektu.
2. W lewym okienku okna dialogowego wybierz pozycję Właściwości>konfiguracji C/C++>General.
3. W obszarze Dodatkowe zależności modułu dodaj moduły do odwołania rozdzielone średnikami. Oto przykład formatu, który ma być używany dla dodatkowych zależności modułu: ModuleName1=Path\To\ModuleName1.ifc; ModuleName2=Path\To\ModuleName2.ifc

Wybierz jedną z wielu kopii jednostki nagłówka

Jeśli odwołujesz się do projektów, które tworzą wiele jednostek nagłówka, o tej samej nazwie lub dla tego samego pliku nagłówka, musisz określić, który z nich ma być używany. Mogą istnieć różne wersje jednostki nagłówka utworzone z różnymi ustawieniami kompilatora, na przykład i muszą określić wersję zgodną z ustawieniami projektu.

Użyj właściwości Dodatkowe zależności jednostek nagłówka projektu, aby rozwiązać kolizje, określając jednostkę nagłówka do użycia. W przeciwnym razie nie można przewidzieć, który z nich jest wybierany.

Aby ustawić właściwość Zależności jednostek dodatkowego nagłówka :

1. W menu głównym wybierz pozycję Właściwości projektu>, aby otworzyć okno dialogowe Strony właściwości projektu.
2. W lewym okienku okna dialogowego wybierz pozycję Właściwości>konfiguracji C/C++>General.
3. Określ, które moduły lub pliki jednostek nagłówka mają być używane w dodatkowych zależnościach jednostek nagłówka w celu rozwiązania kolizji. Użyj tego formatu dla dodatkowych zależności jednostek nagłówka: Path\To\Header1.h= Path\To\HeaderUnit1.ifc;Path\To\Header2.h= Path\To\ HeaderUnit2.ifc

Ważne

Upewnij się, że projekty współużytkujące jednostki nagłówka są kompilowane z zgodnymi opcjami kompilacji. Jeśli używasz opcji kompilacji podczas implementowania jednostki nagłówka, która różni się od tych, które zostały użyte podczas jego tworzenia, kompilator wyświetli ostrzeżenia.

Uwaga

Aby użyć jednostek nagłówków utworzonych w ramach projektu DLL, ustaw wartość Wszystkie moduły na Wartość Tak.

Podejście 2. Skanowanie obejmuje nagłówki STL do zaimportowania

Innym sposobem importowania bibliotek STL jest skanowanie programu Visual Studio pod kątem nagłówków #include STL w projekcie i kompilowanie ich w jednostkach nagłówków. Następnie kompilator importuje zamiast dołączać te nagłówki.

Ta opcja jest wygodna, gdy projekt zawiera wiele plików nagłówków STL w wielu plikach lub gdy przepływność kompilacji nie jest krytyczna. Ta opcja nie gwarantuje, że jednostka nagłówka dla określonego pliku nagłówka jest kompilowana tylko raz. Jest to jednak przydatne, jeśli masz dużą bazę kodu: nie musisz zmieniać kodu źródłowego, aby korzystać z zalet jednostek nagłówków dla wielu używanych bibliotek STL.

Takie podejście jest mniej elastyczne niż podejście do biblioteki statycznej, ponieważ nie nadaje się do ponownego tworzenia wbudowanych jednostek nagłówka w innych projektach. Takie podejście może nie być odpowiednie w przypadku większych projektów: nie gwarantuje optymalnego czasu kompilacji, ponieważ wszystkie źródła muszą być skanowane pod #include kątem instrukcji.

Nie wszystkie pliki nagłówkowe można automatycznie konwertować na jednostki nagłówka. Na przykład nagłówki zależne od kompilacji warunkowej za pośrednictwem makr nie powinny być konwertowane na jednostki nagłówka. Istnieje lista dozwolonych header-units.json w postaci pliku dla nagłówków STL używanych przez kompilator, gdy /translateInclude jest określony. Określa, które nagłówki STL można skompilować w jednostkach nagłówka. Plik header-units.json znajduje się w katalogu instalacyjnym programu Visual Studio. Na przykład %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json. Jeśli plik nagłówka STL nie znajduje się na liście, jest traktowany jako normalny #include , zamiast importować go jako jednostkę nagłówka. Kolejną zaletą header-units.json pliku jest to, że zapobiega duplikowaniu symboli w skompilowanych jednostkach nagłówka. Oznacza to, że w przypadku kompilowania jednostki nagłówka w innym nagłówku biblioteki wiele razy symbole nie zostaną zduplikowane.

Aby wypróbować to podejście, utwórz projekt zawierający dwie biblioteki STL. Następnie zmień właściwości projektu, aby importował biblioteki jako jednostki nagłówka zamiast ich dołączać, zgodnie z opisem w następnej sekcji.

Tworzenie projektu aplikacji konsoli w języku C++

Wykonaj następujące kroki, aby utworzyć projekt zawierający dwie biblioteki STL: <iostream> i <vector>.

1. W programie Visual Studio utwórz nowy projekt aplikacji konsolowej języka C++.

2. Zastąp zawartość pliku źródłowego w następujący sposób:

   #include <iostream>;
   #include <vector>;
   
   int main()
   {
       std::vector<int> numbers = {0, 1, 2};
       std::cout << numbers[1];
   }
   

Ustawianie opcji projektu i uruchamianie projektu

Poniższe kroki umożliwiają ustawienie opcji, która powoduje, że kompilator skanuje pod kątem dołączonych nagłówków w celu przetłumaczenia na jednostki nagłówka. Ustawiają również opcję, która powoduje, że kompilator traktuje #include się tak, jakby został zapisany import dla plików nagłówka, które mogą być traktowane jako jednostki nagłówka.

1. W menu głównym wybierz pozycję Właściwości projektu>, aby otworzyć okno dialogowe Strony właściwości projektu.
2. Wybierz pozycję Wszystkie konfiguracje z listy rozwijanej Konfiguracja , a następnie wybierz pozycję Wszystkie platformy z listy rozwijanej Platforma . Te ustawienia zapewniają, że zmiany mają zastosowanie zarówno do debugowania, jak i wydania oraz innych konfiguracji.
3. W lewym okienku okna dialogowego wybierz pozycję Właściwości>konfiguracji C/C++>General.
4. Ustaw opcję Źródła skanowania dla zależności modułu na wartość Tak. To ustawienie zapewnia, że wszystkie zgodne pliki nagłówków są kompilowane w jednostki nagłówka.
5. Ustaw opcję Translate Includes (Tłumaczenie dołączania) na Import (Importy ) na Wartość Tak. To ustawienie kompiluje pliki nagłówka STL wymienione w header-unit.json pliku jako jednostki nagłówka, a następnie importuje je zamiast używać preprocesora do #include nich.
6. Wybierz przycisk OK , aby zapisać zmiany i zamknąć okno dialogowe Strony właściwości projektu.

Opcja lub nowsza jest wymagana /std:c++20 do korzystania z jednostek nagłówka. Aby zmienić standard języka C++ używany przez kompilator:

1. W menu głównym wybierz pozycję Właściwości projektu>, aby otworzyć okno dialogowe Strony właściwości projektu.
2. Wybierz pozycję Wszystkie konfiguracje z listy rozwijanej Konfiguracja , a następnie wybierz pozycję Wszystkie platformy z listy rozwijanej Platforma . Te ustawienia zapewniają, że zmiany mają zastosowanie zarówno do debugowania, jak i wydania oraz innych konfiguracji.
3. W lewym okienku okna dialogowego Strony właściwości projektu wybierz pozycję Właściwości>konfiguracji Ogólne.
4. Na liście rozwijanej C++ Language Standard wybierz pozycję ISO C++20 Standard (/std:c++20) (lub nowsze).
5. Wybierz przycisk OK , aby zapisać zmiany i zamknąć okno dialogowe Strony właściwości projektu.
6. Z menu głównego skompiluj rozwiązanie, wybierając pozycję Kompiluj >rozwiązanie.

Uruchom rozwiązanie, aby sprawdzić, czy generuje oczekiwane dane wyjściowe: 1

Główną kwestią dotyczącą tego, czy należy użyć tego podejścia, jest równowaga między wygodą a kosztem skanowania wszystkich plików w celu określenia, które pliki nagłówkowe mają być kompilujące jako jednostki nagłówka.

Zobacz też

Porównanie jednostek nagłówka, modułów i wstępnie skompilowanych nagłówków
Samouczek: importowanie standardowej biblioteki języka C++ przy użyciu modułów
Przewodnik: kompilowanie i importowanie jednostek nagłówków w projektach Visual C++
/translateInclude