Manifest-Referenz
Inhalt
Manifest-Referenz¶
Die fpm.toml Datei für jedes Projekt wird als Manifest-Datei benannt. Sie wird im [TOML] Format geschrieben. Jede Manifest-Datei enthält folgende Abschnitte:
name: Der Name des Projekts
version: Die Version des Projekts
license: Die Lizenz des Projekts
maintainer: Der Maintainer des Projekts
author: Der Autor des Projekts
copyright: Copyright des Projekts
description: Die Beschreibung des Projekts
categories: Kategorien, die dem Projekt zugeordnet sind
keywords: Schlüsselwörter, die dem Projekt zugeordnet sind
homepage: Die Homepage des Projekts
Build-Konfiguration:
auto-tests: Automatische Erkennung von Test Programmen
auto-examples: Automatische Erkennung von Beispiel Programmen
auto-executables: Automatische Erkennung von Programmen
link: Link mit externen Abhängigkeiten
external-modules: Module, die nicht innerhalb des fpm Paketes definiert werden
Fortran configuration:
implicit-typing: Toggle default implicit typing
implicit-external: Toggle implicit external interfaces
source-form: Select source form for project
Target-Abschnitte:
library Konfiguration des Library-Targets
executable Konfiguration der Executable-Targets
test Konfiguration der Test-Targets
Abhängigkeiten-Abschnitte:
dependencies: Abhängigkeiten des Projekts
dev-dependencies: Abhängigkeiten, die nur für Tests benötigt werden
install: Installation-Konfiguration
[Vorverarbeitung] (#preprocessor-configuration) Präprozessor-Konfiguration
extra: Zusätzliches freies Datenfeld
Projektname¶
Der Projektname identifiziert das Paket und wird benutzt, um es zu referenzieren. Er wird verwendet, um das Projekt als Abhängigkeit für ein anderes Paket zu listen und der Standardname des Library- und Executable-Targets. Daher muss der Projektname immer vorhanden sein.
Beispiel:
name = "hello_world"
Projektversion¶
Die Versionsnummer des Projekts wird als String angegeben. Eine Standardisierungsmethode zur Versionsverwaltung und zur Spezifikation der Versionsnummer ist das [Semantic Versioning] Schema.
Beispiel:
version = "1.0.0"
Die Versions-Eintrag kann auch einen Dateinamen relativ zum Projekt-Wurzel-Verzeichnis enthalten, der die Versionsnummer des Projekts enthält
Beispiel:
version = "VERSION"
Projekt-Lizenz¶
Das Projekt-Lizenz-Feld enthält den Lizenz-Identifikator. Eine Standardisierungsmethode zur Spezifikation der Lizenzinformationen sind die [SPDX] Identifikatoren.
Beispiele:
Projekte, die unter der [GNU Lesser General Public License] (https://www.gnu.org/licenses/lgpl-3.0-standalone.html), entweder Version 3 oder jede spätere Version, werden angegeben als
license = "LGPL-3.0-or-later"
Projekte, die unter der [Apache-Lizenz, Version 2.0] (http://www.apache.org/licenses/LICENSE-2.0) oder der [MIT-Lizenz] (https://opensource.org/licenses/MIT) lizenziert sind, werden angegeben als
license = "Apache-2.0 OR MIT"
Projekt-Maintainer¶
Informationen über den Projekt-Maintainer und die Möglichkeit zur Kontakaufname.
Beispiel:
maintainer = "jane.doe@example.com"
Projekt-Copyright¶
Eine Aussage, die den Copyright-Status des Projekts klarifiziert.
Beispiel:
copyright = "Copyright 2020 Jane Doe"
Projekt-Beschreibung¶
Die Beschreibung stellt eine kurze Zusammenfassung des Projekts dar. Sie sollte keine Markup-Formatierung verwenden.
Beispiel:
description = "A short summary on this project"
Projekt-Kategorien¶
Das Projekt kann mit verschiedenen Kategorien assoziiert werden.
Beispiel:
categories = ["io"]
Projekt-Schlüsselwörter¶
Das Schlüsselwort-Feld ist ein Feld von Strings, die das Projekt beschreiben.
Beispiel:
keywords = ["hdf5", "mpi"]
Projekt-Homepage¶
URL zur Webseite des Projekts.
Beispiel:
homepage = "https://stdlib.fortran-lang.org"
Projekt-Ziele¶
Jedes fpm-Projekt kann Bibliotheken, ausführbare Programme und Tests definieren. Bibliotheken werden exportiert und für andere Projekte nutzbar.
Bibliotheks-Konfiguration¶
Definiert das exportierte Bibliotheks-Ziel des Projekts. Eine Bibliothek wird generiert, wenn die Quell- oder Include-Verzeichnisse im Projekt gefunden werden. Die Standard-Quell- und Include-Verzeichnisse sind src und include; diese können in der library-Sektion mit den source-dir und include-dir Einträgen angepasst werden. Pfade für die Quell- und Include-Verzeichnisse sind relativ zum Projekt-Wurzelverzeichnis und verwenden / als Pfad-Trenner auf allen Plattformen.
Beispiel:
[library]
source-dir = "lib"
include-dir = "inc"
Include-Verzeichnis¶
Bemerkung
Nur in Fortran fpm unterstützt
Projekte, die die Fortran-Include-Anweisung oder die C-Präprozessor-Include-Anweisung verwenden, können das Schlüsselwort include-dir verwenden, um die Verzeichnisse für die eingebundenen Dateien anzugeben. include-dir kann ein oder mehrere Verzeichnisse enthalten, in denen mehrere Verzeichnisse als Liste von Strings angegeben werden. Die Include-Verzeichnisse aller Projekt-Abhängigkeiten werden dem Compiler mittels dem entsprechenden Kompilierungsoptionen übergeben.
Beispiel:
[library]
include-dir = ["include", "third_party/include"]
Bemerkung
include-dir erlaubt derzeit keine Verwendung von breits kompilierten .mod-Dateien
Ausführbare Ziele¶
Ausführbare Ziele sind Fortran-Programme definiert als executable-Sektionen. Wenn keine executable-Sektion angegeben ist, wird das app-Verzeichnis für Programmdefinitionen gesucht. Für explizit angegebene Ausführbare muss immer das name-Eintrag angegeben werden. Das Quell-Verzeichnis für jedes Ausführbare kann in dem source-dir-Eintrag angepasst werden. Pfade für das Quell-Verzeichnis sind relativ zum Projekt-Wurzelverzeichnis und verwenden / als Pfad-Trenner auf allen Plattformen. Die Quell-Datei mit dem Programm-Körper kann in dem main-Eintrag angegeben werden.
Ausführbare Programme können ihre eigenen Abhängigkeiten haben. Siehe spezifizieren von Abhängigkeiten für weitere Details.
Ausführbare Programme können auch ihre eigenen externen Bibliotheksabhängigkeiten spezifizieren. Siehe externe Bibliotheken für weitere Details.
Bemerkung
Nur Fortran fpm unterstützt das Linken gegen Bibliotheken
Beispiel:
[[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" }
Viele separate Ausführbare können auch mittels Inline-Tabellen spezifiziert werden
executable = [
{ name = "a-prog" },
{ name = "app-tool", source-dir = "tool" },
]
Beispiel-Ziele¶
Beispiel-Programme für ein Projekt sind definiert als example-Sektionen. Wenn keine example-Sektion angegeben ist, wird das example-Verzeichnis für Programmdefinitionen gesucht. Für explizit angegebene Beispiele muss immer das name-Eintrag angegeben werden. Das Quell-Verzeichnis für jedes Beispiel kann in dem source-dir-Eintrag angepasst werden. Pfade für das Quell-Verzeichnis sind relativ zum Projekt-Wurzelverzeichnis und verwenden / als Pfad-Trenner auf allen Plattformen. Die Quell-Datei mit dem Programm-Körper kann in dem main-Eintrag angegeben werden.
Beispiel-Programme können ihre eigenen Abhängigkeiten haben. Siehe spezifizieren von Abhängigkeiten für weitere Details.
Beispiel-Programme können auch ihre eigenen externen Bibliotheksabhängigkeiten spezifizieren. Siehe externe Bibliotheken für weitere Details.
Bemerkung
Nur Fortran fpm unterstützt das Linken gegen Bibliotheken
Beispiel:
[[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-Ziele¶
Test-Programme sind in Fortran definiert als test-Sektionen. Sie folgen ähnlichen Regeln wie Ausführbare Programme. Wenn keine test-Sektion angegeben ist, wird das test-Verzeichnis für Programmdefinitionen gesucht. Für explizit angegebene Tests muss immer das name-Eintrag angegeben werden. Das Quell-Verzeichnis für jedes Test kann in dem source-dir-Eintrag angepasst werden. Pfade für das Quell-Verzeichnis sind relativ zum Projekt-Wurzelverzeichnis und verwenden / als Pfad-Trenner auf allen Plattformen. Die Quell-Datei mit dem Programm-Körper kann in dem main-Eintrag angegeben werden.
Test-Programme können ihre eigenen Abhängigkeiten haben. Siehe spezifizieren von Abhängigkeiten für weitere Details.
Test-Programme können auch ihre eigenen externen Bibliotheksabhängigkeiten spezifizieren. Siehe externe Bibliotheken für weitere Details.
Bemerkung
Nur Fortran fpm unterstützt das Linken gegen Bibliotheken
Beispiel:
[[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" }
Externe Bibliotheken verlinken¶
Bemerkung
Nur in Fortran fpm unterstützt
Um Abhängigkeiten auf externe Bibliotheken zu deklarieren, kann eine Liste von nativen Bibliotheken in das link-Eintrag angegeben werden. Geben Sie eine Bibliothek als Zeichenkette oder eine Liste von Zeichenketten an, wenn mehrere Bibliotheken verlinkt werden sollen. Wenn möglich sollte das Projekt nur eine nativen Bibliothek verlinken. Die Liste der Bibliotheksabhängigkeiten wird in abhängigen Paketen exportiert.
Beispiel:
Um gegen die zlib-Kompressionsbibliothek zu linken, kann die folgende Eingabe genutzt werden
[build]
link = "z"
Um LAPACK zu nutzen, sollte auch gegen BLAS gelinkt werden. In diesem Fall ist die Reihenfolge der Bibliotheken wichtig:
[build]
link = ["blas", "lapack"]
System-installierte Module verwenden¶
Um Module, die nicht in einem fpm-Paket oder Abhängigkeiten definiert sind, anzugeben, müssen diese im build-Tabellen-Eintrag unter external-modules angegeben werden.
Wichtig
fpm kann nicht automatisch externe Modul-Dateien finden; es ist die Verantwortung der Benutzer*in, die benötigten Include-Verzeichnisse mittels Kompiler-Optionen anzugeben, damit der Kompiler externe Modul-Dateien finden kann, während der Kompilierung.
Beispiel:
[build]
external-modules = "netcdf"
Mehrere externe Module können als Liste angegeben werden.
Beispiel:
[build]
external-modules = ["netcdf", "h5lt"]
Automatische Zielerkennung¶
Bemerkung
Nur in Fortran fpm unterstützt
Ausführbare Programme und Tests können automatisch in ihren Standard- Verzeichnissen gefunden werden. Die automatische Erkennung rekursiv sucht die app-, example- und test-Verzeichnisse nach program-Definitionen und deklarieren diese als ausführbare, Beispiel- und Test-Ziele, entsprechend. Die automatische Erkennung wird standardmäßig aktiviert.
Um die automatische Erkennung von Zielen zu deaktivieren, setzen Sie die Einträge auto-executables, auto-examples, und auto-tests auf 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"
Abhängigkeiten spezifizieren¶
Abhängigkeiten können in der dependencies-Tabelle im Manifest-Wurzel- Eintrag oder in den executable oder test-Abschnitten angegeben werden. Wenn sie im Manifest-Wurzel-Eintrag angegeben werden, werden sie mit dem Projekt exportiert.
Abhängigkeiten von Version-Kontrollsystemen¶
Abhängigkeiten können durch die Git-Repository des Projekts angegeben werden.
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f" }
Um einen bestimmten Branch des Upstreams anzugeben, muss der branch-Name mit angegeben werden
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", branch = "main" }
Alternativ können Referenz-Tags durch den Eintrag tag verwendet werden
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", tag = "v0.2.1" }
Um eine bestimmte Revision festzulegen, muss der Commit-Hash im rev-Eintrag angegeben werden
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", rev = "2f5eaba" }
Für eine ausführlichere Layout-Darstellung können normal-Tabellen statt inline-Tabellen zur Abhängigkeits-Spezifikation verwendet werden
[dependencies]
[dependencies.toml-f]
git = "https://github.com/toml-f/toml-f"
rev = "2f5eaba864ff630ba0c3791126a3f811b6e437f3"
Dependencies from a registry¶
Bemerkung
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"
Lokale Abhängigkeiten¶
Um lokale Abhängigkeiten anzugeben, muss der path-Eintrag genutzt werden.
[dependencies]
my-utils = { path = "utils" }
Lokale Abhängigkeits-Pfade sind relativ zum Projekt-Wurzelverzeichnis angegeben und verwenden / als Pfad-Trenner auf allen Plattformen.
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"] }
Entwicklungsabhängigkeiten¶
Entwicklungsabhängigkeiten ermöglichen es, dev-dependencies im Manifest-Wurzel-Eintrag anzugeben, die für alle Tests verfügbar sind, aber nicht mit dem Projekt exportiert werden.
Installations-Konfiguration¶
In den install-Abschnitten können Komponenten für die Installation ausgewählt werden. Standardmäßig werden nur ausführbare Projekte installiert, Library-Projekte können das library-Attribut auf true setzen, um die Module-Dateien auch zu installieren und das Archiv.
Beispiel
[install]
library = true
Konfiguration des Präprozessors¶
Unter dem Abschnitt preprocess können ein oder mehrere Präprozessoren angeben werden, die in einem fpm-Projekt verwendet werden sollen.
Spezifizierung des Präprozessors¶
Im Abschnitt preprocess können ein oder mehrere Präprozessoren angegeben werden. Zum Beispiel kann cpp wie folgt angegeben werden:
Beispiel
[preprocess]
[preprocess.cpp]
Um mehrere Präprozessoren zu verwenden, z. B. cpp und fypp, werden diese wie folgt angegeben:
Beispiel
[preprocess]
[preprocess.cpp]
[preprocess.fypp]
Auch Suffixe von Quelldateien mit denen der Präprozessor arbeiten soll können angeben werden:
Beispiel
[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]
Außerdem können Sie den Präprozessor anweisen, mit Quelldateien in bestimmten Verzeichnissen zu arbeiten:
Beispiel
[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]
Präprozessor-Makros können wie folgt definiert werden:
Beispiel
[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]
Wir können auch gepunktete Schlüssel verwenden, um unsere Präprozessoreinstellungen zu definieren.
Beispiel
[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]
Wir können in der Präprozessortabelle auch Makros mit Werten definieren.
Beispiel
[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]
Wir können auch die Wiederverwendung von Werten wie der Versionsnummer von Manifest als Wert für einen Makro auswerten.
Beispiel
version = "1"
[preprocess]
[preprocess.cpp]
macros=["VERSION={version}"]
Zusätzliches freies Datenfeld¶
Externe Tools können ihre Konfiguration in den extra-Abschnitten speichern. Dieser Abschnitt wird von fpm nie evaluiert, es wird nur eine Einschränkung gesetzt, dass gültiges TOML benutzt wird.
Da das Format dieses Abschnitts frei ist, werden hier nur Empfehlungen für das Hinzufügen von Daten zum extra-Abschnitt angegeben.
Verwenden Sie nur Untertabellen, niemals Daten in den extra-Abschnitt auf der obersten Ebene hinzufügen. Grund: verschiedene Tools können Kollisionen von Schlüsselnamen vermeiden, indem ihre Daten in separate Untertabellen gespeichert werden.
Verwenden Sie den konkreten Namen des Tools statt eines generischen Namens für die Untertabelle. Grund: verschiedene Formatter- oder Linter-Tools können in einer format- oder lint-Untertabelle widersprüchliche Schlüsselwörter verwenden. Benutzer*innen können auch von dem Tabellennamen auf die Tool-Vorgabe des Projekts hinweisen.
Fpm-Plugins sollten eine Untertabelle in den extra.fpm-Abschnitten mit ihrem Plugin-Namen speichern. Grund: diese Verwendung ermöglicht der Benutzer*in von fpm-Plugins eine einzige Sektion zur Konfiguration ihrer benutzten Plugins.
Verwenden Sie den fpm-vorherigen Stil für Schlüsselwörter, der Konkatenation mit Bindestrichen in Kleinbuchstaben darstellt. Grund: während keine Überprüfung in diesem Abschnitt stattfindet, macht ein konsistenter Stil im gesamten Manifest es einfacher für die Benutzer*in das gesamte Paket-Manifest zu verstehen.
Rückmeldungen und Vorschläge für die oben genannten Empfehlungen ist sehr herzlich willkommen. Wir freuen uns über Rückmeldungen im fpm-Diskussionsforum von Tools, die den extra-Abschnitt im Paket-Manifest verwenden.