Referência do manifesto

O arquivo fpm.toml para cada projeto é chamado de seu manifest (manifesto). É escrito usando um formato de texto chamado TOML. Cada arquivo de manifesto é dividido nas seguintes seções:

  • name: O nome do projeto

  • version: A versão do projeto

  • license: A licença do projeto

  • maintainer: Mantenedor do projeto

  • author: Autor do projeto

  • copyright: Copyright do projeto

  • description: Descrição do projeto

  • categories: Categorias associadas com o projeto

  • keywords: Palavras-chave descrevendo o projeto

  • homepage: A página principal do projeto

  • Configuração de compilação:

    • auto-tests: Alterna a descoberta automática dos executáveis de teste

    • auto-examples: Alterna a descoberta automática de programas de exemplo

    • auto-executables: Alterna o reconhecimento automático de executáveis

    • link: Vínculo com dependências externas

    • external-modules: Define módulos usados que não usados de dentro do seu pacote fpm

  • Seção de alvos:

    • library Configuração da biblioteca alvo

    • executable Configuração de alvos executáveis

    • test Configuração dos alvos de teste

  • Seção de dependências:

    • dependencies: Dependências da biblioteca do projeto

    • dev-dependencies: Dependências necessárias apenas para os testes

  • install: Configuração da instalação

  • preprocess Preprocessor configuration

  • extra: Campo de dados adicional

Nome do projeto

O nome do projeto identifica o pacote e será usado ao se referir a ele. Será usado ao listá-lo como dependência por outro pacote e será, por padrão, o nome da biblioteca e de seu executável. Dessa forma, o nome do projeto deve sempre estar presente.

Exemplo:

name = "hello_world"

Versão do projeto

O número da versão do projeto é definido como uma string. Uma forma padronizada de gerenciar e definir versões é o esquema de Versionamento Semântico.

Exemplo:

version = "1.0.0"

O campo de versão poderá conter também um nome de arquivo, relativo a raiz do projeto, contendo o número da versão do projeto

Exemplo:

version = "VERSION"

Licença do projeto

O campo de licença do projeto contém um identificador da licença. Uma forma padronizada de definir a informação de licenciamento são os identificadores SPDX.

Exemplos:

Projetos licenciados sob a GNU Lesser General Public Licence, tanto a versão 3 quanto qualquer versão posterior, são definidos como

license = "LGPL-3.0-or-later"

Projetos de licença dupla sob Apache license, version 2.0 ou MIT license são definidos como

license = "Apache-2.0 OR MIT"

Mantenedor do projeto

Informação sobre o mantenedor do projeto e meios de contatá-lo.

Exemplo:

maintainer = "jane.doe@example.com"

Autor do projeto

Informação sobre o autor do projeto.

Exemplo:

author = "Jane Doe"

Descrição do projeto

A descrição fornece um pequeno resumo sobre o projeto. Deve conter apenas texto e não usar nenhum tipo de formatação.

Exemplo:

description = "A short summary on this project"

Categorias do projeto

O projeto pode ser associado com diferentes categorias.

Exemplo:

categories = ["io"]

Palavras-chave do projeto

O campo de palavras-chave é um array de strings que descreve o projeto.

Exemplo:

keywords = ["hdf5", "mpi"]

Página principal do projeto

URL da página web do projeto.

Exemplo:

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

Alvos do projeto

Cada projeto fpm pode definir bibliotecas, executáveis e testes. Bibliotecas são exportadas e podem ser usadas em outros projetos.

Configuração de biblioteca

Define a biblioteca-alvo a ser exportada pelo projeto. Uma biblioteca é gerada se o diretório do código-fonte ou diretório include é encontrado em um projeto. Os diretórios padrão para o código-fonte o os includes são src e include; estes podem ser modificadas na seção library usando o campo source-dir e include-dir. Os caminhos de arquivo são dados relativos a raiz do projeto e usam / como separador em todas as plataformas.

Exemplo:

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

Incluir diretório

Nota

Disponível apenas na versão Fortran do fpm

Projetos que usam o comando include do Fortran ou o comando #include do preprocessador da linguagem C, podem usar a chave include-dir para definir diretórios de busca para a inclusão dos arquivos. include-dir pode conter um ou mais diretórios, onde múltiplos diretórios são definidos usando uma lista de strings. Os diretórios incluídos por todas as dependências do projeto serão passadas ao compilador com a flag apropriada.

Exemplo:

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

Nota

include-dir atualmente não permite usar módulos .mod pré-compilados

Executáveis-alvo

Executáveis-alvo são programas em Fortran definidos nas seções executable. Se nenhuma seção desse tipo for definida o diretório app é vasculhado para encontrar definições de programas. Para executáveis definidos explicitamente o campo name precisa sempre estar definido O diretório do código-fonte para cada executável pode ser ajustado com o campo source-dir. Os caminhos são sempre dados relativos a raiz do projeto e usa / como separador em todas as plataformas. O código fonte contendo o corpo do programa pode ser definido no campo main.

Executáveis podem ter suas próprias dependências. Veja definindo dependências para mais detalhes.

Executáveis também podem definir suas próprias dependências em bibliotecas externas. Veja bibliotecas externas para mais detalhes.

Nota

Apenas a versão Fortran do fpm possui suporte ao vínculo com bibliotecas

Exemplo:

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

A definição de múltiplos executáveis separados pode ser feita através do uso de tabelas na mesma linha de forma curta

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

Exemplos-alvo

Aplicações de exemplo para um projeto são definidas so a seção example. Se nenhuma seção de exemplo for definida o diretório example será vasculhado para encontrar definições de programas. Para exemplos explicitamente definidos o campo name também deve estar definido. Os diretórios dos código-fonte dos exemplos pode ser ajustada no campo source-dir. Os caminhos são sempre relativos a raiz do projeto e usa / como separador em todas as plataformas. O código-fonte contendo o corpo do programa pode ser definido no campo main.

Exemplos podem ter suas próprias dependências. Veja definir dependências para mais detalhes.

Exemplos podem definir suas próprias dependências de bibliotecas externas. Veja bibliotecas externas para mais detalhes.

Nota

Apenas a versão Fortran do fpm possui suporte ao vínculo com bibliotecas

Exemplo:

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

Testes-alvo

Alvos de teste são programas Fortran definidos nas seções test. Eles seguem regras parecidas com as dos alvos executáveis. Se nenhuma seção de teste é especificada o diretório test é escaneado em busca de definições de programas. Para os testes explicitamente definidos o campo name precisa estar sempre definido. O diretório do código-fonte para cada teste pode ser ajustado com a opção source-dir. Caminhos para este diretório são dados a partir da raiz do projeto e usa / como separador em todas as plataformas. O arquivo que contém o corpo do programa pode ser especificado no campo main.

Testes podem ter suas próprias dependências. Veja definindo dependências para mais detalhes.

Testes podem também definir suas próprias dependências externas. Veja vínculo de bibliotecas externas para mais informações.

Nota

Apenas a versão Fortran do fpm possui suporte ao vínculo com bibliotecas

Exemplo:

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

Usar módulos instalados no sistema

Para usar módulos que não estão definidos dentro do seu pacote fpm ou de suas dependências, especifique o nome do módulo usando a chave external-module dentro da tabela build.

Importante

fpm não consegue localizar arquivos de módulos externos; Sendo responsabilidade do usuário especificar os diretórios que precisam ser incluídos usando flags do compilador de forma que este possa localizar módulos externos durante a compilação.

Exemplo:

[build]
external-modules = "netcdf"

Múltiplos módulos externos podem ser especificados como uma lista.

Exemplo:

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

Localização automática de alvos

Nota

Disponível apenas na versão Fortran do fpm

Executáveis e testes podem ser detectados automaticamente nos seus diretórios padrão. A descoberta automática recursivamente procura por definições program nos diretórios app, example e test, declarando-os como executável, exemplo e alvo de teste, respectivamente. A descoberta automática é habilitada por padrão.

Para desabilitar a descoberta automática de alvos coloque as entradas auto-executables, auto-examples e auto-tests como false.

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

Definição de dependências

Dependências podem ser declaradas na tabela dependencies na raiz do manifesto, ou nas seções executable ou test. Quando declaradas na raiz as dependências serão exportadas com o projeto.

Dependências locais

Para declarar dependências locais use a entrada path.

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

Dependências a partir de sistemas de controle de versão

Dependências podem ser especificadas a partir de repositórios git.

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

Para usar um ramo upstream específico declare o nome branch usando

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

Alternativamente, referencie tags usando a entrada tag

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

Para fixar uma versão específica, identifique o hash do commit na entrada rev

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

Para um leiaute mais verboso use tabelas normais em vez de tabelas em linha, ao especificar dependências

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

Dependências de desenvolvimento

São permitidas as dependências de desenvolvimento declarar dev-dependencies na raiz do manifesto, que estão disponíveis para todos os testes porém não são exportadas com o projeto.

Configuração da instalação

Na seção install os componentes para a instalação podem ser selecionados. Por padrão, apenas executáveis são instalados, projetos do tipo biblioteca podem definir o booleano library para também instalar os arquivos de módulo e o archive.

Exemplo

[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 :

Exemplo

[preprocess]
[preprocess.cpp]

To use multiple preprocessors, for example cpp and fypp, specify them like this:

Exemplo

[preprocess]
[preprocess.cpp]
[preprocess.fypp]

You can also specify source file suffixes that the preprocessor should run on:

Exemplo

[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]

Further, you can instruct the preprocessor to run on source files in specific directories:

Exemplo

[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]

Preprocessor macros can be defined like this:

Exemplo

[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]

We can also use dotted keys to define our preprocessor settings.

Exemplo

[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]

We can also define valued macros in preprocess table.

Exemplo

[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]

We can also reuse values like version number from manifest as a value for a macro.

Exemplo

version = "1"

[preprocess]
[preprocess.cpp]
macros=["VERSION={version}"]

Campo de dados adicionais

Ferramentas de terceiros podem guardar suas configurações dentro da seção extra. Esta seção nunca será processada pelo fpm, portanto a única coisa imposta é que ela seja escrita em TOML.

Já que o formato da seção extra é livre, apenas sugestões para adicionar dados a ela serão dadas aqui.

  1. Use apenas sub-tabelas, nunca adicione configurações no nível superior da seção extra. Motivo: diferentes ferramentas podem evitar colisões de nome colocando seus dados em tabelas separadas.

  2. Use um nome concreto para a ferramenta em vez de um nome genérico para a sub-tabela. Motivo: um formatador diferente ou ferramentas de linter podem usar palavras-chave conflitantes em um tabela chamada format ou lint. Além disso, usuários podem ficar sabendo a partir do nome da tabela qual ferramenta que prefere para usar no projeto.

  3. Os plugins fpm devem usar uma tabela com o nome do plugin sob a seção extra.fpm para armazenar seus dados. Motivo: seguir esta convenção fornece ao seus usuários uma seção para configuração dos seus plugins.

  4. Use o estilo preferido no fpm para as palavras-chave, que é caixa baixa com traços. Motivo: mesmo que não seja feita uma checagem de estilo desta seção, um estilo consistente em todo o seu manifesto fará com que seja mais fácil para o usuário entendê-lo como um todo.

Comentários sobre as recomendações acima são mais que bem-vindos. Se você possui uma ferramenta que usa a seção extra do manifesto, sinta-se à vontade para postar no mural de discussões do fpm.