Manifiesto de la referencia
Contenido
Manifiesto de la referencia¶
El archivo fpm.toml para cada proyecto es denominado manifiesto. Este es escrito usando el formato [TOML]. Cada archivo del manifiesto consiste de las siguientes secciones:
name: Nombre del proyecto
version: Versión del proyecto
license: Licencia del proyecto
maintainer: Encargado del proyecto
author: Autor del proyecto
copyright: Derechos de autor del proyecto
description: Descripcción del proyecto
categories: Categorias asociadas con el proyecto
keywords: palabras clave
homepage: Página web del proyecto
Configuración:
auto-tests: Reconocimiento automático de ejecutables de prueba
auto-examples: Reconocimiento automático de programas de ejemplo
auto-executables: Reconocimiento automático de ejecutables
link: Enlace con dependencias externas
external-modules: Especificar los módulos que no están en su paquete de fpm
Fortran configuration:
implicit-typing: Toggle default implicit typing
implicit-external: Toggle implicit external interfaces
source-form: Select source form for project
Secciones de destino:
library Configuración de la biblioteca objetivo
executable Configuración del ejecutable
test Configración de pruebas
Sección de dependencias:
dependencies: Dependencias de la biblioteca del proyecto
dev-dependencies: Dependencias necesarias solo para pruebas
install: Configuración de la instalación
preprocess Configuración del preprocesador
extra: Campo adicional de datos libre
Nombre del proyecto¶
El nombre del proyecto identifica el paquete y es usado para referirse a este. Es usado cuando se enumera el proyecto como dependencia de otro paquete y el nombre predeterminado de la biblioteca y ejecutable objetivo. Además, el nombre del proyecto siempre debe estar presente.
Ejemplo:
name = "hello_world"
Versión del proyecto¶
El número de la versión es dado como una cadena de caracteres. Una forma estándar para manejar y especificar versiones es el esquema [Semantic Versioning].
Ejemplo:
version = "1.0.0"
La entrada de versiones puede contener un nombre de archivo relativo al proyecto principal, que contiene el número de versión del proyecto
Ejemplo:
version = "VERSION"
Licencia del proyecto¶
El campo de licencia del proyecto contiene el identificador de licencia. Una forma estandarizada para especificar la información de la licencia es con los indentificadores [SPDX].
Ejemplos:
Proyectos aprobados baja la licencia GNU Lesser General Public License, cualquier version 3 o posterior son especificados como
license = "LGPL-3.0-or-later"
Proyectos aprobados bajo la doble licencia Apache license, version 2.0 or la MIT license son especificados como
license = "Apache-2.0 OR MIT"
Encargado del proyecto¶
Información sobre el encargado del proyecto y forma para comunicarse con este.
Ejemplo:
maintainer = "jane.doe@example.com"
Derechos de autor del proyecto¶
Una declaración que especifique el estatus de la autoria del proyecto.
Ejemplo:
copyright = "Copyright 2020 Jane Doe"
Descripción del proyecto¶
La descripción brinda un resumen sobre el proyecto. Este debe ser texto plano y no usar marcas de formatación.
Ejemplo:
description = "A short summary on this project"
Categorias del proyecto¶
El proyecto puede estar asociado con diversas categorias.
Ejemplo:
categories = ["io"]
Palabras clave¶
El campo palabras clave es un arreglo de cadenas de caracteres que describen el proyecto.
Ejemplo:
keywords = ["hdf5", "mpi"]
Página web del proyecto¶
URL de la página web del proyecto.
Ejemplo:
homepage = "https://stdlib.fortran-lang.org"
Objetivos del proyecto¶
Cada proyecto puede definir una biblioteca, un ejecutable y pruebas objetivosLas bibliotecas objetivo se exportan y pueden ser usadas por otros proyectos.
Configuración de bibliotecas¶
Define las bibliotecas objetivo exportadas del proyecto. Una biblioteca es generada si el directorio de origen o el directorio incluir es encontrado en un proyecto. Los directorios de origen e incluir predeterminados son src y include; estos pueden ser modificados en la sección library usando las entradas source-dir y include-dir. Rutas para los directorios fuente e incluir son dados relativos al proyecto raiz y usa / como separador de rutas sobre todas las plataformas.
Ejemplo:
[library]
source-dir = "lib"
include-dir = "inc"
Directorio incluir¶
Nota
Compatible solo en Fortran fpm
Proyectos que usan la instrucción include o la instrucción de preprocesamiento #include, pueden usar la clave include-dir para especificar la busqueda en directorios de los archivos incluidos. include-dir puede contener uno o mas directorios, donde múltiples directorios son especificados usando una lista de cadenas de caracteres. Directorios incluir de todos los proyectos son pasados al compilador usando la opción de compilación apropiada.
Ejemplo:
[library]
include-dir = ["include", "third_party/include"]
Nota
include-dir actualmente no permite usar archivos .mod del módulo predefinido
Ejecutables objetivo¶
Ejecutables objetivo son programas en Fortran definidos como secciones executable. Si ninguna sección ejecutable es especificada, el directorio app es buscado desde las definiciones del programa. Para especificar explicitamente los ejecutables la entrada name debe ser siempre dada. Las rutas para el directorio fuente son dados relativos al proyecto raiz y usan / como separador de rutas en todas las plataformas. El archivo fuente conteniendo el cuerpo del programa puede ser especificado en la entrada main.
Ejecutables pueden tener sus propias depedencias. Ver especificar dependencias para mas detalles.
Ejecutables también pueden especificar su propias depedencias externas de biblioteca. Ver bibliotecas externas para mas detalles.
Nota
El vínculo con bibliotecas solo es soportado en Fortran fpm
Ejemplo:
[[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" }
Por brevedad, se puede especificar muchos ejecutables separados usando tablas en línea
executable = [
{ name = "a-prog" },
{ name = "app-tool", source-dir = "tool" },
]
Ejemplos objetivo¶
Programas de ejemplo para un proyecto son definidos como secciones example. Sininguna sección ejemplo es especificada, el directorio example es buscado en las definiciones del programa. Para especficar ejemplos explicitamente la entrada name debe siempre ser dada. El directorio fuente para cada ejemplo puede ser ajustado en la entrada source-dir. Rutas para el directorio fuente son dadas relativas al proyecto raiz y usan / como separador en todas las plataformas. El archivo fuente continiendo el cuerpo del programa puede ser especificado en la entrada main.
Programas ejemplo pueden tener sus propias dependencias. Ver especificar dependencies para mas detalles.
Programas ejemplos tambien pueden especificar sus propias dependencias de biblioteca. Ver bibliotecas externas para mas detalles.
Nota
El vínculo con bibliotecas solo es soportado en Fortran fpm
Ejemplo:
[[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" }
Pruebas objetivo¶
Las pruebas objetivo son programas Fortran definidos como secciones test. Estos siguen reglas similarees a los ejecutables objetivo. Si ninguna sección prueba es especificada, el directorio test es buscado en las definiciones del programa. Para especificar explicitamente las pruebas, la entrada name debe ser siempre dada. El directorio fuente para prueba puede ser definido en la entrada source-dir. Rutas para el directorio fuente son dadas relativas al proyecto raiz y usan / como separador de ruta en todas las plataformas. El archivo fuente conteniendo el cuerpo del programa puede ser especificado en la entrada main.
Programas de prueba tienen sus propias dependencias. Ver specifying dependencies para mas detalles.
Programas de prueba también pueden especificar sus propias dependencias externas de biblioteca. Ver bibliotecas externas para mas detalles.
Nota
El vínculo con bibliotecas solo es soportado en Fortran fpm
Ejemplo:
[[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
Compatible solo en Fortran fpm
Para declarar dependencias de tiempo de enlace en bibliotecas externas, una lista de las bibliotecas se pueden especificar en la entrada link. Especifique una biblioteca como cadena o una lista de cadenas en caso que varias bibliotecas deban estar vinculado. Cuando sea posible, el proyecto solo debe vincular una biblioteca nativa. La lista de dependencias de la biblioteca se exporta a paquetes dependientes.
Ejemplo:
Para vincular con la biblioteca de compresión zlib use
[build]
link = "z"
Para depender de LAPACK también BLAS debe estar vinculado. En este caso la orden de las bibliotecas importa:
[build]
link = ["blas", "lapack"]
Usar módulos instalados en el sistema¶
Para usar módulos que no están definidos con su paquete fpm o sus dependencias, espeficique el nombre del módulo usando la clave external-module en la table de construcción.
Importante
fpm no puede localizar automáticamente archivos de módulos externos; es responsabilidad del usuario especificar los directorios de inclusión necesarios utilizando indicadores del compilador de modo que este pueda localizar archivos de módulos externos durante la compilación.
Ejemplo:
[build]
external-modules = "netcdf"
Se pueden especificar varios módulos externos como una lista.
Ejemplo:
[build]
external-modules = ["netcdf", "h5lt"]
Localización automática de objetivos¶
Nota
Compatible solo en Fortran fpm
Los ejecutables y las pruebas se pueden localizar automáticamente en sus directorios predeterminados. La localización automático busca de forma recursiva los directorios app, example y test para las definiciones de program y los declara como objetivos ejecutables, ejemplo y de prueba, respectivamente. La localización automática está habilitado de forma predeterminada.
Para deshabilitar la localización automática de objetivos, configure las entradas auto-executables, auto-examples, y auto-tests en 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"
Especificando dependencias¶
Las dependencias se pueden declarar en la tabla dependencies en el manifiesto raiz o en las secciones executable o test. Cuando se declara en el manifiesto raiz, las dependencias se exportan con el proyecto.
Dependencias de los sistemas de control de versiones¶
Las dependencias pueden ser especificadas por el repositorio git de proyectos.
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f" }
Para usar una rama ascendente específica, declare el nombre de la branch con
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", branch = "main" }
Alternativamente, haga referencia a las etiquetas mediante la entrada tag
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", tag = "v0.2.1" }
Para anclar una revisión específica, brinde el hash de confirmación en la entrada rev
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", rev = "2f5eaba" }
Para un diseño más detallado, use tablas normales en lugar de tablas en línea para especificar las dependencias
[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.
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"
Dependencias locales¶
Para declarar dependencias locales, utilice la entrada path.
[dependencies]
my-utils = { path = "utils" }
La ruta de dependencia local se proporciona en relación con fpm.toml en el que se escribe, y utiliza / como separador de ruta en todas las 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"] }
Dependencias de desarrollo¶
Las dependencias de desarrollo permiten declarar dev-dependencies en manifiesto de la raiz, que están disponibles para todas las pruebas pero no se exportan con el proyecto.
Cofiguración de instalación¶
En la sección install se pueden seleccionar los componentes para la instalación. De forma predeterminada, solo se instalan los ejecutables, los proyectos de biblioteca pueden configurar el booleano library para instalar también los archivos del módulo y el archivo.
Ejemplo
[install]
library = true
Configuración del preprocesador¶
En la sección preprocesamiento, puede especificar uno o más preprocesadores para usar en un proyecto fpm.
Especificación del preprocesador¶
La sección preprocess permite especificar uno o más preprocesadores. Por ejemplo, cpp se puede especificar así:
Ejemplo
[preprocess]
[preprocess.cpp]
Para usar múltiples preprocesadores, por ejemplo cpp y fypp, especifíquelos así:
Ejemplo
[preprocess]
[preprocess.cpp]
[preprocess.fypp]
También puede especificar los sufijos del archivo de origen en los que debe ejecutarse el preprocesador:
Ejemplo
[preprocess]
[preprocess.cpp]
suffixes = ["F90", "f90"]
Además, puede indicar al preprocesador que se ejecute en archivos de origen en directorios específicos:
Ejemplo
[preprocess]
[preprocess.cpp]
directories = ["src/feature1", "src/models"]
Las macros del preprocesador se pueden definir así:
Ejemplo
[preprocess]
[preprocess.cpp]
macros = ["FOO", "BAR"]
También podemos usar teclas de puntos para definir la configuración de nuestro preprocesador.
Ejemplo
[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.directories = ["src/feature1", "src/models"]
cpp.macros = ["FOO", "BAR"]
También podemos definir macros valiosas en la tabla de preprocesamiento.
Ejemplo
[preprocess]
[preprocess.cpp]
macros=["FOO=2", "BAR=4"]
También podemos reutilizar valores como el número de versión del manifiesto como valor para una macro.
Ejemplo
version = "1"
[preprocess]
[preprocess.cpp]
macros=["VERSION={version}"]
Campo de datos libre adicional¶
Las herramientas de terceros pueden almacenar su configuración dentro de la sección extra. Esta sección nunca será evaluada por el propio fpm, la única restricción impuesta es que tiene que ser un TOML válido.
Dado que el formato de esta sección es libre, aquí solo se proporcionan recomendaciones para agregar datos a la sección extra.
Use unicamente subtablas, nunca adicione datos de configuración al nivel superior de la sección extra. Razonamiento: diversas herramientas pueden evitar colisiones de nombres clave poniendo sus datos en subtablas separadas.
Use el nombre concreto de la herramienta mas que el nombre genérico para la subtabla. Razonamiento: diversas herramientas de formatación, o herramientas Linter, pueden usar palabras clave en conflicto en una subtable format o lint. Además, los usuarios pueden saber desde el nombre de la tabla la herramienta que prefieren usar con el proyecto.
Los complementos del fpm deben contener una subtabla con el nombre del complemento en la sección extra.fpm para almacenar sus datos. Razonamiento: esta convención brinda al usuario complementos de fpm con una sección para configurar sus complementos usados.
Use el estilo preferido de fpm para palabras clave que están en minúsculas con guiones. Razonamiento: si bien no existe verificación de estilo en esta sección, un estilo consistente en todo el manifiesto facilitará al usuario entender la totalidad del manifiesto del paquete.
Comentarios sobre las recomendaciones anteriores son bienvenidos. Si tiene una herramienta que usa la sección extra en el manifiesto del paquete, sientase libre de publicarlo en fpm discussion board.