Ir al contenido
Molto

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