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

  • Secciones de destino:

    • library Configuración de la biblioteca objetivo

    • executable Configuración del ejecutable

    • test Configración de pruebas

  • Sección de dependencias:

  • install: Configuración de la instalación

  • 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] (https://www.gnu.org/license/lgpl-3.0-standalone.html), 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] (http://www.apache.org/license/LICENSE-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"

Autor del proyecto

Información sobre el autor del proyecto

Ejemplo:

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

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

Especificando dependencias

Las dependencias se pueden declarar en la tabla dependencies en el manifiesto raiz o en las secciones executable o [test] (#test-targets). Cuando se declara en el manifiesto raiz, las dependencias se exportan con el proyecto.

Dependencias locales

Para declarar dependencias locales, utilice la entrada path.

[dependencies]
my-utils = { path = "utils" }

Las rutas de dependencia locales se dan en relación con la raíz del proyecto y utilizan / como separador de rutas en todas las plataformas.

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"

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

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.

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

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

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

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