清单参考
内容
清单参考¶
每个项目的文件fpm.toml称为清单（manifest），它是使用TOML格式编写的。每个清单文件都包含以下部分：
name：项目名称
version：项目版本
license：项目许可证
maintainer：项目的维护者
author：项目作者
copyright：项目版权
description：项目描述
categories：与项目相关的类别
keywords：描述项目的关键词
homepage：项目主页
构建（build）配置：
auto-tests：切换测试程序的自动发现
auto-examples：切换示例程序的自动发现
auto-executables：切换应用程序的自动发现
link：与外部依赖项的链接
external-modules：指定不在fpm包中使用的模块
Fortran配置：
implicit-typing：切换默认的隐式类型声明
implicit-external：切换隐式外部接口
source-form：选择项目的源形式
目标部分：
library：函数库目标的配置
executable：应用程序目标的配置
test：测试程序目标的配置
依赖项（dependencies）部分：
dependencies：项目库依赖项Projekts
dev-dependencies：仅测试需要的依赖关系
install：安装配置
preprocess 预处理器配置
extra：额外的自由数据字段
项目版本¶
项目的版本号指定为字符串。管理和指定版本的标准化方法是语义版本控制方案。
例如：
version = "1.0.0"
版本条目还可以包含相对于项目根目录的文件名，其中包含项目的版本号:
例如：
version = "VERSION"
项目许可证¶
项目许可字段包含许可标识符。指定许可信息的标准化方法是[SPDX]标识符。
例如：
根据 GNU 宽通用公共许可证（版本 3 或任何更高版本）许可的项目被指定为：
license = "LGPL-3.0-or-later"
Apache 许可证——版本 2.0 或 MIT 许可证下的双重许可项目被指定为：
license = "Apache-2.0 OR MIT"
项目目标¶
每个fpm项目都可以定义函数库、可执行程序和测试目标。库目标被导出并可用于其它项目。
库配置¶
定义项目的导出库目标。如果在项目中找到源目录或包含目录，则会生成库。默认的源目录和包含目录是src和include；这些可以在库（library）部分中使用源目录（source-dir）和包含目录（include-dir）条目进行修改。源目录和包含目录的目录相对于项目根目录给出，并在所有平台上使用/用作目录分隔符。
例如：
[library]
source-dir = "lib"
include-dir = "inc"
包含目录¶
备注
仅在Fortran fpm中受支持
使用 Fortran include 语句或 C 预处理器 #include 语句的项目可以使用包含目录（include-dir）键为包含的文件指定搜索目录。包含目录（include-dir）可以包含一个或多个目录，其中使用字符串列表指定多个目录。所有项目依赖项中的包含目录都使用相应的编译器标志传递给编译器。
例如：
[library]
include-dir = ["include", "third_party/include"]
备注
包含目录（include-dir）当前不允许使用预构建的.mod模块文件
可执行目标¶
可执行目标是定义为可执行部分的Fortran程序。如果未指定可执行文件（executable）部分，则会在app目录中搜索程序定义。对于显式指定的可执行文件，必须始终指定名称（name）条目。每个可执行文件的源目录都可以在源目录（source-dir）条目中进行调整。源目录的路径是相对于项目根目录给出的，并在所有平台上使用/用作路径分隔符。可以在主（main）条目中指定包含程序正文的源文件。
可执行文件可以有自己的依赖项。有关更多详细信息，请参阅指定依赖项。
可执行文件还可以指定自己的外部库依赖项。有关更多详细信息，请参阅外部库。
备注
仅在Fortran fpm中支持针对库的链接
例如：
[[executable]]
name = "app-name"
source-dir = "prog"
main = "program.f90"
[[executable]]
name = "app-tool"
link = "z"
[executable.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
指定许多单独的可执行文件可以通过使用内联表来完成，以便简洁
executable = [
{ name = "a-prog" },
{ name = "app-tool", source-dir = "tool" },
]
示例目标¶
项目的示例应用程序被定义为示例部分。如果未指定示例（example）部分，则会在example目录中搜索程序定义。对于显式指定的示例，必须始终指定名称（name）条目。每个示例的源目录都可以在源目录（source-dir）条目中进行调整。源目录的路径是相对于项目根目录给出的，并在所有平台上使用/用作路径分隔符。可以在主（main）条目中指定包含程序正文的源文件。
可执行文件可以有自己的依赖项。有关更多详细信息，请参阅指定依赖项。
可执行文件还可以指定自己的外部库依赖项。有关更多详细信息，请参阅外部库。
备注
仅在Fortran fpm中支持针对库的链接
例如：
[[example]]
name = "demo-app"
source-dir = "demo"
main = "program.f90"
[[example]]
name = "example-tool"
link = "z"
[example.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
测试目标¶
测试目标是定义为测试部分的Fortran程序。它们遵循与可执行目标类似的规则。如果未指定测试（test）部分，则会在test目录中搜索程序定义。对于显式指定的测试，必须始终指定名称（name）条目。每个测试的源目录都可以在源目录（source-dir）条目中进行调整。源目录的路径是相对于项目根目录给出的，并在所有平台上使用/用作路径分隔符。可以在主（main）条目中指定包含程序正文的源文件。
可执行文件可以有自己的依赖项。有关更多详细信息，请参阅指定依赖项。
可执行文件还可以指定自己的外部库依赖项。有关更多详细信息，请参阅外部库。
备注
仅在Fortran fpm中支持针对库的链接
例如：
[[test]]
name = "test-name"
source-dir = "testing"
main = "tester.F90"
[[test]]
name = "tester"
link = ["lapack", "blas"]
[test.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
链接外部库¶
备注
仅在Fortran fpm中受支持
要声明外部库的链接时间依赖关系，可以在链接（link）条目中指定本机库的列表。将一个库指定为字符串，或指定一个字符串列表，以防应链接多个库。如果可能，项目应仅链接一个本机库。库依赖项列表将导出到从属包。
例如：
使用 zlib 链接库
[build]
link = "z"
When linking multiple libraries with dependencies, the order matters. A library must appear before the libraries it depends on.
For example, since LAPACK depends on BLAS, BLAS must come later in the list:
[build]
link = ["lapack", "blas"]
使用系统安装的模块¶
若要使用未在fpm包或其依赖项中定义的模块，请使用生成（build）表中的外部模块（external-modules）键指定模块名称。
重要
fpm无法自动定位外部模块文件；用户有责任使用编译器标志指定必要的包含目录，以便编译器可以在编译期间找到外部模块文件。
例如：
[build]
external-modules = "netcdf"
可以将多个外部模块指定为一个列表。
例如：
[build]
external-modules = ["netcdf", "h5lt"]
目标自动发现¶
备注
仅在Fortran fpm中受支持
可执行文件和测试可以在其默认目录中自动发现。自动发现以递归方式在app、example和test目录中搜索定义，并分别将它们声明为可执行目标、示例目标和测试目标。默认情况下，自动发现处于启用状态。
要禁用目标的自动发现，请将自动可执行文件（auto-executables）、自动示例（auto-examples）和自动测试（auto-tests）条目设置为false。
[build]
auto-executables = false
auto-examples = false
auto-tests = false
Fortran特性¶
允许启用和禁用特定的语言功能
源文件格式¶
允许指定项目中所有文件使用的源码形式。可能的选择是"free"假设所有文件都是自由形式的源代码，"fixed"假设所有文件都是固定形式的源代码，"default"让编译器根据自己的启发式方法来决定。默认选项是 "free"。
[fortran]
source-form = "fixed" # default: "free"
指定依赖项¶
可以在清单根或可执行文件（executable）或测试（test）部分的依赖项（dependencies）表中声明依赖项。在清单根目录中声明时，依赖项将与项目一起导出。
来自版本控制系统的依赖关系¶
依赖项可以由项目git存储库指定。
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f" }
要使用特定的上游分支（branch），请使用
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", branch = "main" }
或者，使用标签条目引用标签（tag）
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", tag = "v0.2.1" }
要固定特定修订版，请在修订版（rev）条目中指定提交哈希
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", rev = "2f5eaba" }
对于更详细的布局，请使用普通表而不是内联表来指定依赖项
[dependencies]
[dependencies.toml-f]
git = "https://github.com/toml-f/toml-f"
rev = "2f5eaba864ff630ba0c3791126a3f811b6e437f3"
来自注册表的依赖性¶
备注
To enable the usage of a registry in fpm make sure you read the instructions in the registry section first.
命名空间¶
从注册中心获得的包（包括远程和本地）需要指定一个命名空间，它提供了一种唯一识别和区分名称相同的包的方法。命名空间在清单（fpm.toml）中声明。
[dependencies]
my-package.namespace = "my-namespace"
这将促使fpm从注册表中下载属于 “my-namespace”的 “my-package”的最新版本。
版本¶
如果你想下载一个特定版本的软件包，而不是最新的可用版本，你可以在清单中指定版本（v）。
[dependencies]
example-package.namespace = "example-namespace"
example-package.v = "1.0.0"
本地依赖项¶
若要声明本地依赖项，请使用路径（path）条目。
[dependencies]
my-utils = { path = "utils" }
本地依赖路径是相对于写入它的 fpm.toml 给出的，并在所有平台上使用 / 作为路径分隔符。
Dependency-specific macro setting¶
As of fpm>=0.9.1, an array of dependency-specific macros can be passed to a single dependency from the manifest, in the same fashion as in the manifest’s preprocessor configuration table. Its preprocess table needs to be entered as part of the dependency entry. fpm will not check if the passed macros collide with the dependencie’s own manifest, so, it is the user’s responsibility to ensure that no collisions or unexpected behavior occur.
For example, one can control the REAL precision that one library is to be used with:
[dependencies]
fftpack = { git="https://github.com/fortran-lang/fftpack.git", preprocess.cpp.macros = ["REAL32"] }
开发依赖关系¶
开发依赖项允许在清单根目录中声明开发依赖项（dev-dependencies），这些依赖项可用于所有测试，但不能随项目一起导出。
安装配置¶
在安装（install）部分中，可以选择安装的组件。默认情况下，仅安装可执行文件，库项目可以将库（library）布尔值设置为同时安装模块文件和归档文件。
例如：
[install]
library = true
预处理器配置¶
在 preprocess 部分下，你可以指定一个或多个预处理器以在 fpm 项目中使用。
指定预处理器¶
preprocess 部分允许指定一个或多个预处理器。例如，cpp 可以这样指定：
例如：
[preprocess]
[preprocess.cpp]
要使用多个预处理器，例如 cpp 和 fypp，请像这样指定它们：
例如：
[preprocess]
[preprocess.cpp]
[preprocess.fypp]
你还可以指定预处理器应在其上运行的源文件后缀：
例如：
[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]
此外，你可以指示预处理器在特定目录中的源文件上运行：
例如：
[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]
预处理器宏可以这样定义：
例如：
[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]
我们还可以使用虚线键来定义我们的预处理器设置。
例如：
[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]
我们还可以在预处理表中定义有值的宏。
例如：
[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]
我们还可以重用清单中的版本号等值作为宏的值。
例如：
version = "1"
[preprocess]
[preprocess.cpp]
macros=["VERSION={version}"]
其它可用数据字段¶
第三方工具可以将其配置存储在额外（extra）部分中。此部分永远不会由fpm本身进行评估，施加的唯一约束是它必须是有效的TOML。
由于此部分的格式是自由的，因此此处仅提供了将数据添加到额外（extra）部分的建议。
仅使用子表，切勿将配置数据添加到额外（extra）部分的顶层。推理：不同的工具可以通过将其数据放在单独的子表中来避免键名的冲突。
使用工具的具体名称，而不是子表的通用名称。推理：不同的格式化程序或linter工具可能会在格式（format）或lint子表中使用冲突的关键词。此外，用户还可以从表名中判断哪个工具更适合用于项目。
fpm插件应在extra.fpm部分中使用带有其插件名称的子表来存储其数据。推理：遵循此约定为fpm插件的用户提供一个部分来配置其使用的插件。
对关键词使用fpm首选样式，该样式是小写和短划线。推理：虽然本节中没有样式检查，但整个清单中的一致样式将使用户更容易理解整个包清单。
非常欢迎对上述建议的反馈。如果你有使用包清单中额外（extra）部分的工具，请随时将其发布在fpm讨论板上。