构建系统

The Nexus Embedded Platform uses CMake with CMake Presets as its build system, providing a modern, flexible, and cross-platform build infrastructure. This guide covers the CMake structure, preset-based workflow, build options, testing, and cross-compilation setup.

概述

Nexus 构建系统旨在支持：

• CMake Presets：为所有平台预配置的构建配置

• 多目标平台：Native、STM32F4、STM32H7、GD32、ESP32、nRF52

• 多 OSAL 后端：裸机、FreeRTOS、RT-Thread、Zephyr

• 交叉编译：ARM Cortex-M 目标，带工具链管理

• 自动化配置：基于 Kconfig 的配置生成

• 全面测试：GoogleTest 与 CTest 集成

• 代码覆盖率：内置覆盖率分析支持

• CI/CD 就绪：包含 GitHub Actions 工作流

参见

• Kconfig 配置系统 - Configuration system overview

• Kconfig 教程 - Kconfig tutorial

• IDE Integration - IDE 集成指南

• Build Scripts and Tools - Build scripts documentation

• 平台 Guides - Platform-specific build instructions

• 您的第一个 Nexus 应用程序 - Building your first application

主要特性

✨ 现代化 CMake Presets

为所有平台和编译器预配置构建设置，确保团队间构建一致性。

🚀 快速并行构建

多核编译支持，自动检测作业数。

🧪 集成测试

CTest 集成，包含 1600+ 单元测试和基于属性的测试。

📊 覆盖率分析

内置代码覆盖率支持，用于质量保证。

🔧 IDE 集成

原生支持 VS Code、Visual Studio 和 CLion。

🤖 CI/CD 就绪

GitHub Actions 工作流，支持多平台测试。

Build Workflow

The following diagram illustrates the complete build workflow from configuration to final binary:

        flowchart TD
    START([Start Build]) --> PRESET{Choose Method}

    PRESET -->|CMake Presets| SELECTPRESET[Select Preset]
    PRESET -->|Build Script| BUILDSCRIPT[Use build.py]
    PRESET -->|Manual CMake| MANUAL[Manual Configuration]

    SELECTPRESET --> KCONFIG[Configure with Kconfig]
    BUILDSCRIPT --> KCONFIG
    MANUAL --> KCONFIG

    KCONFIG --> GENCONFIG[Generate nexus_config.h]
    GENCONFIG --> CMAKE[Run CMake Configuration]
    CMAKE --> PLATFORM{Select Platform}

    PLATFORM -->|Native| NATIVE[Native Platform Build]
    PLATFORM -->|STM32F4| STM32F4[STM32F4 Platform Build]
    PLATFORM -->|STM32H7| STM32H7[STM32H7 Platform Build]
    PLATFORM -->|GD32| GD32[GD32 Platform Build]

    NATIVE --> COMPILE[Compile Source Files]
    STM32F4 --> COMPILE
    STM32H7 --> COMPILE
    GD32 --> COMPILE

    COMPILE --> LINK[Link Libraries]
    LINK --> BINARY[Generate Binary]
    BINARY --> TEST{Run Tests?}

    TEST -->|Yes| RUNTESTS[Execute Unit Tests]
    TEST -->|No| DONE([Build Complete])
    RUNTESTS --> COVERAGE{Coverage Enabled?}

    COVERAGE -->|Yes| GENCOV[Generate Coverage Report]
    COVERAGE -->|No| DONE
    GENCOV --> DONE

    style START fill:#e1f5ff
    style KCONFIG fill:#fff4e1
    style GENCONFIG fill:#fff4e1
    style CMAKE fill:#ffe1f5
    style COMPILE fill:#e1ffe1
    style LINK fill:#e1ffe1
    style BINARY fill:#e1ffe1
    style DONE fill:#e1f5ff
    

快速开始

构建 Nexus 最快的方式是使用 CMake Presets：

# List available presets
cmake --list-presets

# Configure with a preset
cmake --preset windows-msvc-debug

# Build
cmake --build --preset windows-msvc-debug

# Test
ctest --preset windows-msvc-debug

或使用 Python 构建脚本实现更简单的工作流：

# Auto-detect platform and build
python scripts/building/build.py

# Build with specific preset and run tests
python scripts/building/build.py -p windows-msvc-debug -t

# Parallel build with 8 jobs
python scripts/building/build.py -p linux-gcc-release -j8

CMake Presets

什么是 CMake Presets？

CMake Presets（在 CMake 3.19 中引入）提供了一种标准方式来指定常见的构建配置。它们消除了记住复杂 CMake 命令行参数的需要，并确保不同环境间构建的一致性。

优势：

• 📋 一致的配置：所有开发者使用相同的设置

• 🚀 快速设置：一条命令即可配置、构建和测试

• 🔄 轻松切换：即时切换配置

• 🤝 团队协作：通过版本控制共享配置

• 🤖 CI/CD 集成：完美适配自动化构建

可用的 Presets

列出所有可用的 presets：

# List configure presets
cmake --list-presets

# List build presets
cmake --build --list-presets

# List test presets
ctest --list-presets

Windows Presets

Preset Name	Compiler	Generator	Description
windows-msvc-debug	MSVC	VS 2022	Debug build with Visual Studio
windows-msvc-release	MSVC	VS 2022	Release build with Visual Studio
windows-gcc-debug	GCC	Ninja	Debug build with MinGW GCC
windows-gcc-release	GCC	Ninja	Release build with MinGW GCC
windows-clang-debug	Clang	Ninja	Debug build with Clang
windows-clang-release	Clang	Ninja	Release build with Clang

Linux Presets

Preset Name	Compiler	Generator	Description
linux-gcc-debug	GCC	Ninja	Debug build with GCC
linux-gcc-release	GCC	Ninja	Release build with GCC
linux-gcc-coverage	GCC	Ninja	Debug build with coverage
linux-clang-debug	Clang	Ninja	Debug build with Clang
linux-clang-release	Clang	Ninja	Release build with Clang

macOS Presets

Preset Name	Compiler	Generator	Description
macos-clang-debug	Clang	Ninja	Debug build with AppleClang
macos-clang-release	Clang	Ninja	Release build with AppleClang

交叉编译 Presets

Preset Name	Target	Description
cross-arm-debug	STM32F4	ARM Cortex-M4 Debug build
cross-arm-release	STM32F4	ARM Cortex-M4 Release build

使用 Presets

基本工作流

# 1. Configure with preset
cmake --preset windows-msvc-debug

# 2. Build with preset
cmake --build --preset windows-msvc-debug

# 3. Test with preset
ctest --preset windows-msvc-debug

一体化命令

# Configure, build, and test in one go
cmake --preset linux-gcc-debug && \
cmake --build --preset linux-gcc-debug && \
ctest --preset linux-gcc-debug

并行构建

# Build with 8 parallel jobs
cmake --build --preset windows-msvc-debug -j8

# Auto-detect CPU count
cmake --build --preset linux-gcc-release -j$(nproc)

Preset 配置

Presets 在项目根目录的 CMakePresets.json 中定义：

{
    "version": 6,
    "cmakeMinimumRequired": {
        "major": 3,
        "minor": 21,
        "patch": 0
    },
    "configurePresets": [
        {
            "name": "windows-msvc-debug",
            "displayName": "Windows MSVC Debug",
            "description": "Windows build with MSVC compiler (Debug)",
            "generator": "Visual Studio 17 2022",
            "binaryDir": "${sourceDir}/build/${presetName}",
            "cacheVariables": {
                "CMAKE_BUILD_TYPE": "Debug",
                "NEXUS_BUILD_TESTS": "ON",
                "NEXUS_PLATFORM": "native"
            }
        }
    ],
    "buildPresets": [
        {
            "name": "windows-msvc-debug",
            "configurePreset": "windows-msvc-debug",
            "configuration": "Debug"
        }
    ],
    "testPresets": [
        {
            "name": "windows-msvc-debug",
            "configurePreset": "windows-msvc-debug",
            "configuration": "Debug",
            "output": {
                "outputOnFailure": true
            }
        }
    ]
}

构建脚本

scripts/building/build.py 脚本提供了 CMake presets 的便捷包装器，并附带额外功能。

特性

• 🎯 自动检测：自动为您的平台选择合适的 preset

• 📋 Preset 列表：查看所有可用的 presets

• 🧹 清理构建：构建前清理选项

• 🧪 集成测试：构建后运行测试

• ⚡ 并行构建：自动 CPU 检测以获得最佳性能

用法

# Show help
python scripts/building/build.py --help

# List available presets
python scripts/building/build.py --list

# Build with auto-detected preset
python scripts/building/build.py

# Build with specific preset
python scripts/building/build.py --preset windows-msvc-debug

# Build and test
python scripts/building/build.py -p linux-gcc-debug --test

# Clean build with 8 jobs
python scripts/building/build.py -p windows-msvc-release --clean -j8

命令行选项

Option	Description
-p, --preset <name>	CMake preset name (auto-detected if not specified)
-l, --list	List all available CMake presets
-c, --clean	Clean build directory before building
-j, --jobs <n>	Number of parallel jobs (default: auto-detect)
-t, --test	Run tests after building
-h, --help	Show help message

示例

# Quick build for current platform
python scripts/building/build.py

# Development workflow (build + test)
python scripts/building/build.py -p windows-msvc-debug -t

# Release build with maximum parallelism
python scripts/building/build.py -p linux-gcc-release -j$(nproc)

# Clean release build
python scripts/building/build.py -p macos-clang-release -c

# CI/CD workflow
python scripts/building/build.py -p linux-gcc-coverage -t

测试

Nexus 项目包含全面的测试，有 1600+ 个单元测试覆盖所有组件。

运行测试

使用 CTest Presets（推荐）

运行测试最优雅的方式：

# Run all tests with preset
ctest --preset windows-msvc-debug

# Run tests in parallel (8 jobs)
ctest --preset linux-gcc-debug -j8

# Show output only on failure
ctest --preset windows-msvc-debug --output-on-failure

# Quiet mode (summary only)
ctest --preset linux-gcc-release --quiet

# Run specific test
ctest --preset windows-msvc-debug -R "GPIOTest.*"

使用构建脚本

# Build and test in one command
python scripts/building/build.py -p windows-msvc-debug --test

# Or use short form
python scripts/building/build.py -p linux-gcc-debug -t

手动 CTest

# Run all tests
cd build/windows-msvc-debug
ctest -C Debug

# Run with verbose output
ctest -C Debug --verbose

# Run specific test suite
ctest -C Debug -R "OsalTest"

测试输出

CTest 提供清晰、格式化的输出：

Test project D:/code/nexus/nexus/build/windows-msvc-debug
      Start   1: CRCTest.CRC32_EmptyData
 1/1631 Test   #1: CRCTest.CRC32_EmptyData ..................   Passed    0.01 sec
      Start   2: CRCTest.CRC32_SingleByte
 2/1631 Test   #2: CRCTest.CRC32_SingleByte .................   Passed    0.01 sec
      Start   3: CRCTest.CRC32_KnownValue
 3/1631 Test   #3: CRCTest.CRC32_KnownValue .................   Passed    0.01 sec

...

100% tests passed, 0 tests failed out of 1631

Total Test time (real) = 45.23 sec

测试类别

测试套件包括：

**单元测试**（1400+ 个测试）

独立测试各个组件：

• HAL 驱动（GPIO、UART、SPI、I2C、Timer、ADC、DAC 等）

• OSAL 原语（任务、互斥锁、信号量、队列、事件）

• 框架组件（日志、Shell、配置、初始化）

**基于属性的测试**（200+ 个测试）

使用随机输入验证系统属性：

• 生命周期一致性

• 状态机正确性

• 并发安全性

• 资源管理

**集成测试**（30+ 个测试）

测试组件交互：

• HAL + OSAL 集成

• 框架集成

• 平台特定功能

测试组织

测试按组件组织：

tests/
├── hal/                    # HAL tests
│   ├── gpio_tests.cpp
│   ├── uart_tests.cpp
│   └── ...
├── osal/                   # OSAL tests
│   ├── task_tests.cpp
│   ├── mutex_tests.cpp
│   └── ...
├── framework/              # Framework tests
│   ├── log_tests.cpp
│   ├── shell_tests.cpp
│   └── ...
└── integration/            # Integration tests
    └── integration_tests.cpp

过滤测试

运行特定的测试子集：

# Run only GPIO tests
ctest --preset windows-msvc-debug -R "GPIO"

# Run all HAL tests
ctest --preset linux-gcc-debug -R "hal_"

# Exclude property tests
ctest --preset windows-msvc-debug -E "Property"

# Run tests matching pattern
ctest --preset linux-gcc-debug -R "Mutex.*Lock"

测试超时

配置测试超时：

# Set 5-minute timeout
ctest --preset windows-msvc-debug --timeout 300

# No timeout
ctest --preset linux-gcc-debug --timeout 0

测试详细程度

控制输出详细程度：

# Minimal output
ctest --preset windows-msvc-debug --quiet

# Normal output (default)
ctest --preset linux-gcc-debug

# Verbose output
ctest --preset windows-msvc-debug --verbose

# Extra verbose (debug)
ctest --preset linux-gcc-debug --extra-verbose

测试结果

导出测试结果：

# JUnit XML format
ctest --preset windows-msvc-debug --output-junit results.xml

# JSON format
ctest --preset linux-gcc-debug --output-json results.json

调试失败的测试

当测试失败时：

# Show output only for failed tests
ctest --preset windows-msvc-debug --output-on-failure

# Rerun only failed tests
ctest --preset windows-msvc-debug --rerun-failed

# Stop on first failure
ctest --preset linux-gcc-debug --stop-on-failure

CMake 结构

项目组织

项目遵循分层的 CMake 结构：

nexus/
├── CMakeLists.txt              # Root CMake configuration
├── CMakePresets.json           # CMake presets definition
├── cmake/
│   ├── modules/                # CMake helper modules
│   │   ├── NexusPlatform.cmake # Platform detection & config
│   │   ├── NexusHelpers.cmake  # Utility functions
│   │   └── FreeRTOS.cmake      # FreeRTOS integration
│   ├── toolchains/             # Toolchain files
│   │   └── arm-none-eabi.cmake # ARM cross-compilation
│   ├── linker/                 # Linker scripts
│   │   ├── nx_sections.ld      # GCC linker script
│   │   └── nx_sections.sct     # ARM linker script
│   ├── CTestConfig.cmake       # CTest configuration
│   └── CTestScript.cmake       # CTest automation script
├── hal/CMakeLists.txt          # HAL library
├── osal/CMakeLists.txt         # OSAL library
├── framework/CMakeLists.txt    # Framework libraries
├── platforms/CMakeLists.txt    # Platform-specific code
├── applications/CMakeLists.txt # Example applications
└── tests/CMakeLists.txt        # Unit tests

根 CMakeLists.txt

根 CMakeLists.txt 文件：

1. 定义项目元数据（名称、版本、语言）

2. 防止源内构建

3. 声明构建选项

4. 包含 NexusPlatform 模块用于平台检测

5. 根据检测到的编译器配置编译器标志

6. 集成 Kconfig 配置系统

7. 包含子目录

关键部分：

# Project definition
cmake_minimum_required(VERSION 3.21)
project(nexus
    VERSION 0.1.0
    DESCRIPTION "Nexus Embedded Software Development Platform"
    LANGUAGES C CXX ASM
)

# Include platform detection module
include(cmake/modules/NexusPlatform.cmake)

# Options
option(NEXUS_BUILD_TESTS "Build unit tests" ON)
option(NEXUS_BUILD_EXAMPLES "Build example applications" ON)
option(NEXUS_BUILD_DOCS "Build documentation" OFF)
option(NEXUS_ENABLE_COVERAGE "Enable code coverage" OFF)

# Platform selection
set(NEXUS_PLATFORM "native" CACHE STRING "Target platform")

# OSAL backend selection
set(NEXUS_OSAL_BACKEND "baremetal" CACHE STRING "OSAL backend")

# Configure compiler flags
nexus_configure_compiler_flags()

# Add subdirectories
add_subdirectory(hal)
add_subdirectory(osal)
add_subdirectory(framework)
add_subdirectory(platforms)
add_subdirectory(applications)
if(NEXUS_BUILD_TESTS)
    add_subdirectory(tests)
endif()

NexusPlatform 模块

cmake/modules/NexusPlatform.cmake 模块提供：

平台检测

自动检测 Windows、Linux 和 macOS

编译器检测

识别 MSVC、GCC、Clang 和 AppleClang

生成器检测

识别 Visual Studio、Ninja 和 Make

编译器配置

为每个编译器应用适当的标志：

• MSVC：/W4 /WX /permissive- /MP

• GCC/Clang：-Wall -Wextra -Wpedantic -Werror

输出目录管理

一致地组织构建产物：

• 库：${CMAKE_BINARY_DIR}/lib

• 可执行文件：${CMAKE_BINARY_DIR}/bin

• 归档：${CMAKE_BINARY_DIR}/lib

Usage:

# Include the module
include(cmake/modules/NexusPlatform.cmake)

# Platform detection is automatic
# Access detected values:
message("Platform: ${NEXUS_DETECTED_PLATFORM}")
message("Compiler: ${NEXUS_DETECTED_COMPILER}")
message("Generator: ${NEXUS_DETECTED_GENERATOR}")

# Configure compiler flags
nexus_configure_compiler_flags()

Build Options

The following CMake options control the build configuration:

Core Build Options

Option	Type	Default	Description
NEXUS_BUILD_TESTS	BOOL	ON	Build unit tests (requires GoogleTest)
NEXUS_BUILD_EXAMPLES	BOOL	ON	Build example applications
NEXUS_BUILD_DOCS	BOOL	OFF	Build documentation (requires Doxygen/Sphinx)
NEXUS_ENABLE_COVERAGE	BOOL	OFF	Enable code coverage instrumentation

Platform Selection

The NEXUS_PLATFORM option selects the target platform. Type: STRING, Default: native

Platform	Description
native	Native platform for host testing (Windows/Linux/macOS)
stm32f4	STM32F4 series microcontrollers (Cortex-M4)
stm32h7	STM32H7 series microcontrollers (Cortex-M7)
ESP32	ESP32 series microcontrollers (Xtensa LX6)
nrf52	nRF52 series microcontrollers (Cortex-M4)

Set platform using:

CMake -DNEXUS_PLATFORM=stm32f4 ..

OSAL Backend Selection

The NEXUS_OSAL_BACKEND option selects the RTOS backend. Type: STRING, Default: baremetal

Backend	Description
baremetal	Bare-metal (no RTOS)
FreeRTOS	FreeRTOS integration
rtthread	RT-Thread integration
zephyr	Zephyr RTOS integration

Set OSAL backend using:

CMake -DNEXUS_OSAL_BACKEND=FreeRTOS ..

Kconfig Options

Option	Description
NEXUS_KCONFIG_FILE	Path to root Kconfig file (default: Kconfig)
NEXUS_CONFIG_FILE	Path to configuration file (default: .config)
NEXUS_CONFIG_HEADER	Path to generated header (default: nexus_config.h)

Build Types

CMake supports standard build types:

Build Type	Description
Debug	Debug build with symbols, no optimization (-Og -g3)
Release	Release build with optimization (-O2)
RelWithDebInfo	Release with debug info (-O2 -g)
MinSizeRel	Minimum size release (-Os)

Set build type using:

CMake -DCMAKE_BUILD_TYPE=Release ..

构建项目

使用 CMake Presets（推荐）

使用 CMake Presets 的现代化推荐方法：

配置

# List available presets
cmake --list-presets

# Configure with a preset
cmake --preset <preset-name>

Examples:

# Windows with MSVC
cmake --preset windows-msvc-debug

# Linux with GCC
cmake --preset linux-gcc-debug

# macOS with Clang
cmake --preset macos-clang-debug

# Cross-compilation for ARM
cmake --preset cross-arm-debug

构建

# Build with preset
cmake --build --preset <preset-name>

# Build with parallel jobs
cmake --build --preset <preset-name> -j8

Examples:

# Debug build
cmake --build --preset windows-msvc-debug

# Release build with 8 jobs
cmake --build --preset linux-gcc-release -j8

# Cross-compilation
cmake --build --preset cross-arm-release

测试

# Run tests with preset
ctest --preset <preset-name>

# Run tests in parallel
ctest --preset <preset-name> -j8

# Show output on failure
ctest --preset <preset-name> --output-on-failure

Examples:

# Run all tests
ctest --preset windows-msvc-debug

# Parallel testing
ctest --preset linux-gcc-debug -j8 --output-on-failure

# Quiet mode (summary only)
ctest --preset macos-clang-release --quiet

完整工作流

# Configure, build, and test
cmake --preset windows-msvc-debug && \
cmake --build --preset windows-msvc-debug -j8 && \
ctest --preset windows-msvc-debug -j8 --output-on-failure

使用构建脚本

The Python build script provides a simpler interface:

# Auto-detect platform and build
python scripts/building/build.py

# Build with specific preset
python scripts/building/build.py --preset windows-msvc-debug

# Build and test
python scripts/building/build.py -p linux-gcc-debug --test

# Clean build with 8 jobs
python scripts/building/build.py -p windows-msvc-release --clean -j8

# List available presets
python scripts/building/build.py --list

手动 CMake（传统方式）

传统 CMake 工作流（不推荐用于新项目）：

# Create build directory
mkdir build
cd build

# Configure
cmake -DCMAKE_BUILD_TYPE=Debug \
      -DNEXUS_BUILD_TESTS=ON \
      -DNEXUS_PLATFORM=native \
      ..

# Build
cmake --build . -j8

# Test
ctest --output-on-failure

备注

强烈推荐使用 CMake Presets 而不是手动配置，因为它确保构建一致性并简化工作流。

平台特定构建

Windows

MSVC（Visual Studio 2022）

# Debug
cmake --preset windows-msvc-debug
cmake --build --preset windows-msvc-debug

# Release
cmake --preset windows-msvc-release
cmake --build --preset windows-msvc-release

MinGW GCC

# Ensure MinGW is in PATH
cmake --preset windows-gcc-debug
cmake --build --preset windows-gcc-debug -j8

Clang

# Ensure Clang is in PATH
cmake --preset windows-clang-debug
cmake --build --preset windows-clang-debug -j8

Linux

GCC

# Debug
cmake --preset linux-gcc-debug
cmake --build --preset linux-gcc-debug -j$(nproc)

# Release
cmake --preset linux-gcc-release
cmake --build --preset linux-gcc-release -j$(nproc)

# Coverage
cmake --preset linux-gcc-coverage
cmake --build --preset linux-gcc-coverage -j$(nproc)

Clang

# Debug
cmake --preset linux-clang-debug
cmake --build --preset linux-clang-debug -j$(nproc)

# Release
cmake --preset linux-clang-release
cmake --build --preset linux-clang-release -j$(nproc)

macOS

# Debug
cmake --preset macos-clang-debug
cmake --build --preset macos-clang-debug -j$(sysctl -n hw.ncpu)

# Release
cmake --preset macos-clang-release
cmake --build --preset macos-clang-release -j$(sysctl -n hw.ncpu)

交叉编译

ARM Cortex-M 目标

前置条件

安装 ARM GNU 工具链：

• Windows：从 ARM Developer 下载

• Linux：sudo apt-get install gcc-arm-none-eabi

• macOS：brew install gcc-arm-embedded

验证安装：

arm-none-eabi-gcc --version

预期输出：

arm-none-eabi-gcc (GNU Arm Embedded Toolchain 10.3-2021.10) 10.3.1 20210824
Copyright (C) 2020 Free Software Foundation, Inc.

STM32F4 构建

使用 presets（推荐）：

# Configure
cmake --preset cross-arm-debug

# Build
cmake --build --preset cross-arm-debug

# Or use build script
python scripts/building/build.py --preset cross-arm-debug

使用手动配置：

mkdir build-stm32f4
cd build-stm32f4

cmake -DNEXUS_PLATFORM=stm32f4 \
      -DCMAKE_BUILD_TYPE=Release \
      -DNEXUS_BUILD_TESTS=OFF \
      -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/arm-none-eabi.cmake \
      ..

cmake --build . -j8

STM32H7 构建

mkdir build-stm32h7
cd build-stm32h7

cmake -DNEXUS_PLATFORM=stm32h7 \
      -DCMAKE_BUILD_TYPE=Release \
      -DNEXUS_BUILD_TESTS=OFF \
      -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/arm-none-eabi.cmake \
      ..

cmake --build . -j8

构建输出

对于嵌入式目标，构建生成：

build/cross-arm-debug/
├── bin/
│   ├── blinky.elf          # Executable with debug symbols
│   ├── blinky.bin          # Raw binary for flashing
│   ├── blinky.hex          # Intel HEX format
│   └── blinky.map          # Memory map file
└── lib/
    ├── libnexus_hal.a
    ├── libnexus_osal.a
    └── ...

链接期间显示内存使用情况：

Memory region         Used Size  Region Size  %age Used
           FLASH:       45632 B       512 KB      8.70%
             RAM:       12288 B       128 KB      9.38%

工具链配置

ARM 工具链文件（cmake/toolchains/arm-none-eabi.cmake）配置：

编译器工具

set(CMAKE_C_COMPILER arm-none-eabi-gcc)
set(CMAKE_CXX_COMPILER arm-none-eabi-g++)
set(CMAKE_ASM_COMPILER arm-none-eabi-gcc)
set(CMAKE_AR arm-none-eabi-ar)
set(CMAKE_OBJCOPY arm-none-eabi-objcopy)
set(CMAKE_OBJDUMP arm-none-eabi-objdump)
set(CMAKE_SIZE arm-none-eabi-size)

Cortex-M4 的编译器标志

set(CMAKE_C_FLAGS_INIT
    "-mcpu=cortex-m4 \
     -mthumb \
     -mfloat-abi=hard \
     -mfpu=fpv4-sp-d16 \
     -ffunction-sections \
     -fdata-sections"
)

链接器标志

set(CMAKE_EXE_LINKER_FLAGS_INIT
    "-Wl,--gc-sections \
     -Wl,--print-memory-usage \
     -specs=nano.specs \
     -specs=nosys.specs"
)

自定义工具链路径

如果工具链不在 PATH 中：

cmake --preset cross-arm-debug \
      -DTOOLCHAIN_PREFIX=/path/to/gcc-arm-none-eabi

或设置环境变量：

export ARM_TOOLCHAIN_PATH=/path/to/gcc-arm-none-eabi
cmake --preset cross-arm-debug

烧录

构建后，将二进制文件烧录到设备：

使用 OpenOCD

openocd -f interface/stlink.cfg \
        -f target/stm32f4x.cfg \
        -c "program build/cross-arm-debug/bin/blinky.elf verify reset exit"

使用 ST-Link 工具

st-flash write build/cross-arm-debug/bin/blinky.bin 0x8000000

使用 J-Link

JLinkExe -device STM32F407VG -if SWD -speed 4000 \
         -CommanderScript flash.jlink

其中 flash.jlink 包含：

loadfile build/cross-arm-debug/bin/blinky.hex
r
g
exit

Configuration System

Kconfig Integration

The build system integrates with Kconfig for configuration management:

1. Configuration Generation: During CMake configuration, the generate_config.py script generates nexus_config.h from .config

2. Dependency Tracking: CMake tracks all Kconfig files and reconfigures when they change

3. Default Configuration: If no .config exists, a default configuration is generated

Configuration Workflow:

# 1. Configure with menuconfig (if available)
python scripts/Kconfig/generate_config.py --menuconfig

# 2. Or use a defconfig
cp platforms/STM32/defconfig_stm32f4 .config

# 3. Generate header
python scripts/Kconfig/generate_config.py --config .config --output nexus_config.h

# 4. Build
CMake --build build

Generated Header

The nexus_config.h header contains:

/* Generated configuration header */
#ifndef NEXUS_CONFIG_H
#define NEXUS_CONFIG_H

/* Platform configuration */
#define CONFIG_PLATFORM_STM32F4 1
#define CONFIG_CHIP_STM32F407 1

/* Peripheral configuration */
#define CONFIG_HAL_GPIO 1
#define CONFIG_HAL_UART 1
#define CONFIG_HAL_UART_COUNT 3

/* OSAL configuration */
#define CONFIG_OSAL_FREERTOS 1
#define CONFIG_FREERTOS_HEAP_SIZE 32768

#endif /* NEXUS_CONFIG_H */

构建目录结构

After building, the directory structure:

build/
├── CMakeCache.txt              # CMake cache
├── CMakeFiles/                 # CMake internal files
├── compile_commands.json       # Compilation database
├── hal/
│   └── libnexus_hal.a          # HAL library
├── osal/
│   └── libnexus_osal.a         # OSAL library
├── framework/
│   ├── config/
│   │   └── libnexus_config.a   # Config library
│   ├── log/
│   │   └── libnexus_log.a      # Log library
│   └── shell/
│       └── libnexus_shell.a    # Shell library
├── platforms/
│   └── native/
│       └── libnexus_platform.a # Platform library
├── applications/
│   ├── blinky/
│   │   └── blinky.exe          # Blinky application
│   └── shell_demo/
│       └── shell_demo.exe      # Shell demo
└── tests/
    └── nexus_tests.exe         # Unit tests

输出产物

For embedded targets:

• .elf - 带调试符号的可执行文件

• .bin - 用于烧录的原始二进制文件

• .hex - Intel HEX 格式

• .map - 内存映射文件

高级构建功能

并行构建

通过并行编译最大化构建速度：

# Auto-detect CPU count (Linux/macOS)
cmake --build --preset linux-gcc-release -j$(nproc)

# Auto-detect CPU count (macOS)
cmake --build --preset macos-clang-release -j$(sysctl -n hw.ncpu)

# Specify job count
cmake --build --preset windows-msvc-debug -j8

# Use all available cores
cmake --build --preset linux-gcc-debug -j

构建脚本自动检测 CPU 数量：

# Auto-parallel build
python scripts/building/build.py -p linux-gcc-release

# Override with specific job count
python scripts/building/build.py -p windows-msvc-debug -j4

详细构建

显示完整的编译器命令用于调试：

# CMake verbose mode
cmake --build --preset windows-msvc-debug --verbose

# Or set environment variable
export VERBOSE=1
cmake --build --preset linux-gcc-debug

# For Ninja generator
cmake --build --preset linux-gcc-debug -- -v

# For Make generator
cmake --build --preset linux-gcc-debug -- VERBOSE=1

清理构建

删除构建产物：

# Clean specific preset build
cmake --build --preset windows-msvc-debug --target clean

# Or delete entire build directory
rm -rf build/windows-msvc-debug

# Clean all build directories
rm -rf build/

# Using build script with clean flag
python scripts/building/build.py -p linux-gcc-debug --clean

增量构建

CMake 自动执行增量构建：

# First build (full)
cmake --build --preset windows-msvc-debug

# Modify source file
# ...

# Second build (incremental - only changed files)
cmake --build --preset windows-msvc-debug

强制重新构建：

# Rebuild everything
cmake --build --preset windows-msvc-debug --clean-first

安装

将构建产物安装到特定位置：

# Default install location (/usr/local on Unix)
cmake --build --preset linux-gcc-release --target install

# Custom install prefix
cmake --preset linux-gcc-release \
      -DCMAKE_INSTALL_PREFIX=/opt/nexus
cmake --build --preset linux-gcc-release --target install

安装布局：

/opt/nexus/
├── include/
│   ├── nexus/
│   │   ├── hal/
│   │   ├── osal/
│   │   └── framework/
│   └── nexus_config.h
├── lib/
│   ├── libnexus_hal.a
│   ├── libnexus_osal.a
│   └── ...
└── share/
    └── nexus/
        └── cmake/

编译数据库

生成 compile_commands.json 用于 IDE 集成：

# Automatically generated with presets
cmake --preset windows-msvc-debug

# Or manually enable
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..

编译数据库被以下工具使用：

• clangd：VS Code、Vim、Emacs 的语言服务器

• clang-tidy：静态分析工具

• cppcheck：静态分析工具

• IDE 工具：代码导航和补全

自定义构建目标

构建系统提供多个自定义目标：

# Build documentation
cmake --build --preset linux-gcc-debug --target docs

# Run clang-format
cmake --build --preset linux-gcc-debug --target format

# Run clang-tidy
cmake --build --preset linux-gcc-debug --target tidy

# Generate coverage report
cmake --build --preset linux-gcc-coverage --target coverage

构建目录结构

每个 preset 创建自己的构建目录：

build/
├── windows-msvc-debug/         # MSVC Debug build
│   ├── CMakeCache.txt
│   ├── compile_commands.json
│   ├── bin/                    # Executables
│   │   ├── blinky.exe
│   │   └── shell_demo.exe
│   ├── lib/                    # Libraries
│   │   ├── nexus_hal.lib
│   │   └── nexus_osal.lib
│   └── tests/                  # Test executables
│       └── nexus_tests.exe
├── linux-gcc-release/          # GCC Release build
│   ├── bin/
│   ├── lib/
│   └── tests/
└── cross-arm-debug/            # ARM Debug build
    ├── bin/
    │   ├── blinky.elf
    │   ├── blinky.bin
    │   ├── blinky.hex
    │   └── blinky.map
    └── lib/

输出产物

原生平台

• ``.exe``（Windows）或无扩展名（Unix）- 可执行文件

• ``.lib``（MSVC）或 ``.a``（GCC/Clang）- 静态库

• ``.dll``（Windows）或 ``.so``（Unix）- 共享库（如果启用）

嵌入式平台

• .elf - 带调试符号的可执行文件

• .bin - 用于烧录的原始二进制文件

• .hex - Intel HEX 格式

• .map - 内存映射文件

• .lst - 汇编列表（如果启用）

构建性能提示

优化构建速度

1. 使用 Ninja 生成器：比 Make 或 Visual Studio 更快

   # Ninja is used by default in presets
   cmake --preset linux-gcc-debug
   

2. 启用并行构建：使用所有 CPU 核心

   cmake --build --preset linux-gcc-debug -j$(nproc)
   

3. 使用 ccache：缓存编译结果

   # Install ccache
   sudo apt-get install ccache  # Linux
   brew install ccache          # macOS
   
   # Configure CMake to use ccache
   cmake --preset linux-gcc-debug \
         -DCMAKE_C_COMPILER_LAUNCHER=ccache \
         -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
   

4. 增量构建：仅重新构建更改的文件

   # CMake automatically does incremental builds
   cmake --build --preset linux-gcc-debug
   

5. 预编译头文件：减少编译时间（未来功能）

减小构建大小

1. 使用 MinSizeRel 构建类型：

   cmake -DCMAKE_BUILD_TYPE=MinSizeRel ..
   

2. 启用 LTO（链接时优化）：

   cmake -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON ..
   

3. 剥离调试符号：

   arm-none-eabi-strip blinky.elf -o blinky_stripped.elf
   

代码覆盖率

Nexus 构建系统包含全面的代码覆盖率支持，用于质量保证。

使用覆盖率 Preset（推荐）

生成覆盖率报告最简单的方式：

# Configure with coverage preset
cmake --preset linux-gcc-coverage

# Build
cmake --build --preset linux-gcc-coverage -j8

# Run tests
ctest --preset linux-gcc-coverage

# Generate coverage report
bash scripts/coverage/run_coverage_linux.sh

Or use the build script:

# Build and test with coverage
python scripts/building/build.py -p linux-gcc-coverage -t

手动覆盖率设置

Linux/macOS 使用 GCC

# 1. Configure with coverage flags
cmake -DNEXUS_ENABLE_COVERAGE=ON \
      -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_C_FLAGS="--coverage" \
      -DCMAKE_CXX_FLAGS="--coverage" \
      ..

# 2. Build
cmake --build . -j8

# 3. Run tests
ctest --output-on-failure

# 4. Generate coverage data
lcov --capture --directory . --output-file coverage.info

# 5. Filter out system and test files
lcov --remove coverage.info \
     '/usr/*' \
     '*/ext/*' \
     '*/tests/*' \
     '*/googletest/*' \
     --output-file coverage_filtered.info

# 6. Generate HTML report
genhtml coverage_filtered.info \
        --output-directory coverage_html \
        --title "Nexus Coverage Report" \
        --legend

# 7. View report
xdg-open coverage_html/index.html  # Linux
open coverage_html/index.html      # macOS

Windows 使用 MSVC

使用 OpenCppCoverage：

# Install OpenCppCoverage
choco install opencppcoverage

# Run tests with coverage
OpenCppCoverage.exe `
    --sources nexus\* `
    --excluded_sources nexus\ext\* `
    --excluded_sources nexus\tests\* `
    --export_type html:coverage_html `
    -- ctest --preset windows-msvc-debug -C Debug

# View report
start coverage_html\index.html

覆盖率脚本

项目包含覆盖率辅助脚本：

Linux

# Run coverage and generate report
bash scripts/coverage/run_coverage_linux.sh

# Clean coverage data
bash scripts/coverage/clean_coverage.sh

Windows

# Run coverage with OpenCppCoverage
.\scripts\coverage\run_coverage_windows.ps1

覆盖率指标

覆盖率报告包括：

• 行覆盖率：已执行行的百分比

• 函数覆盖率：已调用函数的百分比

• 分支覆盖率：已执行分支的百分比

目标覆盖率：

Component	Target	Notes
HAL Drivers	> 90%	Core functionality must be well-tested
OSAL	> 85%	Platform-specific code may vary
Framework	> 80%	Log, Shell, Config components
Overall	> 80%	Project-wide coverage target

查看覆盖率结果

HTML 报告提供：

• 摘要页面：总体覆盖率统计

• 目录视图：按目录的覆盖率

• 文件视图：逐行覆盖率

• 函数列表：每个函数的覆盖率

覆盖率摘要示例：

Overall coverage rate:
  lines......: 87.3% (12456 of 14267 lines)
  functions..: 91.2% (1234 of 1353 functions)
  branches...: 78.5% (3456 of 4401 branches)

CI/CD 集成

GitHub Actions 中的覆盖率：

- name: Run tests with coverage
  run: |
    cmake --preset linux-gcc-coverage
    cmake --build --preset linux-gcc-coverage
    ctest --preset linux-gcc-coverage

- name: Generate coverage report
  run: |
    lcov --capture --directory . --output-file coverage.info
    lcov --remove coverage.info '/usr/*' '*/ext/*' '*/tests/*' \
         --output-file coverage.info

- name: Upload to Codecov
  uses: codecov/codecov-action@v3
  with:
    files: ./coverage.info
    fail_ci_if_error: true

持续集成

GitHub Actions 工作流

项目在 .github/workflows/build-and-test.yml 中包含全面的 CI/CD 工作流：

特性：

• ✅ 多平台测试（Windows、Linux、macOS）

• ✅ 多编译器支持（MSVC、GCC、Clang）

• ✅ 并行测试执行

• ✅ 代码覆盖率报告

• ✅ 产物上传

• ✅ ARM 交叉编译

工作流结构

name: Build and Test

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  build-and-test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        preset:
          - linux-gcc-debug
          - linux-gcc-release
          - windows-msvc-debug
          - windows-msvc-release
          - macos-clang-debug
          - macos-clang-release
      exclude:
        # Exclude invalid combinations
        - os: ubuntu-latest
          preset: windows-msvc-debug
        # ... more exclusions

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Configure
        run: cmake --preset ${{ matrix.preset }}

      - name: Build
        run: cmake --build --preset ${{ matrix.preset }} -j4

      - name: Test
        run: ctest --preset ${{ matrix.preset }} -j4 --output-on-failure

      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: build-${{ matrix.os }}-${{ matrix.preset }}
          path: build/${{ matrix.preset }}/bin/

覆盖率任务

独立的覆盖率报告任务：

coverage:
  runs-on: ubuntu-latest

  steps:
    - uses: actions/checkout@v3

    - name: Install dependencies
      run: |
        sudo apt-get update
        sudo apt-get install -y lcov

    - name: Configure with coverage
      run: cmake --preset linux-gcc-coverage

    - name: Build
      run: cmake --build --preset linux-gcc-coverage -j4

    - name: Test
      run: ctest --preset linux-gcc-coverage -j4

    - name: Generate coverage report
      run: |
        lcov --capture --directory . --output-file coverage.info
        lcov --remove coverage.info '/usr/*' '*/ext/*' '*/tests/*' \
             --output-file coverage.info

    - name: Upload to Codecov
      uses: codecov/codecov-action@v3
      with:
        files: ./coverage.info
        fail_ci_if_error: true

交叉编译任务

ARM 交叉编译测试：

cross-compile:
  runs-on: ubuntu-latest

  steps:
    - uses: actions/checkout@v3

    - name: Install ARM toolchain
      run: |
        sudo apt-get update
        sudo apt-get install -y gcc-arm-none-eabi

    - name: Configure
      run: cmake --preset cross-arm-release

    - name: Build
      run: cmake --build --preset cross-arm-release -j4

    - name: Check binary size
      run: |
        arm-none-eabi-size build/cross-arm-release/bin/*.elf

    - name: Upload firmware
      uses: actions/upload-artifact@v3
      with:
        name: firmware-arm
        path: |
          build/cross-arm-release/bin/*.elf
          build/cross-arm-release/bin/*.bin
          build/cross-arm-release/bin/*.hex

本地 CI 测试

使用 act 在本地测试 CI 工作流：

# Install act
# Linux: curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
# macOS: brew install act
# Windows: choco install act-cli

# Run all jobs
act

# Run specific job
act -j build-and-test

# Run with specific matrix
act -j build-and-test --matrix os:ubuntu-latest --matrix preset:linux-gcc-debug

最佳实践

开发工作流

日常开发

# 1. Pull latest changes
git pull

# 2. Build with debug preset
python scripts/building/build.py -p windows-msvc-debug -t

# 3. Make changes
# ... edit code ...

# 4. Incremental build and test
cmake --build --preset windows-msvc-debug -j8
ctest --preset windows-msvc-debug --output-on-failure

# 5. Commit changes
git add .
git commit -m "feat: add new feature"

提交 Pull Request 前

# 1. Clean build
python scripts/building/build.py -p linux-gcc-release --clean

# 2. Run all tests
ctest --preset linux-gcc-release -j8

# 3. Check coverage
python scripts/building/build.py -p linux-gcc-coverage -t
bash scripts/coverage/run_coverage_linux.sh

# 4. Format code
cmake --build --preset linux-gcc-debug --target format

# 5. Run static analysis
cmake --build --preset linux-gcc-debug --target tidy

Preset 选择指南

为您的任务选择正确的 preset：

Task	Recommended Preset
Daily development	*-debug (e.g., windows-msvc-debug)
Performance testing	*-release (e.g., linux-gcc-release)
Code coverage	linux-gcc-coverage
Production build	*-release with LTO enabled
Embedded deployment	cross-arm-release
CI/CD testing	Multiple presets for matrix testing

构建配置提示

1. 一致使用 Presets

# Good: Use presets
cmake --preset windows-msvc-debug
cmake --build --preset windows-msvc-debug
ctest --preset windows-msvc-debug

# Avoid: Manual configuration
cmake -DCMAKE_BUILD_TYPE=Debug -G "Visual Studio 17 2022" ..

2. 保持构建目录分离

# Good: Preset-based directories
build/windows-msvc-debug/
build/linux-gcc-release/

# Avoid: Single build directory
build/

3. 使用构建脚本进行自动化

# Good: Automated workflow
python scripts/building/build.py -p linux-gcc-debug -t

# Avoid: Manual steps
cmake --preset linux-gcc-debug
cmake --build --preset linux-gcc-debug
ctest --preset linux-gcc-debug

4. 启用并行构建

# Good: Use all cores
cmake --build --preset linux-gcc-release -j$(nproc)

# Avoid: Single-threaded build
cmake --build --preset linux-gcc-release

5. 定期运行测试

# Good: Test after every build
python scripts/building/build.py -p windows-msvc-debug -t

# Avoid: Build without testing
python scripts/building/build.py -p windows-msvc-debug

常见工作流

快速测试

# Build and test in one command
python scripts/building/build.py -p windows-msvc-debug -t

发布构建

# Clean release build
python scripts/building/build.py -p linux-gcc-release --clean -j8

覆盖率分析

# Build with coverage and generate report
python scripts/building/build.py -p linux-gcc-coverage -t
bash scripts/coverage/run_coverage_linux.sh
xdg-open coverage_html/index.html

交叉编译

# Build for ARM target
cmake --preset cross-arm-release
cmake --build --preset cross-arm-release -j8
arm-none-eabi-size build/cross-arm-release/bin/*.elf

多平台测试

# Test on all available platforms
for preset in windows-msvc-debug linux-gcc-debug macos-clang-debug; do
    if cmake --preset $preset 2>/dev/null; then
        cmake --build --preset $preset -j8
        ctest --preset $preset --output-on-failure
    fi
done

IDE 集成

构建系统通过 CMake Presets 与现代 IDE 无缝集成。

Visual Studio Code

设置：

1. 安装 CMake Tools 扩展

2. 打开项目文件夹

3. 从状态栏（底部）选择 preset

4. 使用 CMake Tools 界面构建和调试

**配置**（.vscode/settings.json）：

{
    "cmake.useCMakePresets": "always",
    "cmake.configureOnOpen": true,
    "cmake.buildDirectory": "${workspaceFolder}/build/${presetName}"
}

键盘快捷键：

• Ctrl+Shift+P → "CMake: Select Configure Preset"

• F7 → 构建

• Shift+F5 → 调试

Visual Studio 2022

设置：

1. 打开项目文件夹（文件 → 打开 → 文件夹）

2. Visual Studio 自动检测 CMakePresets.json

3. 从配置下拉菜单选择 preset

4. 使用标准 Visual Studio 界面构建

特性：

• 原生 CMake Presets 支持

• IntelliSense 集成

• 集成调试器

• 测试资源管理器集成

CLion

设置：

1. 打开项目

2. CLion 自动检测 CMakePresets.json

3. 从 CMake 配置文件选择 preset

4. 使用标准 CLion 界面构建和调试

特性：

• 完整的 CMake Presets 支持

• 代码导航和重构

• 集成调试器

• 测试运行器集成

See IDE Integration for detailed IDE setup guides.

故障排除

常见问题

CMake 版本过旧

CMake Error: CMake 3.21 or higher is required.

解决方案： 升级 CMake 到 3.21 或更高版本。

# Linux
sudo apt-get update
sudo apt-get install cmake

# macOS
brew upgrade cmake

# Windows
# Download from https://cmake.org/download/

找不到 Preset

CMake Error: Could not read presets from CMakePresets.json

解决方案： 确保从项目根目录运行 CMake。

# Check current directory
pwd
ls CMakePresets.json

# If not in project root, navigate there
cd /path/to/nexus

找不到编译器

CMake Error: Could not find compiler

解决方案： 安装所需的编译器并确保它在 PATH 中。

# Windows - Install Visual Studio or MinGW
# Linux
sudo apt-get install build-essential

# macOS
xcode-select --install

# Verify compiler
gcc --version
clang --version

找不到工具链（ARM）

CMake Error: Could not find ARM toolchain

解决方案： 安装 ARM GCC 工具链并添加到 PATH。

# Linux
sudo apt-get install gcc-arm-none-eabi

# macOS
brew install gcc-arm-embedded

# Windows - Download from ARM website
# Add to PATH: C:\Program Files (x86)\GNU Arm Embedded Toolchain\bin

# Verify
arm-none-eabi-gcc --version

测试发现失败

No tests were found!!!

解决方案： 确保测试已启用且平台为 native。

# Check CMake cache
cmake --preset windows-msvc-debug
grep NEXUS_BUILD_TESTS build/windows-msvc-debug/CMakeCache.txt

# Should show: NEXUS_BUILD_TESTS:BOOL=ON

# Rebuild if needed
cmake --build --preset windows-msvc-debug --clean-first

配置生成失败

Failed to generate HAL config from .config file

解决方案： 验证 .config 文件或从 defconfig 重新生成。

# Validate configuration
python scripts/kconfig/validate_kconfig.py --config .config

# Or use defconfig
cp platforms/stm32/defconfig_stm32f4 .config
python scripts/kconfig/generate_config.py

Windows 上构建失败

'cmake' is not recognized as an internal or external command

解决方案： 使用 Visual Studio 开发人员命令提示符或安装 CMake。

# Option 1: Use VS Developer Command Prompt
# Start → Visual Studio 2022 → Developer Command Prompt

# Option 2: Install CMake and add to PATH
# Download from https://cmake.org/download/

找不到 Ninja

CMake Error: Could not find Ninja

解决方案： 安装 Ninja 构建系统。

# Linux
sudo apt-get install ninja-build

# macOS
brew install ninja

# Windows
choco install ninja

# Or use Visual Studio generator instead
# Edit CMakePresets.json to use "Visual Studio 17 2022"

找不到 Python

Could NOT find Python3 (missing: Python3_EXECUTABLE)

解决方案： 安装 Python 3.7 或更高版本。

# Linux
sudo apt-get install python3 python3-pip

# macOS
brew install python3

# Windows
# Download from https://www.python.org/downloads/

# Verify
python3 --version

构建期间内存不足

c++: fatal error: Killed signal terminated program cc1plus

解决方案： 减少并行作业数或增加系统内存。

# Reduce parallel jobs
cmake --build --preset linux-gcc-debug -j2

# Or use build script with limited jobs
python scripts/building/build.py -p linux-gcc-debug -j2

调试构建问题

启用详细输出：

# Verbose CMake configuration
cmake --preset windows-msvc-debug --debug-output

# Verbose build
cmake --build --preset windows-msvc-debug --verbose

# Verbose tests
ctest --preset windows-msvc-debug --verbose

检查 CMake 缓存：

# View all cache variables
cmake -L build/windows-msvc-debug

# View with help text
cmake -LH build/windows-msvc-debug

# Edit cache with GUI
cmake-gui build/windows-msvc-debug

清理并重新构建：

# Clean build artifacts
cmake --build --preset windows-msvc-debug --target clean

# Or delete build directory
rm -rf build/windows-msvc-debug

# Reconfigure and rebuild
cmake --preset windows-msvc-debug
cmake --build --preset windows-msvc-debug

获取帮助

如果遇到此处未涵盖的问题：

1. 查看文档：查阅 Environment Setup

2. 搜索问题：访问 GitHub Issues

3. 询问社区：加入 GitHub Discussions

4. 报告错误：提交新问题，包含：

   • CMake 版本：cmake --version

   • 编译器版本：gcc --version 或 cl

   • 操作系统和版本

   • 完整错误消息

   • 重现步骤

总结

Nexus 构建系统提供：

✅ Modern CMake Presets for consistent, reproducible builds ✅ Multi-platform support (Windows, Linux, macOS, ARM) ✅ Comprehensive testing with 1600+ unit tests ✅ Code coverage analysis for quality assurance ✅ CI/CD integration with GitHub Actions ✅ IDE support for VS Code, Visual Studio, CLion ✅ Cross-compilation for embedded targets ✅ Build scripts for simplified workflows

快速参考：

# List presets
cmake --list-presets

# Build and test
python scripts/building/build.py -p <preset> -t

# Run tests
ctest --preset <preset> -j8

# Generate coverage
python scripts/building/build.py -p linux-gcc-coverage -t

另请参阅

• Kconfig 配置系统 - Kconfig 配置系统

• 测试 - 测试指南

• Environment Setup - 安装指南

• IDE Integration - IDE 集成指南

• 平台 Guides - 平台特定指南

• 贡献指南 - 贡献指南

故障排除

常见问题

CMake 版本过旧

CMake Error: CMake 3.16 or higher is required.

Solution: Upgrade CMake to version 3.16 or higher.

Toolchain not found

CMake Error: Could not find toolchain file

Solution: Install ARM toolchain and ensure it's in PATH, or specify TOOLCHAIN_PREFIX.

配置生成失败

Failed to generate HAL config from .config file

Solution: Validate .config file or regenerate from defconfig:

python scripts/Kconfig/validate_kconfig.py --config .config
# Or use defconfig
cp platforms/STM32/defconfig_stm32f4 .config

Missing dependencies

Could NOT find Python3 (missing: Python3_EXECUTABLE)

Solution: Install Python 3.7 or higher.

Windows 上构建失败

Solution: Use Visual Studio Developer Command Prompt or install MinGW-w64.

获取帮助

• Check 贡献指南 for contribution guidelines

• Visit GitHub Issues

• Join GitHub Discussions

另请参阅

• Kconfig 配置系统 - Kconfig 配置系统

• 测试 - 测试指南

• Environment Setup - 安装指南

• IDE Integration - IDE 集成指南