Manuel de référence du manifeste

Le fichier fpm.toml de chaque projet est appelé son manifeste. Il utilise le format TOML. Chaque fichier manifeste est composé des sections suivantes :

  • name: nom du projet

  • version: version du projet

  • license: license du projet

  • maintainer: mainteneur du projet

  • author: auteur du projet

  • copyright: copyright du projet

  • description: description du projet

  • categories: catégories associées au projet

  • keywords: mots-clés décrivant le projet

  • homepage: page d’accueil du projet

  • Configuration de la construction :

    • auto-tests : activer la découverte automatique des exécutables des tests

    • auto-exemples : activer la découverte automatique d’exemples

    • auto-executables: activer la découverte automatique d’exécutables

    • link: lier à des dépendances externes

    • external-modules : spécifier les modules utilisés qui ne font pas partie de votre paquet fpm

  • Sections relatives aux cibles :

    • library configuration de la bibliothèque cible

    • executable configuration des exécutables cibles

    • test configuration des tests cibles

  • Sections concernant les dépendances :

    • dependencies : dépendances de la bibliothèque du projet

    • dev-dependencies : dépendances nécessaires uniquement pour les tests

  • install: configuration de l’installation

  • extra : champ de données libre supplémentaire

Nom du projet

Le nom du projet identifie le paquet et est utilisé pour s’y référer. Il est utilisé lorsque l’on liste le projet comme dépendance d’un autre paquet et est le nom par défaut de la bibliothèque et de la cible exécutable. Par conséquent, le nom du projet doit toujours être présent.

Exemple:

name = "hello_world"

Version du projet

Le numéro de version du projet est spécifié sous forme d’une chaîne. Le schéma Semantic Versioning est une méthode courante pour gérer et spécifier les versions.

Exemple:

version = "1.0.0"

Le champ de version peut également contenir un nom de fichier, relatif à la racine du projet, qui contient le numéro de version du projet.

Exemple:

version = "VERSION"

Licence du projet

Le champ de la licence du projet contient l’identifiant de la licence. Les identifiants SPDX constituent une méthode courante pour spécifier les informations relatives à la licence.

Exemples:

Les projets sous licence GNU Lesser General Public License, pour la version 3 ou toute version ultérieure, sont indiqués ainsi

license = "LGPL-3.0-or-later"

Les projets à double licence, par exemple sous la licence Apache, version 2.0 ou la licence MIT, sont spécifiés comme suit

license = "Apache-2.0 OR MIT"

Mainteneur du projet

Informations sur le responsable du projet et les moyens de le contacter.

Exemple:

maintainer = "jane.doe@example.com"

Auteur du projet

Information sur l’auteur du projet.

Exemple:

author = "Jane Doe"

Description du projet

La description fournit un bref résumé du projet. Elle doit être sous forme de texte brut, sans formatage.

Exemple:

description = "A short summary on this project"

Catégories du projet

Le projet peut être associé à différentes catégories.

Exemple:

categories = ["io"]

Mots-clés du projet

Le champ « keywords » est un tableau de chaînes de caractères décrivant le projet.

Exemple:

keywords = ["hdf5", "mpi"]

Page d’accueil du projet

URL de la page d’accueil du projet.

Exemple:

homepage = "https://stdlib.fortran-lang.org"

Cibles du projet

Chaque projet fpm peut définir des cibles de type bibliothèque, exécutable et test. Les cibles de type bibliothèque sont exportées et utilisables par d’autres projets.

Configuration de la bibliothèque

Définit la cible de la bibliothèque exportée par le projet. Une bibliothèque est générée si le répertoire source ou un répertoire de fichiers inclus est trouvé dans un projet. Les répertoires source et de fichiers inclus sont par défaut src et include ; ils peuvent être modifiés dans la section library en utilisant les entrées source-dir et include-dir. Les chemins pour les répertoires source et de fichiers inclus sont donnés relativement à la racine du projet et utilisent / comme séparateur de chemin sur toutes les plateformes.

Exemple:

[library]
source-dir = "lib"
include-dir = "inc"

Répertoire de fichiers inclus

Note

Supporté uniquement par fpm

Les projets qui utilisent l’instruction Fortran include ou l’instruction du préprocesseur C #include, peuvent utiliser la clé include-dir pour spécifier les répertoires de recherche des fichiers inclus. include-dir peut contenir un ou plusieurs répertoires, les répertoires multiples étant spécifiés en utilisant une liste de chaînes de caractères. Les répertoires de fichiers inclus de toutes les dépendances du projet sont transmis au compilateur en utilisant l’indicateur de compilateur approprié.

Exemple:

[library]
include-dir = ["include", "third_party/include"]

Note

include-dir ne permet pas actuellement d’utiliser les fichiers .mod de modules préconstruits

Cibles exécutables

Les cibles exécutables sont des programmes Fortran définis par des sections executable. Si aucune section executable n’est spécifiée, le répertoire app est recherché pour les déclarations de programmes. Pour les exécutables explicitement spécifiés, l’entrée name doit toujours être renseignée. Le répertoire source de chaque exécutable peut être modifié dans l’entrée source-dir. Les chemins pour le répertoire source sont donnés relativement à la racine du projet et utilisent / comme séparateur de chemin sur toutes les plateformes. Le fichier source contenant le corps du programme peut être spécifié dans l’entrée main.

Les exécutables peuvent avoir leurs propres dépendances. Voir specifying dependencies pour plus de détails.

Les exécutables peuvent également spécifier leurs propres dépendances vis-à-vis des bibliothèques externes. Voir external libraries pour plus de détails.

Note

La liaison avec les bibliothèques n’est supportée qu’avec fpm

Exemple:

[[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" }

Il est possible de spécifier plusieurs exécutables distincts en utilisant un tableau :

executable = [
  { name = "a-prog" },
  { name = "app-tool", source-dir = "tool" },
]

Cibles de type exemple

Les applications d’exemple d’un projet sont définies par des sections example. Si aucune section example n’est spécifiée, le répertoire example est recherché et analysé. Pour les exemples explicitement déclarés, l’entrée name doit toujours être renseignée. Le répertoire source de chaque exemple peut être modifié dans l’entrée source-dir. Les chemins pour le répertoire source sont donnés relativement à la racine du projet et utilisent / comme séparateur de chemin sur toutes les plateformes. Le fichier source contenant le corps du programme peut être indiqué dans l’entrée main.

Les exemples peuvent avoir leurs propres dépendances. Voir specifying dependencies pour plus de détails.

Les exemples peuvent également avoir leurs propres dépendances vis-à-vis de bibliothèques externes. Voir external libraries pour plus de détails.

Note

La liaison avec les bibliothèques n’est supportée qu’avec fpm

Exemple:

[[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" }

Cibles de type test

Les cibles de test sont des programmes Fortran déclarés dans des sections test. Elles suivent les mêmes règles que les cibles exécutables. Si aucune section test n’est spécifiée, le répertoire test est recherché et analysé. Pour les tests explicitement spécifiés, l’entrée name doit toujours être renseignée. Le répertoire source de chaque test peut être modifié dans l’entrée source-dir. Les chemins pour le répertoire source sont donnés relativement à la racine du projet et utilisent / comme séparateur de chemin sur toutes les plateformes. Le fichier source contenant le corps du programme peut être indiqué dans l’entrée main.

Les tests peuvent avoir leurs propres dépendances. Voir specifying dependencies pour plus de détails.

Les tests peuvent également spécifier leurs propres dépendances vis-à-vis de bibliothèques externes. Voir external libraries pour plus de détails.

Note

La liaison avec les bibliothèques n’est supportée qu’avec fpm

Exemple:

[[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" }

Utiliser des modules installés au niveau du système

Pour utiliser des modules qui ne sont pas définis dans votre paquet fpm ou ses dépendances, indiquez le nom du module en utilisant la clé external-modules dans la table build.

Important

fpm ne peut pas localiser automatiquement les fichiers des modules externes ; il est de la responsabilité de l’utilisateur de spécifier les répertoires de fichiers inclus nécessaires en utilisant les drapeaux de compilation de sorte que le compilateur puisse localiser les fichiers des modules externes pendant la compilation.

Exemple:

[build]
external-modules = "netcdf"

Un tableau TOML peut être utilisé pour spécifier plusieurs modules externes.

Exemple:

[build]
external-modules = ["netcdf", "h5lt"]

Découverte automatique des cibles

Note

Supporté uniquement par fpm

Les exécutables et les tests peuvent être découverts automatiquement dans leurs répertoires par défaut. La découverte automatique recherche récursivement dans les répertoires app, example, et test les déclarations program et les déclare respectivement comme cibles d’exécutables, d’exemples et de tests. La découverte automatique est activée par défaut.

Pour désactiver la découverte automatique des cibles, mettez false dans les entrées auto-executables, auto-examples et auto-tests.

[build]
auto-executables = false
auto-examples = false
auto-tests = false

Spécifier les dépendances

Les dépendances peuvent être déclarées dans la table dependencies à la racine du manifeste ou dans les sections executable ou test. Lorsqu’elles sont déclarées à la racine du manifeste, les dépendances sont exportées avec le projet.

Dépendances locales

Pour déclarer des dépendances locales, utilisez l’entrée path.

[dependencies]
my-utils = { path = "utils" }

Les chemins des dépendances locales sont donnés relativement à la racine du projet et utilisent / comme séparateur de chemin sur toutes les plateformes.

Dépendances issues de systèmes de contrôle de version

Les dépendances peuvent être spécifiées par le dépôt git des projets.

[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f" }

Pour utiliser une branche amont spécifique, déclarez le nom de la branche avec

[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", branch = "main" }

Vous pouvez également indiquer les versions en utilisant l’entrée tag

[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", tag = "v0.2.1" }

Pour fixer une version précise, indiquez le hachage du commit dans l’entrée rev

[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", rev = "2f5eaba" }

Pour une présentation plus verbeuse, utilisez une table TOML standard plutôt qu’une table en ligne pour spécifier les dépendances

[dependencies]
[dependencies.toml-f]
git = "https://github.com/toml-f/toml-f"
rev = "2f5eaba864ff630ba0c3791126a3f811b6e437f3"

Dépendances de développement

Les dépendances de développement permettent de déclarer des dev-dependencies dans la racine du manifeste, disponibles pour tous les tests mais pas exportées avec le projet.

Configuration de l’installation

Dans la section install, les composants à installer peuvent être sélectionnés. Par défaut, seuls les exécutables sont installés. Les projets de type bibliothèque peuvent définir le booléen library pour installer également les fichiers module et l’archive.

Exemple

[install]
library = true

Champ de données libres supplémentaire

Les outils tiers peuvent stocker leur configuration dans la section extra. Cette section ne sera jamais traitée par fpm lui-mêmeL La seule contrainte est qu’elle doit être écrite en TOML valide.

Le format de cette section étant libre, seules des recommandations sont fournies ici pour ajouter des données à la section extra.

  1. N’utilisez que des sous-tables, n’ajoutez jamais de données de configuration au niveau supérieur de la section extra. Raison : différents outils peuvent ainsi éviter les collisions de noms de champs en plaçant leurs données dans des sous-tables séparées.

  2. Utilisez le nom concret de l’outil plutôt qu’un nom générique pour la sous-table. Raison : différents outils de formatage ou d’analyse de code peuvent utiliser des mots-clés en conflit dans une sous-table format ou lint. En outre, les utilisateurs peuvent savoir, d’après le nom de la table, quel outil il est préférable d’utiliser pour le projet.

  3. Les greffons fpm doivent utiliser une sous-table avec leur nom de greffon dans la section extra.fpm pour stocker leurs données. Raison : en suivant cette convention, l’utilisateur de greffons fpm dispose d’une section pour configurer les greffons qu’il utilise.

  4. Utilisez le style standard de fpm pour les mots-clés, c’est-à-dire en minuscules avec des tirets. Raison : bien qu’il n’y ait pas de contrôle de style dans cette section, un style cohérent dans l’ensemble du manifeste facilitera la compréhension du manifeste du paquet par l’utilisateur.

Les commentaires sur les recommandations ci-dessus sont les bienvenus. Si vous avez un outil qui utilise la section extra dans le manifeste du paquet, n’hésitez pas à le poster dans la section discussion de fpm.