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:

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

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-Autor

Informationen über den Projekt-Autor.

Beispiel:

author = "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" }

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

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.

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.

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"

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

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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.