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:

  • Target-secties:

    • library Configuratie van de bibliotheek-targets

    • executable Configuratie van de targets voor executables

    • test Configuratie van de test-targets

  • Secties voor afhankelijkheden:

  • 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"

Auteur van het project

Informatie over de auteur.

Voorbeeld:

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

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.

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

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

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

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