Manuel de référence du manifeste
Contenu
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
Configuration Fortran :
implicit-typing : Basculer le typage implicite par défaut
implicit-external : Basculer les interfaces externes implicites
source-form : Sélectionner le format de code source du projet
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
preprocess Configuration d’un préprocesseur
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"
Copyright du projet¶
Une déclaration clarifiant le statut des droits d’auteur du projet.
Exemple:
copyright = "Copyright 2020 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" }
Liaison à des bibliothèques externes¶
Note
Supporté uniquement par fpm
Pour déclarer des dépendances à des bibliothèques externes, gérées lors de l’édition de liens, une liste de bibliothèques natives peut être spécifiée dans l’entrée link. Spécifiez soit une bibliothèque à l’aide d’une chaîne, soit une liste de chaînes dans le cas où plusieurs bibliothèques doivent être liées. Quand c’est possible, le projet ne devrait être lié qu’à une seule bibliothèque native. La liste des bibliothèques nécessaires est exportée vers les paquets dépendants.
Exemple:
Pour établir un lien avec la bibliothèque de compression zlib, utilisez
[build]
link = "z"
Pour dépendre de LAPACK, il faut également lier BLAS. Dans ce cas, l’ordre des bibliothèques est important :
[build]
link = ["blas", "lapack"]
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
Fonctionnalités Fortran¶
Permet d’activer et de désactiver des fonctions spécifiques du langage
Typage implicite¶
Permet d’indiquer si le typage implicite par défaut doit être utilisé. L’option par défaut est false.
[fortran]
implicit-typing = true # default: false
Interfaces externes implicites¶
Permet d’indiquer si les interfaces externes peuvent être déclarées implicitement. L’option par défaut est false.
[fortran]
implicit-external = true # default: false
Format de code source¶
Permet de spécifier le format de code source à utiliser pour tous les fichiers du projet. Les choix possibles sont "free" pour indiquer que tous les fichiers utilisent la forme libre, "fixed" pour indiquer que tous les fichiers utilisent la forme fixe, et "default" pour laisser le compilateur décider sur la base de sa propre heuristique. L’option par défaut est "free".
[fortran]
source-form = "fixed" # default: "free"
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 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 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 à partir d’un registre¶
Note
To enable the usage of a registry in fpm make sure you read the instructions in the registry section first.
Espace de noms¶
Les paquets obtenus à partir d’un registre (distant ou local) doivent spécifier un espace de noms, qui permet d’identifier et de différencier de manière unique les paquets ayant des noms identiques. L’espace de noms est déclaré dans le manifeste (fpm.toml).
[dependencies]
my-package.namespace = "my-namespace"
fpm est alors invité à télécharger la dernière version de « my-package », qui appartient à « my-namespace », depuis le registre.
Version du projet¶
Si vous souhaitez télécharger une version spécifique d’un paquet plutôt que la plus récente, vous pouvez spécifier la version (v) dans le manifeste.
[dependencies]
example-package.namespace = "example-namespace"
example-package.v = "1.0.0"
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 à l’emplacement du manifeste fpm.toml et utilisent / comme séparateur de chemin sur toutes les plateformes.
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"] }
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
Configuration du préprocesseur¶
Dans la section preprocess, vous pouvez spécifier un ou plusieurs préprocesseurs à utiliser dans votre projet fpm.
Spécifier le préprocesseur¶
La section preprocess permet de spécifier un ou plusieurs préprocesseurs. Par exemple, cpp peut être spécifié comme suit :
Exemple
[preprocess]
[preprocess.cpp]
Pour utiliser plusieurs préprocesseurs, par exemple cpp et fypp, spécifiez-les comme suit :
Exemple
[preprocess]
[preprocess.cpp]
[preprocess.fypp]
Vous pouvez également spécifier les suffixes des fichiers sources pour lesquels le préprocesseur doit être exécuté :
Exemple
[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]
En outre, vous pouvez demander au préprocesseur de s’exécuter sur des fichiers sources situés dans des répertoires spécifiques :
Exemple
[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]
Les macros du préprocesseur peuvent être définies comme suit :
Exemple
[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]
Nous pouvons également utiliser des sous-champs pour définir les paramètres de notre préprocesseur.
Exemple
[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]
Nous pouvons également définir des macros numérotés dans la table de prétraitement.
Exemple
[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]
Nous pouvons même réutiliser des valeurs comme le numéro de version défini dans le manifeste comme valeur pour une macro.
Exemple
version = "1"
[preprocess]
[preprocess.cpp]
macros=["VERSION={version}"]
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.
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.
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.
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.
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.