本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 搭配 FreeRTOS 使用 CMake **重要** 此頁面是指已棄用的 Amazon-FreeRTOS 儲存庫。我們建議您在建立新專案時從[這裡開始](freertos-getting-started-modular.md)。如果您已經有以現在已棄用的 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 [Amazon-FreeRTOS Github 儲存庫遷移指南](github-repo-migration.md)。 FreeRTOS 您可以使用 CMake 從 FreeRTOS 應用程式原始碼產生專案建置檔案，以及建置和執行原始碼。 您也可以使用 IDE 在符合 FreeRTOS 資格的裝置上編輯、偵錯、編譯、刷新和執行程式碼。每個電路板特定的入門指南都包含了設定 IDE 特定平台的說明。如果您偏好在沒有 IDE 的情況下作業，則可使用第三方的程式碼編輯與除錯工具來開發和除錯程式碼，再接著使用 CMake 建置並執行應用程式。 以下主機板支援使用 CMake： + Espressif ESP32-DevKitC + Espressif ESP-WROVER-KIT + Infineon XMC4800 IoT 連線套件 + Marvell MW320 AWS IoT Starter 套件 + Marvell MW322 AWS IoT Starter 套件 + Microchip Curiosity PIC32MZEF 套件 + Nordic nRF52840 DK Development kit + STMicroelectronicsSTM32L4 Discovery Kit IoT Node + Texas Instruments CC3220SF-LAUNCHXL + Microsoft Windows 模擬器 如需搭配 FreeRTOS 使用 CMake 的詳細資訊，請參閱下列主題。 **Topics** + [先決條件](#building-cmake-prereqs) + [使用第三方程式碼編輯器和偵錯工具開發 FreeRTOS 應用程式](#developing-third-party) + [使用 CMake 建置 FreeRTOS](#building-cmake) ## 先決條件 請確認您的主機機器符合下列先決條件，再繼續操作： + 您的裝置的編譯工具鏈必須支援該機器的作業系統。且 CMake 需支援 Windows、macOS 和 Linux 的所有版本。 不支援「適用於 Linux 的 Windows 子系統 (WSL)」。在 Windows 機器上使用原生 CMake。 + 您必須安裝 CMake 3.13 版或更新版本。 您可以從 [CMake.org](https://cmake.org/download/) 下載 CMake 的二進位分發。 **注意** 如果您已下載 CMake 的二進位分發版本，請務必先新增 CMake 可執行檔至 PATH 環境變數，再從命令列使用 CMake。 您也可以使用套件管理員來下載並安裝 CMake，例如 macOS 上的 [homebrew](https://brew.sh/)，以及 Windows 上的 [scoop](https://scoop.sh/) 或 [chocolatey](https://chocolatey.org/)。 **注意** 在許多 Linux 分發版本的套件管理員中，提供的 CMake 套件版本都已過時。如果分發版本的套件管理員未提供 CMake 最新版本，您可以嘗試換成其他套件管理員，例如 `linuxbrew` 或 `nix`。 + 您必須有相容的原生建置系統。 CMake 可以將許多原生建置系統當作目標，包括 [GNU Make](https://www.gnu.org/software/make/) 或 [Ninja](https://github.com/ninja-build/ninja/releases)。Make 和 Ninja 都可透過套件管理員來安裝在 Linux、macOS 和 Windows 上。如果您在 Windows 上使用 Make，則可從 [Equation](http://www.equation.com/servlet/equation.cmd?fa=make) 安裝獨立版本，或是安裝 Make 隨附的 [MinGW](https://sourceforge.net/projects/mingw-w64/files/)。 **注意** MinGW 中的 Make 可執行檔稱為 `mingw32-make.exe`，而不是 `make.exe`。 我們建議您使用 Ninja，因為它比 Make 更快，且可為所有桌面作業系統提供原生支援。 ## 使用第三方程式碼編輯器和偵錯工具開發 FreeRTOS 應用程式 您可以使用程式碼編輯器和偵錯擴充功能或第三方偵錯工具來開發 FreeRTOS 的應用程式。 舉例來說，如果您將 [Visual Studio 程式碼](https://code.visualstudio.com/)做為程式碼編輯器，就能將 [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) VS 程式碼擴充功能做為除錯工具進行安裝。應用程式開發完畢後，即可呼叫 CMake 命令列工具從 VS 程式碼內建置專案。如需使用 CMake 建置 FreeRTOS 應用程式的詳細資訊，請參閱 [使用 CMake 建置 FreeRTOS](#building-cmake)。 若要進行除錯，您可提供具備除錯組態的 VS 程式碼，該組態類似如下： ``` "configurations": [ { "name": "Cortex Debug", "cwd": "${workspaceRoot}", "executable": "./build/st/stm32l475_discovery/aws_demos.elf", "request": "launch", "type": "cortex-debug", "servertype": "stutil" } ] ``` ## 使用 CMake 建置 FreeRTOS 根據預設，CMake 以您的主機作業系統作為目標系統。若要將它用於跨編譯，CMake 需要指定您想使用之編譯器的工具鏈檔案。在 FreeRTOS 中，我們在 中提供預設的工具鏈檔案`freertos/tools/cmake/toolchains`。提供此檔案到 CMake 的方法取決於您是否使用 CMake 命令列界面或 GUI。有關更多詳細資訊，請參閱下面的 [產生建置檔案 (CMake 命令行工具)](#cmake-gen-cli) 指示。如需有關在 CMake 中跨編譯的詳細資訊，請參閱官方 CMake wiki 上的[跨編譯](https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling)。 **建置以 CMake 為基礎的專案** 1. 執行 CMake 來產生原生建置系統的建置檔案，例如 Make 或 Ninja。 您可以使用 [CMake 命令列工具](https://cmake.org/cmake/help/latest/manual/cmake.1.html)或 [CMake GUI](https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html)，為您的原生建置系統產生建置檔案。 如需產生 FreeRTOS 建置檔案的資訊，請參閱 [產生建置檔案 (CMake 命令行工具)](#cmake-gen-cli)和 [產生建置檔案 (CMake GUI)](#cmake-gen-gui)。 1. 叫用原生建置系統將專案製成可執行檔。 如需製作 FreeRTOS 組建檔案的資訊，請參閱 [從產生的建置檔案建置 FreeRTOS](#cmake-build)。 ### 產生建置檔案 (CMake 命令行工具) 您可以使用 CMake 命令列工具 (cmake) 來產生 FreeRTOS 的建置檔案。若要產生建置檔案，您需要指定一個目標電路板、編譯器和原始程式碼的位置並建立目錄。 您可將下列選項用於 cmake： + `-DVENDOR` – 指定目標電路板。 + `-DCOMPILER` – 指定編譯器。 + `-S` – 指定來源碼的位置。 + `-B` – 指定產生建置檔案的位置。 **注意** 編譯器必須在系統的 `PATH` 變數中，否則您必須指定編譯器的位置。 例如，如果廠商是 Texas Instruments，電路板是 CC3220 Launchpad，而編譯器是 GCC for ARM，您可以發出以下命令，從目前的目錄將下列原始檔案建置到名為 `build-directory` 的目錄中： ``` cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory ``` **注意** 如果您使用 Windows，則必須指定原生建置系統，因為 CMake 預設會使用 Visual Studio。例如： ``` cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G Ninja ``` 或者： ``` cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G "MinGW Makefiles" ``` 規則表達式 `${VENDOR}.*` 和 `${BOARD}.*` 用來搜尋相符的電路板，因此，您在 `VENDOR` 和 `BOARD` 選項中不需要使用廠商和電路板的全名。部分名稱假如只有單一相符項，亦可使用。例如，以下命令從相同的來源產生相同的建置檔案： ``` cmake -DVENDOR=ti -DCOMPILER=arm-ti -S . -B build-directory ``` ``` cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -S . -B build-directory ``` ``` cmake -DVENDOR=t -DBOARD=cc -DCOMPILER=arm-ti -S . -B build-directory ``` 如果您想要使用的工具鏈檔案不是位於預設目錄 `cmake/toolchains`，您可以使用 `CMAKE_TOOLCHAIN_FILE` 選項。例如： ``` cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -S . -B build-directory ``` 如果工具鏈檔案不使用絕對路徑來尋找您的編譯器，而且您未將您的編譯器新增到 `PATH` 環境變數，則 CMake 可能找不到它。為了確保 CMake 可找到您的工具鏈檔案，您可以使用 `AFR_TOOLCHAIN_PATH` 選項。此選項會搜尋指定的工具鏈目錄路徑和 `bin` 下的工具鏈子資料夾。例如： ``` cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -DAFR_TOOLCHAIN_PATH='/path/to/toolchain/' -S . -B build-directory ``` 若要啟用除錯，請將 `CMAKE_BUILD_TYPE` 設為 `debug`。啟用此選項後，CMake 會將偵錯旗標新增至編譯選項，並使用偵錯符號建置 FreeRTOS。 ``` # Build with debug symbols cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -DCMAKE_BUILD_TYPE=debug -S . -B build-directory ``` 您也可以將 `CMAKE_BUILD_TYPE` 設為 `release`，以將最佳化旗標新增到編譯選項。 ### 產生建置檔案 (CMake GUI) 您可以使用 CMake GUI 來產生 FreeRTOS 建置檔案。 **使用 CMake GUI 產生建置檔案** 1. 從命令列發出 `cmake-gui`，以啟動 GUI。 1. 選擇 **Browse Source (瀏覽來源)** 並指定來源輸入，然後選擇 **Browse Build (瀏覽建置)** 並指定建置輸出。 ![\[CMake 視窗包含來源碼位置和建置二進位位置的輸入欄位，以及瀏覽來源、瀏覽建置目錄、搜尋、新增或移除項目，以及檢視分組或進階選項的選項。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/cmake-gui1.png) 1. 選擇 **Configure (設定)**，然後在 **Specify the build generator for this project (指定此專案的建置產生器)** 下方，尋找和選擇您要用來建置所產生的建置檔案的建置系統。如果您沒有看到彈出式視窗，則您可能正在重複使用現有的建置目錄。在此情況下，請從**檔案**功能表中選擇刪除快取，以刪除 CMake 快取。 **** ![\[CMakeSetup 對話方塊具有選項，可將專案的產生器指定為 Unix Makefiles，並指定工具鏈檔案進行交叉編譯。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/cmake-gui2.png) 1. 選擇 **Specify toolchain file for cross-compiling (指定跨編譯的工具鏈檔案)**，然後選擇 **Next (下一步)**。 1. 選擇工具鏈檔案 (例如，`freertos/tools/cmake/toolchains/arm-ti.cmake`)，然後選擇 **Finish (完成)**。 FreeRTOS 的預設組態是範本板，它不提供任何可攜式層目標。因此，將出現含有訊息 Error in configuration process 的視窗。 **注意** 如果您看到以下錯誤： ``` CMake Error at tools/cmake/toolchains/find_compiler.cmake:23 (message): Compiler not found, you can specify search path with AFR_TOOLCHAIN_PATH. ``` 表示該編譯器不在您的 `PATH` 環境變數中。您可以在 GUI 中設定 `AFR_TOOLCHAIN_PATH` 變數，以告訴 CMake 您安裝編譯器的位置。如果您沒有看到 `AFR_TOOLCHAIN_PATH` 變數，請選擇 **Add Entry (新增項目)**。在彈出視窗中的 **Name (名稱)** 下輸入 **AFR\$1TOOLCHAIN\$1PATH**。在 **Compiler Path (編譯器路徑)** 輸入編譯器路徑。例如，`C:/toolchains/arm-none-eabi-gcc`。 1. GUI 現在應該看起來像這樣： ![\[CMake 組態視窗，用於在選取廠商電路板、啟用模組並指定建置路徑的情況下建置 FreeRTOS。\]](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/cmake-gui3.png) 選擇 **AFR\$1BOARD**，選擇您的電路板，然後再次選擇 **Configure (設定)**。 1. 選擇 **Generate (產生)**。CMake 會產生建置系統檔案 (例如，makefiles 或 ninja 檔案)，這些檔案會出現在您在第一個步驟中指定的建置目錄中。請按照下一節的指示來產生二進位影像。 ### 從產生的建置檔案建置 FreeRTOS #### 使用原生建置系統進行建置 您可以從輸出二進位目錄呼叫建置系統命令，以原生建置系統建置 FreeRTOS。 例如，如果您的建置檔案輸出目錄是 ``，而且您使用 Make 作為原生建置系統，請執行下列命令： ``` cd make -j4 ``` #### 使用 CMake 建置 您也可以使用 CMake 命令列工具來建置 FreeRTOS。CMake 提供抽象層來呼叫原生建置系統。例如： ``` cmake --build build_dir ``` 以下是 CMake 命令列工具建置模式的一些其他常見用法： ``` # Take advantage of CPU cores. cmake --build build_dir --parallel 8 ``` ``` # Build specific targets. cmake --build build_dir --target afr_kernel ``` ``` # Clean first, then build. cmake --build build_dir --clean-first ``` 如需 CMake 建置模式的詳細資訊，請參閱 [CMake 文件](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-tool-mode)。