注意
这是一份动态文档。欢迎您通过创建 问题 来提出对该工作流程的更改建议。
本文件描述了我们当前的工作流程。
我们欢迎任何人都来参与并提出对 stdlib 的补充建议。即使您没有规范或实现方面的经验,只要您有关于 stdlib 的想法,都可以提出。如果该想法在社区中很受欢迎,更有经验的贡献者将帮助您完成所有 5 个步骤。
想法: 您有了一个想法或提议。创建一个 问题 来讨论它。这相当于 "社区是否对在 stdlib 中添加图像读取器/写入器函数感兴趣?" 这一步的目的是了解社区是否对将该功能作为 stdlib 的一部分感兴趣。
API: 当提议似乎引起了社区的极大兴趣(绝大多数参与者认为这是一个好主意)时,继续讨论具体的 API。如果您已经有了 API 的想法,可以从一开始就提出。这一步是探索性的,其目标是了解 API 应该看起来和感觉如何。
规范: 讨论 API 并进行迭代。当 API 获得绝大多数人的认可时,继续进行实现并提交 PR。小 PR 总是比大 PR 更好。可以只实现新模块的几个函数,并在之后的 PR 中继续处理其他函数。所有新的功能都放在 "实验性" 命名空间中 (version: experimental
)。在提交 PR 时,如果您提交新的面向公众的 API,请同时提供规范文档的初稿以及该规范的初始参考实现。该 规范是一个文档,它描述了 API 和功能,因此任何人都可以利用它从头开始创建实现,而无需查看 stdlib
。然后,stdlib
库提供参考实现。
实现 (实验性): 当打开 PR 时,请从一个或多个最相关的人员那里请求审查。这些人很可能参与了工作流程的先前步骤。鼓励其他贡献者(未明确邀请)也提供审查和建议。进行迭代,直到所有(或大多数)参与者达成一致。如果对大多数可能的调用场景(有或没有可选参数,有触发错误的参数)都进行了单元测试,并且 PR 获得了绝大多数人的认可,则可以合并 PR。
发布: 从实验性版本迁移到发布版本。实验性 "命名空间" 包含新的功能及其规范。为了从实验性版本迁移到发布版本,规范文档必须获得社区和标准委员会(非正式)的批准。如果获得批准,则表示该功能已获得广泛使用,我们可以将代码迁移到 stdlib
的主部分,并且特定规范文档将成为 Fortran 标准库的一部分。
注意: 上面的 "绝大多数" 一般是指至少 80%,但最终取决于我们自己的判断,以确保社区一致认为每个 PR 和提议都获得了 "绝大多数" 的认可。
欢迎您通过创建 问题 来提出对该工作流程的更改建议。
该项目支持两种构建系统,fpm 和 CMake。
CMake 的构建文件允许树内构建,即构建产物与源文件位于同一目录树,也允许树外构建,即构建产物位于单独的目录树。两种构建类型都明确支持并经过测试,建议在本地开发中使用后者。
主库目标的源文件在 src/CMakeLists.txt
中相对于库目标添加,即不需要使用绝对路径。
要添加测试,应使用宏 ADDTEST
而不是 CMake 函数 add_test
,该宏隐藏了可执行目标的创建,与主库目标的链接以及测试的注册。测试本身在 test
中的子目录中定义为独立的可执行文件,必须在 test/CMakeLists.txt
中注册一个新的包含测试的子目录。
源代码树应被视为只读。对 PROJECT_SOURCE_DIR
和 CMAKE_CURRENT_SOURCE_DIR
的引用只能用于访问源文件,不能用于写入构建输出,应使用 PROJECT_BINARY_DIR
和 CMAKE_CURRENT_BINARY_DIR
来写入构建产物。为了完全支持树内构建,构建产物绝不能与源文件同名,以避免意外覆盖它们,例如在预处理或配置文件时。
CMAKE_INSTALL_PREFIX
只能在安装时写入,不能在构建过程中写入。要安装生成的文件,在构建树中创建一个构建输出,并使用 install
函数安装它。该项目遵循 GNU 安装惯例,这意味着必须使用变量 CMAKE_INSTALL_BINDIR
、CMAKE_INSTALL_LIBDIR
和 CMAKE_INSTALL_INCLUDEDIR
而不是 bin
、lib
和 include
。库目标应该在安装时导出,以便在其他 CMake 项目中正确包含该项目。文件名的首选格式为使用连字符,例如 project-config
或 project-targets
,而不是驼峰式,例如 projectConfig
或 projectTarget
,因为前者可以通过串联 PROJECT_NAME
变量轻松构造。
该项目可以用作 CMake 子项目。必须避免对 CMAKE_SOURCE_DIR
和 CMAKE_BINARY_DIR
的显式引用,以免破坏子项目的构建。您可以在这里 找到一个示例项目 来测试 CMake 子项目集成。