PolarSSL项目中重复common.h文件问题的分析与解决方案

问题背景

在PolarSSL（现为Mbed TLS）项目中，开发人员发现存在两个完全相同的common.h头文件，分别位于library/common.h和tf-psa-crypto/core/common.h路径下。这种重复不仅增加了维护成本，还可能导致构建问题，特别是对于那些不使用项目构建脚本而直接引用源代码的用户。

问题分析

头文件重复带来的主要问题体现在两个方面：

1. 维护困难：开发者在修改一个文件时容易忽略另一个副本，导致两个文件内容不同步，引发难以排查的问题。

2. 构建风险：当用户直接引用项目源代码而非使用构建系统时，两个同名但不同路径的头文件可能导致编译器无法正确解析包含路径，从而破坏构建过程。

技术讨论

在深入讨论解决方案时，开发团队提出了几个关键点：

1. 构建系统差异：Mbed TLS和TF-PSA-Crypto使用不同的构建系统，它们生成的build_info.h内容也不同。Mbed TLS的build_info.h需要包含mbedtls_config.h用于TLS和X509配置，而TF-PSA-Crypto的build_info.h则有其特定配置。

2. 头文件包含顺序：调整头文件包含顺序可能带来未定义结构体、成员或函数的问题，需要谨慎处理。

3. 模块化设计：理想情况下，应该将通用功能拆分到主题明确的头文件中，如已经实现的alignment.h。

解决方案

经过深入讨论，团队确定了以下解决方案路径：

1. 分离通用头文件：

   • 创建mbedtls_common.h和tf_psa_crypto_common.h两个不同的头文件
   • 每个头文件包含各自项目的build_info.h（分别为mbedtls/build_info.h和psa/build_info.h）

2. 重构包含关系：

   • 将当前common.h中的大部分内容拆分到专门的头文件中
   • 保持Mbed TLS公共头文件包含TF-PSA-Crypto头文件的关系

3. 调整包含顺序：

   • 确保build_info.h在任何其他代码之前被包含
   • 将ssl_misc.h和x509_internal.h的包含移到源文件顶部

实施建议

对于实际实施，建议采用以下步骤：

1. 使用git命令正确处理文件移动历史：

   git rm tf-psa-crypto/core/common.h
   git commit
   git mv library/common.h tf-psa-crypto/core
   git commit
   

2. 逐步重构头文件包含关系，确保每一步都经过充分测试

3. 特别注意SSL和X509模块的特殊需求，可能需要保留某些特定的包含顺序

总结

通过将通用功能模块化并明确区分不同组件的头文件，不仅可以解决当前的文件重复问题，还能为项目未来的扩展和维护奠定更好的基础。这种重构虽然需要谨慎实施，但从长期来看将显著提高代码的可维护性和构建可靠性。