### 如何在 PlatformIO 中正确添加和使用 `.cpp` 和 `.h` 文件 #### 项目结构概述 PlatformIO 提供了一种清晰的项目结构来管理源文件和头文件。通常情况下，`.cpp` 文件存放在 `src` 文件夹中，而 `.h` 文件可以放置在同一目录下或者单独创建一个 `include` 或者其他命名的文件夹用于存放这些头文件[^1]。 #### 头文件的组织方式 为了更好地管理和维护代码，建议将所有的 `.h` 文件集中存储在一个特定的文件夹中（例如命名为 `include`）。这样做的好处是可以让项目的层次更加分明，并且便于后续扩展或调试。如果希望实现这一布局，则可以在 `platformio.ini` 配置文件中的 `[env:]` 节点通过设置 `build_flags` 参数指定额外的包含路径： ```ini [env:my_custom_env] platform = ... board = ... framework = ... build_flags = -I${PROJECT_DIR}/include ``` 这里 `-I` 是告诉编译器去哪里寻找头文件的一个标志符，`${PROJECT_DIR}` 表达的是当前项目的根目录位置[^2]。 #### 添加多个 `.cpp` 文件至构建过程 当有多个 `.cpp` 文件需要参与编译时，只需简单地把它们放入 `src` 文件夹即可。PlatformIO 默认会自动识别并处理该文件夹下的所有 C++ 源码文件[^1]。假设存在两个分别叫做 `main.cpp` 和 `helper.cpp` 的文件，那么无需做任何特别操作，两者都会被纳入最终的目标链接阶段。 对于跨文件间的函数调用情况，确保相应的声明已经写进了公共可见范围内的头文件里，并且每个 `.cpp` 实现部分都包含了必要的头部引用语句。比如，在某个辅助功能模块中有如下定义： ```cpp // helper.h #ifndef HELPER_H_ #define HELPER_H_ void doSomething(); #endif /* HELPER_H_ */ ``` 以及它的具体实现在另一个地方给出： ```cpp // helper.cpp #include "helper.h" void doSomething() { // Function implementation... } ``` 此时，主程序只需要引入此接口描述就可以正常使用它所提供的服务了： ```cpp // main.cpp #include <Arduino.h> #include "helper.h" void setup() { Serial.begin(9600); } void loop() { doSomething(); delay(1000); } ``` 以上例子展示了如何分离逻辑单元并通过标准机制相互协作完成任务[^3]。 #### 自定义库的支持 如果有更复杂的场景涉及到第三方或者是自行开发的大规模组件集合，推荐按照官方文档指引的方式去注册新的库资源。这不仅限于简单的单一文件形式，还可以打包成完整的解决方案提供给他人重复利用[^4]。 另外值得注意的一点是关于某些特殊硬件平台可能存在的兼容性考量，例如针对 STC 单片机系列所做的适配工作就需要额外关注其特有的寄存器地址映射关系等问题。 ---