Raspberry Pi Pico SDK 中 CMake 4.x 与 MbedTLS 2.x 的兼容性问题解析

在嵌入式开发领域，Raspberry Pi Pico SDK 是一个广泛使用的开发工具包。近期，随着 CMake 4.0 的发布，许多开发者在使用 Pico SDK 构建项目时遇到了构建失败的问题。本文将深入分析这一问题的根源，并提供解决方案。

问题背景

当开发者尝试使用最新版本的 CMake（4.0 及以上）构建基于 Pico SDK 的项目时，会遇到以下错误信息：

CMake Error at .../lib/mbedtls/CMakeLists.txt:23 (cmake_minimum_required):
  Compatibility with CMake < 3.5 has been removed from CMake.

这个错误表明 Pico SDK 中集成的 MbedTLS 库（2.28.x 版本）与新版 CMake 存在兼容性问题。

根本原因分析

问题的核心在于版本兼容性：

1. MbedTLS 2.x 的限制：Pico SDK 当前集成的 MbedTLS 2.28.x 版本在其 CMakeLists.txt 中指定了最低 CMake 版本为 2.8.12，而 CMake 4.0 已移除了对 3.5 以下版本的支持。

2. 构建系统升级：随着各大Linux发行版（如Ubuntu 24.04）和包管理器（如Homebrew）开始默认提供CMake 4.0，这个问题变得越来越普遍。

3. 安全考虑：MbedTLS 2.28.x 系列已停止维护，不再接收安全更新。

解决方案

针对这一问题，开发者有以下几种选择：

1. 临时解决方案

对于需要立即构建项目的开发者，可以采用以下临时方案：

• 降级CMake：使用CMake 3.x版本进行构建
• 设置策略版本：在CMake命令中添加-DCMAKE_POLICY_VERSION_MINIMUM=3.5参数

2. 长期解决方案

Raspberry Pi Pico SDK开发团队已经提供了根本性解决方案：

• 升级MbedTLS：将MbedTLS升级到3.6或更高版本，这些版本已经更新了CMake最低版本要求

3. 自定义构建

对于需要保持特定配置的项目，开发者可以：

• 通过设置PICO_MBEDTLS_PATH变量指定自定义的MbedTLS路径
• 使用项目自己的MbedTLS副本

最佳实践建议

1. 版本管理：在CI/CD环境中固定CMake版本，避免自动升级带来的构建中断

2. 依赖更新：定期检查并更新项目依赖，特别是安全相关的库如MbedTLS

3. 兼容性测试：在升级构建工具链前，先在测试环境中验证项目构建

总结

随着构建工具的不断演进，类似这样的兼容性问题在嵌入式开发中并不罕见。理解问题的根源并掌握多种解决方案，能够帮助开发者更从容地应对这类挑战。对于Pico SDK用户来说，升级到包含MbedTLS 3.x的SDK版本是最推荐的长期解决方案。

对于正在使用Pico SDK进行开发的团队，建议密切关注官方更新，并及时将项目迁移到兼容CMake 4.x的版本，以确保开发环境的长期稳定性和安全性。