Referentie voor manifestbestanden
Inhoud
Referentie voor manifestbestanden¶
Het fpm.toml bestand voor elk project wordt het manifestbestand genoemd. Het staat in het [TOML] format. Ieder manifestbestand bevat de volgende secties:
name: De naam van het project
version: De versie van het project
license: De licentie voor het project
maintainer: De beheerder van het project
author: De auteur van het project
copyright: Copyright voor het project
description: De omschrijving van het project
categories: Categorieën, waaronder het project valt
keywords: Sleutelwoorden waarmee het project wordt gekenmerkt
homepage: De homepage van het project
Build-configuratie:
auto-tests: Automatische herkenning van testprogramma’s
auto-examples: Automatische herkenning van voorbeeldprogramma’s
auto-executables: Schakel automatische herkenning van programma’s aan/uit
link: Link met externe afhankelijkheden
external-modules: Modules, die niet binnen het fpm pakket zelf gedefinieerd worden
Fortran configuration:
implicit-typing: Toggle default implicit typing
implicit-external: Toggle implicit external interfaces
source-form: Select source form for project
Target-secties:
library Configuratie van de bibliotheek-targets
executable Configuratie van de targets voor executables
test Configuratie van de test-targets
Secties voor afhankelijkheden:
dependencies: Bibliotheken gebruikt in het project
dev-dependencies: Afhankelijkheden die alleen nodig zijn voor de testen
install: Installatieconfiguratie
preprocess Preprocessor configuration
extra: Veld voor aanvullende gegevens
Projectnaam¶
De projectnaam geeft het pakket aan en wordt gebruikt, om eraan te refereren. Het wordt ook gebruikt als afhankelijkheid bij andere projecten en als standardnaam voor de targets voor de bibliotheek en de executable. Daarom moet er altijd een projectnaam zijn.
Voorbeeld:
name = "hello_world"
Projectversie¶
Het versienummer van het project wordt als een string behandeld. Een standaardmethode om versies aan te geven is het zogeheten [Semantic Versioning] schema.
Voorbeeld:
version = "1.0.0"
Het veld voor het versienummer kan ook een bestandsnaam zijn relatief t.o.v. de hoofddirectory van het project. Dit bestand bevat dan het versienummer.
Voorbeeld:
version = "VERSION"
Licentie voor het project¶
Het veld license geeft aan welke licentie er voor het project geldt. Een standaardmethode is de [SPDX] Identicatie.
Voorbeelden:
Projecten, die onder de [GNU Lesser General Public License] (https://www.gnu.org/licenses/lgpl-3.0-standalone.html), versie 3 of elke latere versie vallen, worden aangegeven als
license = "LGPL-3.0-or-later"
Projecten, die onder de Apache-licentie, versie 2.0 of de MIT-licentie vallen, worden aangegeven als
license = "Apache-2.0 OR MIT"
Projectbeheerder¶
Informatie over de projectbeheerder en de mogelijkheden tot contact.
Voorbeeld:
maintainer = "jane.doe@example.com"
Copyright voor het project¶
Verklaring van de copyrightstatus van het project.
Voorbeeld:
copyright = "Copyright 2020 Jane Doe"
Projectbeschrijving¶
De beschrijving hoort een korte samenvatting van het project te zijn zonder enige opmaakcodes.
Voorbeeld:
description = "A short summary on this project"
Projectcategorieën¶
Het project kan onder meerdere categorieën vallen.
Voorbeeld:
categories = ["io"]
Projectsleutelwoorden¶
Het veld voor sleutelwoorden bevat een of meer strings die het project beschrijven.
Voorbeeld:
keywords = ["hdf5", "mpi"]
Homepage van het project¶
URL voor de website van het project.
Voorbeeld:
homepage = "https://stdlib.fortran-lang.org"
Doelstellingen van het project¶
Elk fpm-project kan bibliotheken, executables en testen definiëren. Bibliotheken worden geëxporteerd voor gebruik in andere projecten.
Configuratie voor bibliotheken¶
Definieer de target voor de te exporteren bibliotheek. Een bibliotheek wordt gegenereerd, als de brondirectory of de include-directory in het project aangetroffen wordt. De standaardnamen hiervoor zijn src und include; deze namen kunnen in de library-sectie in het manifestbestand met de entries source-dir en include-dir aangepast worden. Paden voor deze directories zijn altijd relatief to.v. de hoofddirectory van het project en bevatten / als padscheiding voor alle plattforms.
Voorbeeld:
[library]
source-dir = "lib"
include-dir = "inc"
Includedirectory¶
Notitie
Alleen in Fortran fpm ondersteund
Projecten, die het Fortran include-statement of het #include statement van de C-preprocessor gebruiken, kunnen via het sleutelwoord include-dir aangeven welke directories de mee te nemen bronbestanden bevatten. include-dir bestaat uit een of meer directorynamen als een lijst van strings. De include-directories van alle project-afhankelijkheden worden aan de compiler door middel van de juiste opties doorgegeven.
Voorbeeld:
[library]
include-dir = ["include", "third_party/include"]
Notitie
Op dit moment kan include-dir niet gebruikt worden voor voorgecompileerde modules files .mod
Targets voor executables¶
Targets die uitvoerbare programma’s definiëren staan in de secties executable. Als er geen executable secties zijn gegeven, wordt in plaats daarvan de directory app onderzocht. Voor expliciet aangegeven executables moet altijd de name-entry opgegeven worden. De brondirectory voor elek executable kan in de entry source-dir aangepast worden. Paden voor de source-directory zijn relatief t.o.v. de hoofddirectory van het projecten en gebruiken/ als padscheiding op alle plattforms. Het bronbestanden met het hoofdprogramma is aan te geven met de entry main.
Executables kunnen elk hun eigen afhankelijkheden hebben. Zie specificeren van afhankelijkheden voor meer details.
Executables kunnen afzonderlijk afhangen van specifieke bibliotheken. Zie externe bibliotheken voor verdere details.
Notitie
Linking met bibliotheken wordt binnen fpm alleen voor Fortran ondersteund
Voorbeeld:
[[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" }
Als je veel aparte executables hebt, kun je deze specificeren via inline-tabellen.
executable = [
{ name = "a-prog" },
{ name = "app-tool", source-dir = "tool" },
]
Voorbeeld-targets¶
Vorobeeldprogramma’s voor een project worden gedefinieerd via example-secties. Als er geen sectie example opgegeven is, wordt de directory example onderzocht voor definities van programma’s. Voor expliciet opgegeven voorbeelden is altijd de name-entry nodig. De brondirectory voor elk voorbeeld kan in de source-dir-entry aangepast worden. Paden voor de brondirectory zijn relatief t.o.v. de hoofddirectory van het project en gebruiken / als padscheiding op alle plattforms. Het bronbestand met het hoofdprogramma kan in de main-entry aangegeven worden.
Voorbeeldprogramma’s kunnen hun eigen afhankelijkheden hebben. Zie specificeren van afhankelijkheden voor meer details.
Voorbeeldprogramma’s kunnen afzonderlijk van externe bibliotheken afhangen. Zie externe bibliotheken voor verdere details.
Notitie
Linking met bibliotheken wordt binnen fpm alleen voor Fortran ondersteund
Voorbeeld:
[[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" }
Targets voor testen¶
Testprogramma’s in Fortran worden gedefinieerd in test-secties. Er gelden soortgelijke regels als voor alle executables. Als er geen sectie is opgegeven, wordt de directory test doorzocht voor programmadefinities. Voor expliciet opgegeven tests moet altijd de name-entry opgegeven worden. De brondirectory voor elke test kan in de source-dir-entry aangepast worden. Paden voor de brondirectory zijn relatief t.o.v. de hoofddirectory van het project en gebruiken / als padscheiding op alle plattforms. Het bronbestand met het hoofdprogramma kan in de main-entry aangegeven worden.
Testprogramma’s kunnen hun eigen afhankelijkheden hebben. Zie specificeren van afhankelijkheden voor meer details.
Testprogramma’s kunnen afzonderlijk van externe bibliotheken afhangen. Zie externe bibliotheken “voor verdere details.
Notitie
Linking met bibliotheken wordt binnen fpm alleen voor Fortran ondersteund
Voorbeeld:
[[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" }
Linken met externe bibliotheken¶
Notitie
Alleen in Fortran fpm ondersteund
Om de afhankelijkheid van externe bibliotheken te specificeren, wordt een lijst van de betreffende bibliotheken in de link-entry opgegeven. Geef de naam van de bibliotheek of biblotheken op als een string of een lijst van strings. Indien mogelijk moet het project daarvoor een systeemspecifieke bibliotheek gebruiken. De lijst van dergelijke afhankelijkheden wordt doorgegeven aan pakketten die van dit pakket afhangen.
Voorbeeld:
Linken met de zlib-compressiebibllotheek, kan als volgt:
[build]
link = "z"
Om LAPACK te gebruiken, moet ook BLAS meegelinkt worden. In dit geval is de volgorde van de bibliotheken van belang:
[build]
link = ["blas", "lapack"]
Modules die op het systeem zijn geïnstalleerd¶
Om modules te gebruiken die niet in een fpm-pakket of via afhankelijkheden gedefinieerd zijn, moeten ze in een build-tabellenentry onder external-modules opgegeven worden.
Belangrijk
fpm kan niet automatisch externe modulebestanden vinden; het is de verantwoordelijkheid van de gebruiker om de benodigde include-directories met compileropties aan te geven, zodat de compiler deze externe modulebestanden kan vinden.
Voorbeeld:
[build]
external-modules = "netcdf"
Meerdere externe modules kunnen aangegeven worden via een lijst.
Voorbeeld:
[build]
external-modules = ["netcdf", "h5lt"]
Automatische bepaling targets¶
Notitie
Alleen in Fortran fpm ondersteund
Executables en testprogramma’s kunnen automatisch in de standaarddirectories gevonden worden. De automatische procedure hiervoor doorzoekt recursief de app-, example- und test-directories naar program-definities en merken deze aan als respectievelijk executable-, voorbeeld- en test-targets. De automatische zoekprocedure wordt standaard aangezet.
Om de automatische bepaling van targets uit te schakelen, zet je de entries auto-executables, auto-examples, en auto-tests op 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"
Afhankelijkheden specificeren¶
Afhankelijkheden kunnen in de dependencies-tabel in de hoofdentry van het manifestbestand of in de secties executable of test aangegeven worden. Als ze in de hoofdentry worden aangegeven, worden ze met het project geëxporteerd.
Afhankelijkheden van versiebeheersystemen¶
Afhankelijkheden kunnen via een Git-repository van het project aangegeven worden.
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f" }
Om een bepaalde branch van de upstream repository aan te geven, moet de branch-naam gespecificeerd werden.
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", branch = "main" }
Als alternatief kunnen referentie-tags via een entry tag gebruikt worden.
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", tag = "v0.2.1" }
Om een bepaalde revisie vast te leggen, moet de hash van de betreffende commit in een rev-entry aangegeven worden.
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", rev = "2f5eaba" }
Voor een uitgebreide layout kunnen normale tabellen gebruikt worden in plaats van inline-tabellen om afhankelijkheden te specificeren.”
[dependencies]
[dependencies.toml-f]
git = "https://github.com/toml-f/toml-f"
rev = "2f5eaba864ff630ba0c3791126a3f811b6e437f3"
Dependencies from a registry¶
Notitie
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 afhankelijkheden¶
Om lokale afhankelijkheden aan te geven, moet dr path-entry gebruikt worden.
[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"] }
Afhankelijkheden voor ontwikkeling¶
Afhankelijkheden die een rol spelen bij de ontwikkeling zijn aan te geven via de entry dev-dependencies in de hoofdentry van het manifest. Ze zijn beschikbaar voor alle testen, maar worden niet geëxporteerd.
Installatieconfiguratie¶
In de install-sectie kunnen componenten voor de installatie geselecteerd worden. Standaard worden alleen de executables geïnstalleerd. Bij bibliotheekprojecten kan het library-kenmerk op true gezet worden, om de bibliotheek en de modulebestanden ook te installeren.
Voorbeeld
[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 :
Voorbeeld
[preprocess]
[preprocess.cpp]
To use multiple preprocessors, for example cpp and fypp, specify them like this:
Voorbeeld
[preprocess]
[preprocess.cpp]
[preprocess.fypp]
You can also specify source file suffixes that the preprocessor should run on:
Voorbeeld
[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]
Further, you can instruct the preprocessor to run on source files in specific directories:
Voorbeeld
[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]
Preprocessor macros can be defined like this:
Voorbeeld
[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]
We can also use dotted keys to define our preprocessor settings.
Voorbeeld
[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]
We can also define valued macros in preprocess table.
Voorbeeld
[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]
We can also reuse values like version number from manifest as a value for a macro.
Voorbeeld
version = "1"
[preprocess]
[preprocess.cpp]
macros=["VERSION={version}"]
Veld voor aanvullende gegevens¶
Externe tools kunnen configuratiegegevens in de sectie extra opslaan. Deze sectie wordt door fpm nooit geëvalueerd. De enige voorwaarde is dat het voldoet aan het TOML-format.
Aangezien het format van deze sectie verder vrij is, worden hier enkele aanbevelingen gegeven.
Gebruik alleen deeltabellen, nooit configuratiegegevens op het hoogste niveau binnen de sectie extra. De reden: veschillende tools kunnen dan conflicten met de sleutelwoorden vermijden, doordat ze verschillende deeltabellen gebruiken.
Gebruik steeds de concrete naam van het tool in plaats van een generieke naam voor de deeltabellen. De reden: verschillende formatterings- of opschoon-tools kunnen in een deeltabel format- of lint conflicterende sleutelwoorden gebruiken. Gebruikers kunnen ook met de tabelnaam kiezen voor de juiste tool voor het project.
Fpm-plugins moeten een deeltabel met de pluginnaam in de sectie extra.fpm opslaan. Reden: met deze conventie kan de gebruiker van fpm-plugins met een enkele sectie de te gebruiken plugins configureren.
Gebruik bij voorkeur de fpm-stijl voor sleutelwoorden, kleine letters en streepjes om onderdelen te scheiden. Reden: er vindt weliswaar geen controle plaats in deze sectie, maar een consistente stijl in het hele manifestbestand maakt het gemakkelijker voor de gebruiker om de inhoud te begrijpen.
Terugmeldungen en suggesties voor de genoemde aanbevelingen zijn van harte welkom. Dit geldt zeker voor tools die via de sectie extra in het manifestbestand geconfigureerd kunnen worden. Meld dit in het fpm discussieforum.