Referência do manifesto
Conteúdo
Referência do manifesto¶
O ficheiro fpm.toml para cada projeto é chamado de seu manifest (manifesto). É escrito usando um formato de texto chamado TOML. Cada ficheiro 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
Fortran configuration:
implicit-typing: Toggle default implicit typing
implicit-external: Toggle implicit external interfaces
source-form: Select source form for project
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 Configuração do pré-processador
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 cadeia. Uma forma padronizada de gerir 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 ficheiro, 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"
Copyright do projeto¶
Uma declaração que especifique o status de copyright do projeto.
Exemplo:
copyright = "Copyright 2020 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 cadeias 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 ficheiros. include-dir pode conter um ou mais diretórios, onde múltiplos diretórios são definidos usando uma lista de cadeias. 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 ficheiro 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" }
Vincular bibliotecas externas¶
Nota
Disponível apenas na versão Fortran do fpm
Para declarar dependências externas em tempo de vinculação, uma lista de bibliotecas nativas pode ser definidas no campo link. Defina uma biblioteca como uma cadeia ou uma lista de cadeias no caso em que várias bibliotecas precisam ser vinculadas. Quando possível, o projeto deve vincular apenas uma biblioteca nativa. A lista de dependências da biblioteca é exportada aos pacotes dependentes.
Exemplo:
Para vincular com a biblioteca de compressão zlib use
[build]
link = "z"
Para depender do LAPACK, o BLAS deve estar vinculado. Neste caso, a ordem das bibliotecas importa:
[build]
link = ["blas", "lapack"]
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 ficheiros 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
Recursos do Fortran¶
Allows to enable and disable specific language features
Tipagem Implícita¶
Allows to toggle whether the default implicit typing should be used.
The default option is false.
[fortran]
implicit-typing = true # default: false
Funções Externas Implícitas¶
Allows to toggle whether external interfaces can be declared implicitly.
The default option is false.
[fortran]
implicit-external = true # default: false
Formatação do Código-Fonte¶
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"
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 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"
Dependencies from a registry¶
Nota
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.
Versão¶
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"
Dependências locais¶
Para declarar dependências locais use a entrada path.
[dependencies]
my-utils = { path = "utils" }
Os caminhos para dependências locais são dados relativos à localização do arquivo fpm.toml e usam / como separador de caminho em todas as plataformas.
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"] }
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
Configuração de pré-processamento¶
Sob a seção preprocess, você pode especificar um ou mais pré-processadores para usá-lo em um projeto fpm.
Definição do pré-processador¶
A seção preprocess permite usar um ou mais pré-processadores. Por exemplo, o pré-processador cpp pode ser definido como:
Exemplo
[preprocess]
[preprocess.cpp]
Para usar mais de um pré-processador, por exemplo, o cpp e o fypp, defina-os como:
Exemplo
[preprocess]
[preprocess.cpp]
[preprocess.fypp]
Você também pode definir sufixos de código-fonte aos quais o pré-processador deve processar:
Exemplo
[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]
Além disso, você pode instruir o pré-processador para processar código-fonte a partir de diretórios específicos:
Exemplo
[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]
As macros do pré-processador podem ser definidas como:
Exemplo
[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]
Também é possível definir as configurações do nosso pré-processador acessando as chaves usando o ponto.
Exemplo
[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]
Também é possível definir macros com seus valores em uma tabela de pré-processamento.
Exemplo
[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]
Além disso, é possível reutilizar valores como o número de versão a partir do manifesto como um valor para a sua 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.
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.
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.
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.
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.