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

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

必要條件

注意

針對 Windows 使用者,Visual Studio 的 MSVC(Microsoft Visual C++ 編譯程式)是 C++ 開發所需的編譯程式。

1 - 設定 vcpkg

  1. 複製存放庫

    第一個步驟是從 GitHub 複製 vcpkg 存放庫。 存放庫包含可取得 vcpkg 可執行文件的腳本,以及 vcpkg 社群所維護之策劃開放原始碼連結庫的登錄。 若要這樣做,請執行:

    git clone https://github.com/microsoft/vcpkg.git
    

    vcpkg 策展登錄是一組超過 2,000 個開放原始碼連結庫。 這些連結庫已由 vcpkg 的持續整合管線進行驗證,以共同運作。 雖然 vcpkg 存放庫不包含這些連結庫的原始程式碼,但它會保存配方和元數據,以在您的系統中建置並安裝它們。

  2. 執行啟動程式腳本

    既然您已複製 vcpkg 存放庫,請瀏覽至 vcpkg 目錄並執行啟動程式腳本:

    cd vcpkg && bootstrap-vcpkg.bat
    
    cd vcpkg; .\bootstrap-vcpkg.bat
    
    cd vcpkg && ./bootstrap-vcpkg.sh
    

    啟動程式腳本會執行必要條件檢查,並下載 vcpkg 可執行檔。

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

2 - 設定專案

  1. 設定 VCPKG_ROOT 環境變數。

    export VCPKG_ROOT=/path/to/vcpkg
    export PATH=$VCPKG_ROOT:$PATH
    

    注意

    使用 export 命令設定VCPKG_ROOT環境變數只會影響目前的殼層會話。 若要讓此變更在會話之間永久完成,您必須將命令新增 export 至殼層的配置檔腳本(例如 ~/.bashrc~/.zshrc)。

    set VCPKG_ROOT="C:\path\to\vcpkg"
    set PATH=%VCPKG_ROOT%;%PATH%
    

    注意

    使用 set 命令設定VCPKG_ROOT環境變數只會影響目前的殼層會話。 若要讓此變更在會話之間永久完成,您可以使用 setx 命令並重新啟動殼層會話。

    $env:VCPKG_ROOT = "C:\path\to\vcpkg"
    $env:PATH = "$env:VCPKG_ROOT;$env:PATH"
    

    注意

    VCPKG_ROOT以這種方式設定及更新PATH環境變數只會影響目前的PowerShell會話。 若要在所有工作階段中永久進行這些變更,您應該將它們新增至PowerShell配置檔,或透過 [Windows 系統環境變數] 面板加以設定。

    設定 VCPKG_ROOT 會告知 vcpkg 實例所在的位置。 新增它以確保 PATH 您可以直接從殼層執行 vcpkg 命令。

  2. 建立項目目錄。

    mkdir helloworld && cd helloworld
    

3 - 新增相依性和項目檔

  1. 建立指令清單檔案並新增 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 至原始檔控制,以確保不同開發環境的版本一致性。

  2. 建立項目檔。

    CMakeLists.txt使用下列內容建立檔案:

    cmake_minimum_required(VERSION 3.10)
    
    project(HelloWorld)
    
    find_package(fmt CONFIG REQUIRED)
    
    add_executable(HelloWorld helloworld.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 - 建置並執行專案

  1. 執行 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
    
  2. 建置專案

    請執行:

    cmake --build build
    
  3. 執行應用程式

    最後,執行可執行檔以查看您的應用程式運作情形:

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

下一步

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