マニフェスト詳説
目次
マニフェスト詳説¶
各プロジェクトのfpm.tomlファイルは，マニフェストとよばれています．これはTOML形式で記述されます．マニフェストファイルは，以下の設定項目で構成されます．
name: プロジェクトの名前
version: プロジェクトのバージョン
license: プロジェクトのライセンス
maintainer: プロジェクトのメンテナ
author: プロジェクトの作成者
copyright: プロジェクトの著作権
description: プロジェクトの概要
categories: プロジェクトに関連する分類
keywords: プロジェクトを説明するキーワード
homepage: プロジェクトのホームページ
ビルド設定:
auto-tests: テスト用実行ファイルの自動検出の切替
auto-examples: サンプルプログラムの自動検出の切替
auto-executables: 実行ファイルの自動検出の切替
link: 外部依存関係とのリンク
external-modules: fpmパッケージ内に存在しないモジュールの指定
Fortran configuration:
implicit-typing: Toggle default implicit typing
implicit-external: Toggle implicit external interfaces
source-form: Select source form for project
構築対象に関する設定項目
library ビルドされるライブラリの設定
executable ビルドされる実行ファイルの設定
test ビルドされるテストの設定
依存関係に関する設定項目
dependencies: プロジェクトが参照するライブラリの依存関係
dev-dependencies: テストのみに必要な依存関係
install: インストール設定
preprocess Preprocessor configuration
extra: 設定の追加欄
プロジェクトの名前¶
プロジェクト名は，パッケージを識別し，それを参照するために用いられます．ライブラリと実行ファイルの標準の名前として用いられ，また他のパッケージの依存関係としてプロジェクトを列挙するときにも用いられます．したがって，プロジェクト名は常に記述する必要があります．
例:
name = "hello_world"
プロジェクトのバージョン¶
プロジェクトのバージョン番号を文字列で指定します．バージョンを管理・指定する標準的な方法は，セマンティックバージョニングです．
例:
version = "1.0.0"
versionの設定値として，プロジェクトのバージョン番号を含むファイルの名前をプロジェクト直下からの相対パスで指定できます．
例:
version = "VERSION"
プロジェクトのライセンス¶
プロジェクトのライセンス設定欄には，ライセンス識別子を記述します．ライセンス情報を指定する標準的な方法は，SPDX識別子です．
例:
GNU Lesser General Public Licenseのバージョン3もしくはそれ以降の下で許諾されるプロジェクトは，次のように指定します．
license = "LGPL-3.0-or-later"
Apache license, version 2.0もしくはMIT licenseのデュアルライセンスのプロジェクトの場合は，次のように指定します．
license = "Apache-2.0 OR MIT"
プロジェクトの概要¶
プロジェクトに関する要約を記述します．プレーンテキストを用いてください．装飾用の情報は挿入しないでください．
例:
description = "A short summary on this project"
プロジェクトの構築対象¶
すべての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ファイルを使用できません．
実行ファイル¶
実行ファイルは，executable設定項目で指定されたFortranのプログラムです．もしexecutableが書かれていない場合，appディレクトリでprogramの定義が探索されます．明示的に実行ファイルを設定する場合，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が指定されていない場合，exampleディレクトリでprogramの定義が探索されます．明示的にサンプルを設定する場合，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" }
テスト¶
テストは，test設定項目で定義されたFortranプログラムです．これらは実行ファイルと同様の規則に従います．もしtestが指定されていない場合，testディレクトリでprogramの定義が探索されます．明示的にテストを設定する場合，nameが指定されている必要があります．各実行ファイルのソースディレクトリは，source-dirで設定できます．ソースディレクトリへのパスは，プロジェク直下からの相対パスで与え，パスの区切りには/を用います．プログラム本体を含むソースファイルの名前は，mainで指定します．
複数のテストがある場合，テストごとに依存関係を持つことができます．依存関係の指定を参照してください．
複数のテストがある場合，テストごとに外部ライブラリを指定できます．外部ライブラリのリンクを参照してください．
注釈
ライブラリのリンクは，Fortran fpmのみ対応しています．
例:
[[test]]
name = "test-name"
source-dir = "testing"
main = "tester.F90"
[[test]]
name = "tester"
link = ["blas", "lapack"]
[test.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
外部ライブラリのリンク¶
注釈
Fortran fpmのみ対応しています．
外部ライブラリリンク時の依存関係を宣言するために，link設定項目にネイティブライブラリの一覧を指定できます．一つのライブラリは文字列で指定し，複数のライブラリをリンクする場合は文字列のリストを用います．できることなら，プロジェクトは一つのネイティブライブラリのみをリンクするべきでしょう．依存ライブラリの一覧は，依存するパッケージにも展開されます．
例:
zlib圧縮ライブラリをリンクするには，次の設定を用います．
[build]
link = "z"
LAPACKに依存する場合，BLASもリンクする必要があります．この場合，ライブラリの順番に意味があります．
[build]
link = ["blas", "lapack"]
システムにインストールされたモジュールの利用¶
fpmパッケージやその依存関係の中で定義されていないモジュールを利用するには，build設定項目のexternal-modulesを使用して，モジュールの名前を指定します．
重要
fpmは，外部モジュールファイルの位置を自動的に特定できません．ユーザは，コンパイラがコンパイル時に外部モジュールファイルを発見できるように，コンパイラフラグを利用してインクルードディレクトリを指定しなければなりません．
例:
[build]
external-modules = "netcdf"
複数の外部モジュールをリストで指定できます．
例:
[build]
external-modules = ["netcdf", "h5lt"]
構築対象の自動検出¶
注釈
Fortran fpmのみ対応しています．
実行ファイルとテストは，標準のディレクトリ内であれば自動的に検出されます．自動検出では，app, example, testディレクトリ内のprogramの定義を再帰的に検索し，実行ファイル，サンプル，テストをそれぞれ構築対象として宣言します．自動検出は，標準で有効にされています．
構築対象の自動検出を無効にするには，auto-executables, auto-examples, auto-testsをfalseに設定します．
[build]
auto-executables = false
auto-examples = false
auto-tests = false
Fortran features¶
Allows to enable and disable specific language features
Implicit typing¶
Allows to toggle whether the default implicit typing should be used.
The default option is false.
[fortran]
implicit-typing = true # default: false
Implicit external¶
Allows to toggle whether external interfaces can be declared implicitly.
The default option is false.
[fortran]
implicit-external = true # default: false
Source form¶
Allows to specifiy the source form to be used for all files in the project.
Possible choices are "free" to assume all files are free form source,
"fixed" to assume all files are fixed form source,
and "default" to let the compiler decide based on its own heuristics.
The default option is "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"
Dependencies from a registry¶
注釈
To enable the usage of a registry in fpm make sure you read the instructions in the registry section first.
Namespace¶
Packages obtained from a registry (both remote and local) are required to specify a namespace, which provides a way to uniquely identify and differentiate packages with identical names. The namespace is declared in the manifest (fpm.toml).
[dependencies]
my-package.namespace = "my-namespace"
This will prompt fpm to download the newest version of "my-package", which belongs to "my-namespace", from the registry.
Version¶
If you want to download a specific version of a package instead of the newest one available, you can specify the version (v) in the manifest.
[dependencies]
example-package.namespace = "example-namespace"
example-package.v = "1.0.0"
ローカルな依存関係の指定¶
ローカルな依存関係を宣言するには，pathを用います．
[dependencies]
my-utils = { path = "utils" }
The local dependency path is given relative to the fpm.toml it is written to, and uses / as the path separator on all platforms.
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
Preprocessor configuration¶
Under the preprocess section, you can specify one or more preprocessor to use in an fpm project.
Specifying the preprocessor¶
The preprocess section allows one or more preprocessors to be specified.
For example, cpp can be specified like this :
例
[preprocess]
[preprocess.cpp]
To use multiple preprocessors, for example cpp and fypp, specify them like this:
例
[preprocess]
[preprocess.cpp]
[preprocess.fypp]
You can also specify source file suffixes that the preprocessor should run on:
例
[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]
Further, you can instruct the preprocessor to run on source files in specific directories:
例
[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]
Preprocessor macros can be defined like this:
例
[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]
We can also use dotted keys to define our preprocessor settings.
例
[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]
We can also define valued macros in preprocess table.
例
[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]
We can also reuse values like version number from manifest as a value for a macro.
例
version = "1"
[preprocess]
[preprocess.cpp]
macros=["VERSION={version}"]
設定の追加欄¶
extra設定項目内に，第三者製ツールの設定を記述できます．この設定項目は，fpmによって評価はされません．正当なTOML形式であることが唯一の制約です．
この項目の書式は自由なので，ここではextraに追加するデータの推奨事項のみを示します．
サブテーブルのみを使用し，extraに設定を追加してはならない．根拠：異なるツールが参照するデータを個々のサブテーブルに配置することで，名前の衝突を避けることができる．
サブテーブルには，一般的な名前ではなく，ツールの具体的な名前を用いる．根拠：異なるフォーマッタやリンタが，formatあるいはlintサブテーブル内で相反するキーワードを使用する可能性がある．また，どのツールをプロジェクトで利用するのが適切かを，ユーザがテーブルの名前から判断できる．
fpmのプラグインは，extra.fpm項目内でプラグイン名を持つサブテーブルを使用してデータを格納する．根拠：この規約に従うことで，利用するプラグインの設定が書かれた単一の設定項目をユーザに提供できる．
キーワードの記述には，小文字とダッシュで構成されるfpmのスタイルを使用する．根拠：この設定項目の書式はチェックされないが，マニフェスト全体で一貫した書式を維持することにより，ユーザがパッケージマニフェスト全体を理解しやすくなる．
上記推奨事項に対する反応を歓迎します．もしあなたがパッケージマニフェストのextra設定項目を使用するツールをお持ちの場合は，fpmディスカッション掲示板にその情報を投稿してください．