6.4 記錄項目版本信息以便報告 · cmake-cookbook

# 6.4 記錄項目版本信息以便報告 **NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-6/recipe-04 中找到，其中包含一個C和Fortran例子。該示例在CMake 3.5版(或更高版本)中是有效的，并且已經在GNU/Linux、macOS和Windows上進行過測試。* 代碼版本很重要，不僅是為了可重復性，還為了記錄API功能或簡化支持請求和bug報告。源代碼通常處于某種版本控制之下，例如：可以使用Git標記附加額外版本號(參見https://semver.org )。然而，不僅需要對源代碼進行版本控制，而且可執行文件還需要記錄項目版本，以便將其打印到代碼輸出或用戶界面上。本例中，將在CMake源文件中定義版本號。我們的目標是在配置項目時將程序版本記錄到頭文件中。然后，生成的頭文件可以包含在代碼的正確位置和時間，以便將代碼版本打印到輸出文件或屏幕上。 ## 準備工作將使用以下C文件(`example.c`)打印版本信息: ```c++ #include "version.h" #include <stdio.h> int main() { printf("This is output from code %s\n", PROJECT_VERSION); printf("Major version number: %i\n", PROJECT_VERSION_MAJOR); printf("Minor version number: %i\n", PROJECT_VERSION_MINOR); printf("Hello CMake world!\n"); } ``` 這里，假設`PROJECT_VERSION_MAJOR`、`PROJECT_VERSION_MINOR`和`PROJECT_VERSION`是在`version.h`中定義的。目標是從以下模板中生成`version.h.in`: ```c++ #pragma once #define PROJECT_VERSION_MAJOR @PROJECT_VERSION_MAJOR@ #define PROJECT_VERSION_MINOR @PROJECT_VERSION_MINOR@ #define PROJECT_VERSION_PATCH @PROJECT_VERSION_PATCH@ #define PROJECT_VERSION "v@PROJECT_VERSION@" ``` 這里使用預處理器定義，也可以使用字符串或整數常量來提高類型安全性(稍后我們將對此進行演示)。從CMake的角度來看，這兩種方法是相同的。 ## 如何實施我們將按照以下步驟，在模板頭文件中對版本進行注冊: 1. 要跟蹤代碼版本，我們可以在CMakeLists.txt中調用CMake的`project`時定義項目版本: ```cmake cmake_minimum_required(VERSION 3.5 FATAL_ERROR) project(recipe-04 VERSION 2.0.1 LANGUAGES C) ``` 2. 然后，基于`version.h.in`生成`version.h`: ```cmake configure_file( version.h.in generated/version.h @ONLY ) ``` 3. 最后，我們定義了可執行文件，并提供了目標包含路徑: ```cmake add_executable(example example.c) target_include_directories(example PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/generated ) ``` ## 工作原理當使用版本參數調用CMake的`project`時，CMake將為項目設置`PROJECT_VERSION_MAJOR`、`PROJECT_VERSION_MINOR`和`PROJECT_VERSION_PATCH`。此示例中的關鍵命令是`configure_file`，它接受一個輸入文件(本例中是`version.h.in`)，通過將`@`之間的占位符替換成對應的CMake變量，生成一個輸出文件(本例中是`generate/version.h`)。它將`@PROJECT_VERSION_MAJOR@`替換為2，以此類推。使用關鍵字`@ONLY`，我們將`configure_file`限制為只替換`@variables@`，而不修改`${variables}`。后一種形式在`version.h.in`中沒有使用。但是，當使用CMake配置shell腳本時，會經常出現。生成的頭文件可以包含在示例代碼中，可以打印版本信息: ```shell $ mkdir -p build $ cd build $ cmake .. $ cmake --build . $ ./example This is output from code v2.0.1 Major version number: 2 Minor version number: 0 Hello CMake world! ``` **NOTE**:*CMake以`x.y.z`格式給出的版本號，并將變量`PROJECT_VERSION`和` <project-name>_VERSION`設置為給定的值。此外,`PROJECT_VERSION_MAJOR`(`<project-name>_VERSION_MAJOR`),`PROJECT_VERSION_MINOR`(`<project-name>_VERSION_MINOR`) `PROJECT_VERSION_PATCH`(`<project-name>_VERSION_PATCH`)和`PROJECT_VERSION_TWEAK`(`<project-name>_VERSION_TWEAK`),將分別設置為`X`, `Y`, `Z`和`t`。* ## 更多信息為了確保只有當CMake變量被認為是一個真正的常量時，才定義預處理器變量，可以使用`configure_file`，在配置的頭文件中使用`#cmakedefin`而不是`#define`。根據是否定義了CMake變量并將其計算為一個真正的常量，`#cmakedefine YOUR_VARIABLE`將被替換為`#define YOUR_VARIABLE …`或者`/* #undef YOUR_VARIABLE */`。還有`#cmakedefine01`，將根據變量是否定義，將變量設置為`0`或`1`。