El manifiesto
Todas las claves que lee Project.toml, qué emiten en la línea de comandos y los límites que se niega a sobrepasar.
Un único Project.toml vive en la raíz del proyecto. Todos los comandos lo buscan subiendo desde
el directorio actual, así que molto build funciona desde cualquier subdirectorio. El mismo
archivo construye en Linux, Windows y macOS: nada de él es por plataforma.
La regla sobre la que descansa el archivo entero:
Molto descubre tus fuentes; no descubre tus ajustes de build.
Cada archivo .c, .cpp y .cc bajo src/ y tests/ se compila automáticamente: nunca
enumeras archivos. Los include, los defines, las librerías y la disposición de los tests son
únicamente lo que diga este archivo. Nada se deduce de la estructura de directorios, y no hay
vuelta atrás a un Makefile.
Las rutas relativas de include y test.sources se resuelven contra la raíz del proyecto,
nunca contra el directorio desde el que lanzaste el comando. flags se pasa literalmente por
contrato y nunca se reescribe.
Qué escribe molto new
Una librería por defecto — molto new my_lib:
[package]
name = "my_lib"
version = "0.1.0"
artifact = "static"
[target]
std = "c17"
include = ["include"]
[profile.debug]
opt_level = 0
debug_info = true
[profile.release]
opt_level = 3
debug_info = false
[test]
mode = "single" # moltest registra los tests y es dueño de main()
[dev-deps]
moltest = { git = "https://github.com/moltobuild/moltest", tag = "v0.3.0" }
molto new my_app --bin escribe lo mismo sin artifact, [test] ni [dev-deps], y un
src/main.c en vez de una librería y su test. Cualquiera de los dos es un proyecto completo: no hay
un segundo archivo ni un paso de generación.
[package]
| Clave | Tipo | Notas |
|---|---|---|
name |
string | Obligatoria. snake_case, debe empezar por una minúscula |
version |
string | Formato libre; por defecto 0.0.0. Debe ser semver para una librería compartida |
artifact |
string | executable (por defecto), static o shared. source se rechaza |
description |
string | Una línea que dice qué es el paquete |
license |
string | Una expresión SPDX: MIT, MIT OR Apache-2.0, Apache-2.0 WITH LLVM-exception |
homepage |
string | URL |
repository |
string | URL |
authors |
array | Como mucho 8 entradas |
name y version llegan a cada unidad de traducción como MOLTO_PKG_NAME y MOLTO_PKG_VERSION,
así que un programa puede reportar su propia versión sin una cabecera que mantener sincronizada.
artifact decide qué aterriza en build/<perfil>/:
artifact |
Linux | macOS |
|---|---|---|
executable (por defecto) |
greet |
greet |
static |
libgreet.a |
libgreet.a |
shared |
libgreet.so.1.2.3, más libgreet.so.1 y libgreet.so |
libgreet.1.2.3.dylib, más libgreet.1.dylib y libgreet.dylib |
En Windows un ejecutable es greet.exe. Los tres nombres de una librería compartida son lo que lee
el cargador: un programa enlazado contra libgreet.so.1 sigue funcionando cuando 1.2.3 se
sustituye por 1.9.0, y deja de hacerlo con 2.0.0. Los tests enlazan los objetos de src/ en
cualquier caso, así que una librería se prueba igual que un programa; molto run sobre una se
niega, porque no hay nada que ejecutar.
Las cinco últimas claves no llegan a ninguna línea de compilación: son lo que muestra un catálogo y
lo que lee molto metadata para nombrar tu licencia. [package] falla en
cerrado: una clave desconocida en ella es un error que la nombra, porque un licence descartado
en silencio publicaría un paquete que no declara licencia alguna.
[target]
| Clave | Tipo | Emite |
|---|---|---|
compiler |
string | Nada directamente: gcc, g++, clang, llvm o msvc. Ausente significa autodetección |
std |
string | -std= para las fuentes C |
cpp_std |
string | -std= para las fuentes C++ |
requires |
array | Nada: capacidades que deben demostrar que compilan |
include |
array | -I, relativo a la raíz del proyecto |
defines |
array | -D, en la forma que corresponda a cada compilador |
link |
array | -l, nombres sin el prefijo |
flags |
array | Literal, tanto al compilador como al enlazador |
host |
array | Los include y los flags de enlace de una librería que la máquina ya tiene |
compiler es una preferencia de fabricante, no un binario. Nombrar un fabricante en vez de una
ruta es lo que mantiene portable un manifiesto: gcc es la versión 9 en una máquina y la 14 en
otra. Cualquier cosa fuera de esa lista es un error.
std elige el modo; requires declara lo que tiene que funcionar de verdad. Aceptar -std=c2x no
es lo mismo que implementarlo: un compilador puede tragarse el flag y aun así rechazar
[[nodiscard]]. Molto le pregunta a pickup qué toolchain local demuestra cada
capacidad compilando un programa que la usa, y cachea la respuesta en .bin/wsdb.
--refresh-toolchain vuelve a preguntar.
Omitir std hereda el valor por defecto del compilador, que cambia según la toolchain y la
versión. Decláralo.
host nombra una librería por capacidad, nunca por ruta —host = ["gtk+-3.0"]— y pkg-config
responde dónde están sus cabeceras y librerías en esta máquina. Un valor con / se rechaza: una
ruta es la disposición de una máquina, y una capacidad es la misma palabra en todas. Para una
librería que Molto deba traer cuando la máquina no la tiene, usa un
paquete de plataforma.
Para un flag de enlazado que no es una librería —-Wl,... o -pthread en tiempo de compilación—
usa flags, no link.
Molto elige el driver de C para .c y el de C++ para .cpp y .cc, ambos de la misma toolchain
resuelta, así que un proyecto mixto nunca mezcla compiladores. Un proyecto con C++ cuya toolchain
no tiene driver de C++ se reporta de entrada, no se descubre al enlazar.
[test]
| Clave | Tipo | Notas |
|---|---|---|
mode |
string | per_file (por defecto) o single |
sources |
array | Fuentes extra que sólo se compilan para tests; recorre directorios |
defines, include, flags |
array | Sólo se aplican al compilar tests/ |
[[test.isolated]] file, replaces |
array de tablas | Un archivo de test enlazado solo, sin las fuentes que sustituye |
per_file construye un ejecutable por archivo de tests/, cada uno enlazado contra los objetos
del proyecto menos src/main.c, y cada uno con su propio main(). La salida va a
build/<perfil>/tests/<nombre>.
single enlaza todo en un único ejecutable en build/<perfil>/tests/<paquete>_tests. Es lo que
necesita un framework que registra sus casos y es dueño de main(): moltest, como
dependencia de desarrollo, llega solo al build de tests.
[[test.isolated]] sirve para falsear una función: el archivo se enlaza en un ejecutable propio,
sin las fuentes que nombra, para que un fake
(moltest-mock, fff o uno escrito a mano) ocupe su
lugar:
[[test.isolated]]
file = "tests/test_network.c"
replaces = ["src/socket.c"] # o "dep:src/x.c" en una dependencia, o "dep" para toda ella
Un framework que vive en el árbol en vez de en [dev-deps] no se compila salvo que sources lo
nombre: es la razón más común de que un build de tests falle en los símbolos del propio framework.
[profile.*]
Hay cinco perfiles: debug (por defecto), release, bench, custom y coverage. Se elige uno
con --profile; la salida va a build/<perfil>/.
| Clave | Tipo | Notas |
|---|---|---|
opt_level |
integer | -O |
debug_info |
bool | -g |
defines, include, flags |
array | Se añaden sobre [target], nunca lo sustituyen |
Valores por defecto cuando falta la tabla:
| Perfil | opt_level |
debug_info |
|---|---|---|
debug |
0 | true |
release |
3 | false |
bench |
3 | false |
custom |
2 | true |
coverage |
0 | true |
coverage además está siempre instrumentado: Molto añade --coverage a las líneas de compilación
y enlazado de src/ y tests/ por su cuenta, y molto test --profile coverage deja los contadores
bajo build/coverage/. Las dependencias no se instrumentan, así que la cifra es la de tu código.
Con moltest, moltest-coverage los convierte en un
informe y un umbral opcional; si no, apunta gcovr o lcov a build/coverage/. Necesita un
compilador compatible con GCC o Clang.
custom es el sitio para todo lo demás, sanitizers incluidos: los flags de un perfil llegan
también a la línea de enlazado:
[profile.custom]
opt_level = 0
debug_info = true
flags = ["-fsanitize=address,undefined", "-fno-omit-frame-pointer"]
Cambiar cualquier ajuste de compilación provoca una recompilación: Molto registra el comando exacto de cada objeto y reconstruye cuando cambia.
[env]
[env]
MY_APP_LOG = "debug"
Las claves son nombres de variables y los valores tienen que ser cadenas. Se exportan a las
invocaciones del compilador y el enlazador, y al programa bajo molto run y molto test. Se
establecen sólo en el proceso hijo, así que el entorno de Molto nunca se modifica y el [env]
de un proyecto no puede colarse en otro.
Límites
Sobrepasar uno es un error del manifiesto, nunca un recorte silencioso: perder un flag produciría un build en verde con opciones que no pediste.
| Límite | |
|---|---|
Entradas en defines / include / flags / requires / test.sources |
16 |
| Longitud de una de esas entradas | 95 caracteres |
Entradas en link, y longitud de una |
32 / 63 caracteres |
Entradas en [env] |
32 |
Longitud de nombre / valor en [env] |
63 / 255 caracteres |
Longitud de description / homepage / repository |
255 caracteres |
Longitud de license |
63 caracteres |
Entradas en authors, y longitud de una |
8 / 127 caracteres |
Las claves desconocidas se descartan sin avisar
Una errata en el nombre de una clave simplemente desaparece. Si un ajuste parece no tener efecto, revisa primero cómo está escrito.
El manifiesto tolera claves desconocidas porque la RFC-0003 especifica tablas que este binario aún no implementa, y rechazarlas descartaría manifiestos que son válidos por diseño.
Las excepciones fallan en cerrado: [package], [deps] y [dev-deps], donde una clave
desconocida, dos orígenes o un rango de versiones es un error que la nombra, y format.json y
linter.json. Una dependencia mal leída es una dependencia que en silencio no está.
Especificado pero no implementado
| Tabla o clave | Qué pasa hoy |
|---|---|
| Más de un target por proyecto | Una librería y el programa que la usa necesitan dos; un manifiesto describe uno |
package.artifact = "source" |
Error duro: servir fuentes es cosa de una recipe |
dep.artifact, optional, features, default_features |
Rechazadas, no ignoradas |
[features], [build-deps], [workspace] |
No se leen |
target.triple, tablas por sistema operativo |
No se leen: la plataforma la elige molto build --target |
profile.lto, strip, sanitizers, warnings_as_errors |
No se leen: los sanitizers van en los flags de un perfil |
Si vienes de un Makefile
Lee CFLAGS y LDFLAGS, y pon cada pieza bajo la clave a la que pertenece. Frente a un Makefile
que pasa -Iinclude -D_DEFAULT_SOURCE -Wall -Wextra -Wpedantic -pthread y construye sus tests con
un framework dueño de main():
[target]
std = "c2x"
requires = ["attr_nodiscard"]
defines = ["_DEFAULT_SOURCE"]
include = ["include"]
flags = ["-Wall", "-Wextra", "-Wpedantic", "-pthread"]
[test]
mode = "single"
[dev-deps]
moltest = { git = "https://github.com/moltobuild/moltest", tag = "v0.3.0" }
Ese es el manifiesto del propio Molto, menos los perfiles y los tests aislados: el repositorio se construye con su propia herramienta.
Resolución de problemas
| Síntoma | Causa | Arreglo |
|---|---|---|
fatal error: 'pkg/foo.h' file not found |
No hay include declarado | include = ["include"] |
Los tests no enlazan, falta o sobra main |
El framework es dueño de main() |
mode = "single" |
| Los tests fallan en las cabeceras del framework | Vive fuera de src/ |
Ponlo en [dev-deps], o en test.sources |
| Faltan avisos que esperabas | flags sin declarar |
flags = ["-Wall", "-Wextra"] |
Un #ifdef nunca se activa |
defines sin declarar |
Añádelo a [target].defines |
undefined reference a sqrt, pthread_create |
Librería sin enlazar | link = ["m", "pthread"] |
unknown compiler '…' |
compiler nombra un binario |
Usa un fabricante, o quita la clave |
a shared library needs a major version |
artifact = "shared" sin semver |
Dale a version un número mayor |
has nothing to run |
molto run sobre una librería |
Lo que la ejercita es molto test |
| Una clave parece no hacer nada | Errata, o no implementada | Compruébala en las tablas de arriba |
not inside a molto workspace |
No hay manifiesto aquí ni arriba | molto init |