教學課程：搭配 vcpkg 安裝和使用套件

發行項
05/01/2024

本教學課程說明如何建立 C++ “Hello World” 程式，以搭配 CMake 和 vcpkg 使用 fmt 連結庫。您將安裝相依性、設定、建置和執行簡單的應用程式。

必要條件

終端機
C++ 編譯器
CMake
Git

注意

針對 Windows 使用者，Visual Studio 的 MSVC（Microsoft Visual C++ 編譯程式）是 C++ 開發所需的編譯程式。

1 - 設定 vcpkg

複製存放庫

第一個步驟是從 GitHub 複製 vcpkg 存放庫。存放庫包含可取得 vcpkg 可執行文件的腳本，以及 vcpkg 社群所維護之策劃開放原始碼連結庫的登錄。若要這樣做，請執行：
```
git clone https://github.com/microsoft/vcpkg.git
```
vcpkg 策展登錄是一組超過 2,000 個開放原始碼連結庫。這些連結庫已由 vcpkg 的持續整合管線進行驗證，以共同運作。雖然 vcpkg 存放庫不包含這些連結庫的原始程式碼，但它會保存配方和元數據，以在您的系統中建置並安裝它們。
執行啟動程式腳本

既然您已複製 vcpkg 存放庫，請瀏覽至 vcpkg 目錄並執行啟動程式腳本：
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
啟動程式腳本會執行必要條件檢查，並下載 vcpkg 可執行檔。

介紹完畢 vcpkg 已設定且可供使用。

2 - 設定專案

設定 VCPKG_ROOT 環境變數。
```
export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH
```
注意

使用 export 命令設定環境變數只會影響目前的殼層會話。若要讓此變更在會話之間永久完成，請將命令新增 export 至殼層的配置檔腳本（例如 ~/.bashrc 或 ~/.zshrc）。
```
set VCPKG_ROOT="C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%
```
注意

以這種方式設定環境變數只會影響目前的終端機會話。若要在所有工作階段中永久進行這些變更，請透過 [Windows 系統環境變數] 面板加以設定。
```
$env:VCPKG_ROOT = "C:\path\to\vcpkg"
$env:PATH = "$env:VCPKG_ROOT;$env:PATH"
```
注意

以這種方式設定環境變數只會影響目前的終端機會話。若要在所有工作階段中永久進行這些變更，請透過 [Windows 系統環境變數] 面板加以設定。
設定 VCPKG_ROOT 會告知 vcpkg 實例所在的位置。新增它以確保 PATH 您可以直接從殼層執行 vcpkg 命令。
建立項目目錄。
```
mkdir helloworld && cd helloworld
```

3 - 新增相依性和項目檔

建立指令清單檔案並新增 fmt 相依性。

首先，從 helloworld 目錄中執行 vcpkg new 命令，在項目的目錄中建立指令清單檔（vcpkg.json）：
```
vcpkg new --application
```
接下來，新增 fmt 相依性：
```
vcpkg add port fmt
```
您的 vcpkg.json 應該會顯示如下：
```
{
    "dependencies": [
        "fmt"
    ]
}
```
這是您的指令清單檔案。 vcpkg 會讀取指令清單檔，以瞭解要安裝和整合哪些相依性與 CMake，以提供專案所需的相依性。

默認 vcpkg-configuration.json 檔案引進基準條件約束，指定項目應該使用的相依性最低版本。雖然修改此檔案超出本教學課程的範圍，但在定義專案相依性的版本限制時扮演重要角色。因此，即使本教學課程並非絕對必要，但最好將新增 vcpkg-configuration.json 至原始檔控制，以確保不同開發環境的版本一致性。
建立項目檔。

CMakeLists.txt使用下列內容建立檔案：
```
cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)

add_executable(HelloWorld main.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)
```
現在，讓我們細分檔案中 CMakeLists.txt 每一行的功能：
- cmake_minimum_required(VERSION 3.10)：指定建置專案所需的 CMake 最低版本為 3.10。如果您的系統上安裝的 CMake 版本低於此版本，則會產生錯誤。
- project(HelloWorld)：將專案的名稱設定為「HelloWorld」。。
- find_package(fmt CONFIG REQUIRED)：使用其 CMake 組態檔尋找連結 fmt 庫。關鍵詞 REQUIRED 可確保找不到套件時，會產生錯誤。
- add_executable(HelloWorld main.cpp)：新增名為「HelloWorld」的可執行檔目標，從原始程式檔 main.cpp建置。
- target_link_libraries(HelloWorld PRIVATE fmt::fmt)：指定 HelloWorld 可執行文件應該連結至 fmt 連結庫。關鍵詞 PRIVATE 表示 fmt 只需要建置 HelloWorld ，且不應該傳播至其他相依專案。
main.cpp使用下列內容建立檔案：
```
#include <fmt/core.h>

int main()
{
    fmt::print("Hello World!\n");
    return 0;
}
```
在此 main.cpp 檔案中， <fmt/core.h> 會包含使用連結庫的 fmt 標頭。函式 main() 接著會呼叫 fmt::print() ，將 “Hello World！” 訊息輸出至控制台。

4 - 建置並執行專案

執行 CMake 設定

若要允許 CMake 專案系統辨識 vcpkg 所提供的 C++ 連結庫，您必須提供 vcpkg.cmake 工具鏈檔案。若要將此作業自動化，請使用下列內容在「helloworld」目錄中建立 CMakePresets.json 檔案：
```
{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}
```
此 CMakePresets.json 檔案包含 CMake 的單一「預設」預設值，並設定 CMAKE_TOOLCHAIN_FILE 變數。 CMAKE_TOOLCHAIN_FILE允許 CMake 專案系統辨識 vcpkg 所提供的 C++ 連結庫。新增會將 CMakePresets.json 執行 CMake 時指定工具鏈的程式自動化。

使用 CMake 設定組建：
```
cmake --preset=default
```
建置專案

請執行：
```
cmake --build build
```
執行應用程式

最後，執行可執行檔以查看您的應用程式運作情形：
```
./build/HelloWorld

Hello World!
```
```
.\build\HelloWorld.exe

Hello World!
```

下一步

若要深入瞭解 vcpkg.json，請參閱我們的參考檔：

教學課程：搭配 vcpkg 安裝和使用套件

必要條件

1 - 設定 vcpkg

2 - 設定專案

3 - 新增相依性和項目檔

4 - 建置並執行專案

下一步

意見反應

其他資源