Panduan: Mengimpor pustaka STL sebagai unit header

Artikel
04/03/2023

Panduan ini menunjukkan cara mengimpor pustaka Pustaka Templat Standar (STL) C++ sebagai unit header di Visual Studio. Untuk cara yang lebih cepat dan lebih kuat untuk mengimpor pustaka standar, lihat Tutorial: Mengimpor pustaka standar C++ menggunakan modul.

Mengimpor header STL sebagai unit header lebih sederhana daripada menggunakan file header yang telah dikompresi. Unit header lebih mudah disiapkan dan digunakan, secara substansial lebih kecil pada disk, memberikan manfaat performa yang sama, dan lebih fleksibel daripada PCH bersama.

Untuk informasi lebih rinci tentang unit header apa dan manfaat yang mereka berikan, lihat Apa itu unit header?. Untuk membandingkan unit header dengan cara lain untuk mengimpor pustaka standar, lihat Membandingkan unit header, modul, dan header yang telah dikommpilasikan sebelumnya.

Prasyarat

Untuk menggunakan unit header, gunakan Visual Studio 2022 atau yang lebih baru, atau Visual Studio 2019 versi 16.11 atau yang lebih baru. Opsi /std:c++20 (atau yang lebih baru) diperlukan untuk menggunakan unit header.

Dua pendekatan untuk mengimpor header STL sebagai unit header

Sebelum Anda dapat mengimpor header STL, header harus dikompilasi ke dalam unit header. Unit header adalah representasi biner dari file header. Ini memiliki .ifc ekstensi.

Pendekatan yang disarankan adalah membuat pustaka statis yang berisi unit header bawaan untuk header STL yang ingin Anda gunakan. Kemudian referensikan pustaka tersebut dan import unit headernya. Pendekatan ini dapat menghasilkan build yang lebih cepat dan penggunaan kembali yang lebih baik. Untuk mencoba pendekatan ini, lihat Pendekatan 1: Membuat pustaka statis unit header pustaka STL.

Pendekatan lain adalah meminta Visual Studio memindai header STL yang Anda #include gunakan dalam proyek, mengkompilasinya ke dalam unit header, dan import bukan #include header tersebut. Pendekatan ini berguna jika Anda memiliki basis kode besar, karena Anda tidak perlu mengubah kode sumber Anda. Pendekatan ini kurang fleksibel daripada pendekatan pustaka statis, karena tidak meminjamkan dirinya untuk menggunakan kembali unit header bawaan di proyek lain. Namun, Anda masih mendapatkan keuntungan performa dari mengimpor pustaka STL individual sebagai unit header. Untuk mencoba pendekatan ini, lihat Pendekatan 2: Pemindaian menyertakan header STL untuk diimpor.

Pendekatan 1: Membuat pustaka statis unit header pustaka STL

Cara yang disarankan untuk menggunakan pustaka STL sebagai unit header adalah dengan membuat satu atau beberapa proyek pustaka statis. Proyek-proyek ini harus terdiri dari unit header pustaka STL yang ingin Anda gunakan. Kemudian, referensikan proyek pustaka untuk menggunakan unit header STL tersebut. Ini mirip dengan menggunakan header bersama yang telah dikommpilasikan sebelumnya, tetapi lebih mudah.

Unit header (dan modul) yang dibangun dalam proyek pustaka statis secara otomatis tersedia untuk mereferensikan proyek karena sistem proyek secara otomatis menambahkan opsi baris perintah yang sesuai /headerUnit ke pengkompilasi sehingga proyek referensi dapat mengimpor unit header.

Pendekatan ini memastikan bahwa unit header untuk header tertentu hanya dibangun sekali. Ini memungkinkan Anda mengimpor beberapa atau semua unit header, yang tidak dimungkinkan dengan PCH. Anda dapat menyertakan unit header dalam urutan apa pun.

Dalam contoh berikut, Anda membuat proyek pustaka statis yang terdiri dari <iostream> unit header dan <vector> . Setelah solusi dibuat, Anda akan mereferensikan proyek unit header bersama ini dari proyek C++ lain. Di mana pun atau import <vector>; ditemukan, unit header bawaan untuk pustaka tersebut digunakan alih-alih import <iostream>; menerjemahkan header dengan praproscessor. Ini meningkatkan performa build, seperti yang dilakukan file PCH, ketika header yang sama disertakan dalam beberapa file. Header tidak perlu diproses berulang kali oleh file yang menyertakannya. Sebagai gantinya, unit header yang dikompilasi yang sudah diproses diimpor.

Untuk membuat pustaka statis yang berisi pustaka <iostream> STL dan <vector>, ikuti langkah-langkah berikut:

Buat proyek C++ kosong. Beri nama SharedPrj.
Pilih Proyek Kosong untuk C++ dari jenis proyek yang tersedia di jendela Buat proyek baru:
Tambahkan file C++ baru ke proyek. Ubah konten file menjadi:
```
import <iostream>;
import <vector>;
```

Mengatur properti proyek

Atur properti proyek untuk berbagi unit header dari proyek ini:

Pada menu utama Visual Studio, pilih Properti SharedPrj Proyek>untuk membuka dialog Halaman Properti proyek:
Pilih Semua Konfigurasi di daftar dropdown Konfigurasi , lalu pilih Semua Platform di daftar dropdown Platform . Pengaturan ini memastikan bahwa perubahan Anda berlaku apakah Anda sedang membangun untuk debug atau rilis.
Di panel kiri dialog Halaman Properti proyek, pilih Properti>Konfigurasi Umum.
Ubah opsi Jenis Konfigurasi menjadi Pustaka statis (.lib).
Ubah Standar Bahasa C++ menjadi ISO C++20 Standard (/std:c++20) (atau yang lebih baru).
Di panel kiri dialog Halaman Properti proyek, pilih Properti>Konfigurasi C/C++>Umum.
Di daftar dropdown Sumber Pemindaian untuk Dependensi Modul, pilih Ya. (Opsi ini menyebabkan pengkompilasi memindai kode Anda untuk dependensi yang dapat dibangun ke dalam unit header):
Pilih OK untuk menutup dialog Halaman Properti proyek. Bangun solusi dengan memilih Build>Build Solution pada menu utama.

Mereferensikan pustaka unit header

Untuk mengimpor <iostream> dan <vector> sebagai unit header dari pustaka statis, buat proyek yang mereferensikan pustaka statis sebagai berikut:

Dengan solusi saat ini masih terbuka, pada menu Visual Studio, pilih Tambahkan>File>Proyek Baru.
Di wizard Buat proyek baru, pilih templat Aplikasi Konsol C++ dan pilih Berikutnya.
Beri nama proyek baru Walkthrough. Ubah dropdown Solusi ke Tambahkan ke solusi. Pilih Buat untuk membuat proyek dan menambahkannya ke solusi Anda.

Ubah konten file sumber Walkthrough.cpp sebagai berikut:

import <iostream>;
import <vector>;

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

Unit header memerlukan /std:c++20 opsi (atau yang lebih baru). Atur standar bahasa dengan menggunakan langkah-langkah berikut:

Di Penjelajah Solusi, klik kanan proyek Penelusuran dan pilih Properti untuk membuka dialog Halaman Properti proyek:
Di panel kiri dialog Halaman Properti proyek Penelusuran, pilih Properti>Konfigurasi Umum.
Di menu dropdown Standar Bahasa C++, pilih ISO C++20 Standard (/std:c++20) (atau yang lebih baru).
Pilih OK untuk menutup dialog Halaman Properti proyek.

Dalam proyek Panduan, tambahkan referensi ke proyek SharedPrj dengan langkah-langkah berikut:

Di proyek Penelusuran, pilih simpul Referensi, lalu pilih Tambahkan Referensi. Pilih SharedPrj dalam daftar proyek: Menambahkan referensi ini menyebabkan sistem build menggunakan unit header yang dibangun oleh SharedPrj setiap kali dalam proyek Walkthrough cocok dengan salah satu unit header bawaan di SharedPrj.import
Pilih OK untuk menutup dialog Tambahkan Referensi .
Klik kanan proyek Penelusuran dan pilih Atur sebagai Proyek Startup.
Bangun solusinya. (Gunakan Bangun>Build Solution pada menu utama.) Jalankan untuk melihat bahwa ia menghasilkan output yang diharapkan: 1

Keuntungan dari pendekatan ini adalah Anda dapat mereferensikan proyek pustaka statis dari proyek apa pun untuk menggunakan kembali unit header di dalamnya. Dalam contoh ini, pustaka statis berisi <vector> unit header dan <iostream> .

Anda dapat membuat proyek pustaka statis monolitik yang berisi semua header STL yang umum digunakan yang ingin Anda impor dari berbagai proyek Anda. Atau Anda dapat membuat proyek pustaka bersama yang lebih kecil untuk berbagai pengelompokan pustaka STL yang ingin Anda impor sebagai unit header. Kemudian referensikan proyek unit header bersama tersebut sesuai kebutuhan.

Hasilnya harus ditingkatkan throughput build karena mengimpor unit header secara signifikan mengurangi pekerjaan yang harus dilakukan pengkompilasi.

Saat Anda menggunakan pendekatan ini dengan proyek Anda sendiri, buat proyek pustaka statis dengan opsi kompilator yang kompatibel dengan proyek yang mereferensikannya. Misalnya, proyek STL harus dibangun dengan /EHsc opsi pengkompilasi untuk mengaktifkan penanganan pengecualian, dan begitu juga proyek yang mereferensikan proyek pustaka statis.

Menggunakan `/translateInclude`

Opsi /translateInclude pengkompilasi (tersedia dalam dialog Halaman Properti proyek di bawah C/C++>General>Translate Includes to Imports) memudahkan Anda untuk menggunakan pustaka unit header di proyek lama yang #include pustaka STL. Ini membuatnya tidak perlu mengubah #include arahan ke import dalam proyek Anda, sambil tetap memberi Anda keuntungan mengimpor unit header alih-alih menyertakannya.

Misalnya, jika Anda memiliki #include <vector> dalam proyek dan mereferensikan pustaka statis yang berisi unit header untuk <vector>, Anda tidak perlu mengubah #include <vector> secara manual ke import <vector>; dalam kode sumber Anda. Sebaliknya, pengkompilasi secara otomatis memperlakukan #include <vector> sebagai import <vector>;. Untuk informasi selengkapnya tentang pendekatan ini, lihat Pendekatan 2: Pemindaian menyertakan header STL untuk diimpor. Tidak semua file header STL dapat dikompilasi ke unit header. Dikirim header-units.json dengan Visual Studio mencantumkan file header STL mana yang dapat dikompilasi ke dalam unit header. Header yang bergantung pada makro untuk menentukan perilakunya sering tidak dapat dikompilasi ke dalam unit header.

Pernyataan #include yang tidak merujuk ke unit header diperlakukan sebagai normal #include.

Menggunakan kembali unit header di antara proyek

Unit header yang dibangun oleh proyek pustaka statis secara otomatis tersedia untuk semua proyek yang dirujuk secara langsung dan tidak langsung. Ada pengaturan proyek yang memungkinkan Anda memilih unit header mana yang harus secara otomatis tersedia untuk semua proyek referensi. Pengaturan berada dalam pengaturan proyek di bawah Direktori VC++.

Di Penjelajah Solusi, klik kanan proyek dan pilih Properti untuk membuka dialog Halaman Properti proyek.
Di panel kiri dialog, pilih Properti>Konfigurasi VC++ Direktori:

Properti berikut mengontrol visibilitas unit header ke sistem build:

Direktori Sertakan Publik menentukan direktori proyek untuk unit header yang harus secara otomatis ditambahkan ke jalur sertakan dalam mereferensikan proyek.
Direktori Modul C++ Publik menentukan direktori proyek mana yang berisi unit header yang harus tersedia untuk mereferensikan proyek. Properti ini memungkinkan Anda untuk membuat beberapa unit header menjadi publik. Ini terlihat oleh proyek lain, jadi letakkan unit header yang ingin Anda bagikan di sini. Jika Anda menggunakan pengaturan ini, untuk kenyamanan, tentukan Direktori Sertakan Publik untuk secara otomatis menambahkan header publik Anda ke jalur Sertakan dalam mereferensikan proyek.
Semua Modul bersifat Publik: saat Anda menggunakan unit header yang dibangun sebagai bagian dari proyek DLL, simbol harus diekspor dari DLL. Untuk mengekspor simbol modul secara otomatis, atur properti ini ke Ya.

Menggunakan file modul bawaan

Biasanya, cara term mudah untuk menggunakan kembali unit header di antara solusi adalah dengan mereferensikan proyek unit header bersama dari setiap solusi.

Jika Anda harus menggunakan unit header bawaan yang tidak memiliki proyek, Anda dapat menentukan di mana file bawaan .ifc berada sehingga Anda dapat mengimpornya dalam solusi Anda. Untuk mengakses pengaturan ini:

Pada menu utama, pilih Properti Proyek>untuk membuka dialog Halaman Properti proyek.
Di panel kiri dialog, pilih Properti>Konfigurasi C/C++>Umum.
Di Dependensi Modul Tambahan, tambahkan modul ke referensi, dipisahkan oleh titik koma. Berikut adalah contoh format yang akan digunakan untuk Dependensi Modul Tambahan: ModuleName1=Path\To\ModuleName1.ifc; ModuleName2=Path\To\ModuleName2.ifc

Pilih di antara beberapa salinan unit header

Jika Anda mereferensikan proyek yang membangun beberapa unit header, baik dengan nama yang sama atau untuk file header yang sama, Anda harus menentukan mana yang akan digunakan. Anda mungkin memiliki versi unit header yang berbeda yang dibangun dengan pengaturan pengkompilasi yang berbeda, misalnya, dan harus menentukan versi yang cocok dengan pengaturan proyek Anda.

Gunakan properti Dependensi Unit Header Tambahan proyek untuk mengatasi tabrakan dengan menentukan unit header mana yang akan digunakan. Jika tidak, tidak mungkin untuk memprediksi mana yang dipilih.

Untuk mengatur properti Dependensi Unit Header Tambahan:

Pada menu utama, pilih Properti Proyek>untuk membuka dialog Halaman Properti proyek.
Di panel kiri dialog, pilih Properti>Konfigurasi C/C++>Umum.
Tentukan modul atau file unit header mana yang akan digunakan dalam Dependensi Unit Header Tambahan untuk mengatasi tabrakan. Gunakan format ini untuk Dependensi Unit Header Tambahan: Path\To\Header1.h= Path\To\HeaderUnit1.ifc;Path\To\Header2.h= Path\To\ HeaderUnit2.ifc

Penting

Pastikan bahwa proyek yang berbagi unit header dibangun dengan opsi kompilasi yang kompatibel. Jika Anda menggunakan opsi kompilasi saat mengimplementasikan unit header yang berbeda dari yang Anda gunakan saat membuatnya, pengkompilasi akan mengeluarkan peringatan.

Catatan

Untuk menggunakan unit header yang dibangun sebagai bagian dari proyek DLL, atur Semua Modul adalah Publik ke Ya.

Pendekatan 2: Pemindaian mencakup header STL untuk diimpor

Cara lain untuk mengimpor pustaka STL adalah dengan memindai Visual Studio untuk header STL yang Anda #include miliki di proyek Anda dan mengkompilasinya ke dalam unit header. Pengkompilasi kemudian mengimpor daripada menyertakan header tersebut.

Opsi ini nyaman ketika proyek Anda menyertakan banyak file header STL di banyak file, atau saat throughput build tidak penting. Opsi ini tidak menjamin bahwa unit header untuk file header tertentu hanya dibuat sekali. Namun, ini berguna jika Anda memiliki basis kode besar: Anda tidak perlu mengubah kode sumber untuk memanfaatkan manfaat unit header untuk banyak pustaka STL yang Anda gunakan.

Pendekatan ini kurang fleksibel daripada pendekatan pustaka statis, karena tidak meminjamkan dirinya untuk menggunakan kembali unit header yang dibangun di proyek lain. Pendekatan ini mungkin tidak sesuai untuk proyek yang lebih besar: Ini tidak menjamin waktu build yang optimal, karena semua sumber harus dipindai untuk #include pernyataan.

Tidak semua file header dapat dikonversi secara otomatis ke unit header. Misalnya, header yang bergantung pada kompilasi kondisional melalui makro tidak boleh dikonversi ke unit header. Ada daftar yang diizinkan dalam bentuk header-units.jsonfile untuk header STL yang digunakan pengkompilasi saat /translateInclude ditentukan. Ini menentukan header STL mana yang dapat dikompilasi ke dalam unit header. File header-units.json berada di bawah direktori penginstalan untuk Visual Studio. Misalnya, %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json. Jika file header STL tidak ada dalam daftar, file tersebut diperlakukan sebagai normal #include alih-alih mengimpornya sebagai unit header. Keuntungan lain dari header-units.json file adalah mencegah duplikasi simbol di unit header bawaan. Artinya, jika mengkompilasi unit header membawa header pustaka lain beberapa kali, simbol tidak akan diduplikasi.

Untuk mencoba pendekatan ini, buat proyek yang menyertakan dua pustaka STL. Kemudian, ubah properti proyek sehingga mengimpor pustaka sebagai unit header alih-alih menyertakannya, seperti yang dijelaskan di bagian berikutnya.

Membuat proyek aplikasi konsol C++

Ikuti langkah-langkah ini untuk membuat proyek yang menyertakan dua pustaka STL: <iostream> dan <vector>.

Di Visual Studio, buat proyek aplikasi konsol C++ baru.

Ganti konten file sumber sebagai berikut:

#include <iostream>;
#include <vector>;

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

Mengatur opsi proyek dan menjalankan proyek

Langkah-langkah berikut mengatur opsi yang menyebabkan pengkompilasi memindai header yang disertakan diterjemahkan ke dalam unit header. Mereka juga mengatur opsi yang menyebabkan pengkompilasi memperlakukan #include seolah-olah Anda telah menulis import untuk file header yang dapat diperlakukan sebagai unit header.

Pada menu utama, pilih Properti Proyek>untuk membuka dialog Halaman Properti proyek.
Pilih Semua Konfigurasi di daftar dropdown Konfigurasi , lalu pilih Semua Platform di daftar dropdown Platform . Pengaturan ini memastikan bahwa perubahan Anda berlaku apakah Anda membangun untuk debug atau rilis, dan konfigurasi lainnya.
Di panel kiri dialog, pilih Properti>Konfigurasi C/C++>Umum.
Atur Sumber Pemindaian untuk Dependensi Modul ke Ya. Pengaturan ini memastikan bahwa semua file header yang kompatibel dikompilasi ke dalam unit header.
Atur Terjemahkan Termasuk ke Impor ke Ya. Pengaturan ini mengkompilasi file header STL yang tercantum dalam header-unit.json file sebagai unit header, lalu mengimpornya alih-alih menggunakan pra-prosesor ke #include file tersebut.
Pilih OK untuk menyimpan perubahan Anda dan menutup dialog Halaman Properti proyek.

Opsi /std:c++20 atau yang lebih baru diperlukan untuk menggunakan unit header. Untuk mengubah standar bahasa C++ yang digunakan oleh pengkompilasi:

Pada menu utama, pilih Properti Proyek>untuk membuka dialog Halaman Properti proyek.
Pilih Semua Konfigurasi di daftar dropdown Konfigurasi , lalu pilih Semua Platform di daftar dropdown Platform . Pengaturan ini memastikan bahwa perubahan Anda berlaku apakah Anda membangun untuk debug atau rilis, dan konfigurasi lainnya.
Di panel kiri dialog Halaman Properti proyek, pilih Properti>Konfigurasi Umum.
Di daftar dropdown Standar Bahasa C++, pilih ISO C++20 Standard (/std:c++20) (atau yang lebih baru).
Pilih OK untuk menyimpan perubahan Anda dan menutup dialog Halaman Properti proyek.
Dari menu utama, buat solusi dengan memilih Build>Build Solution.

Jalankan solusi untuk memverifikasi bahwa solusi menghasilkan output yang diharapkan: 1

Pertimbangan utama apakah akan menggunakan pendekatan ini adalah keseimbangan antara kenyamanan dan biaya pemindaian semua file Anda untuk menentukan file header mana yang akan dibangun sebagai unit header.

Bagikan melalui

Panduan: Mengimpor pustaka STL sebagai unit header

Prasyarat

Dua pendekatan untuk mengimpor header STL sebagai unit header