saselang-bible/chapters/035-manifests-et-workspaces.md

35. Manifests et workspaces

35.1 Format et noms — V1 REQUIS — FIGÉ

Saselang V1 utilise un seul format de manifest : TOML. JSON ou d'autres formats alternatifs ne sont pas acceptés pour les manifests officiels afin de conserver une syntaxe unique pour le compilateur, le resolver et les outils.

Les noms canoniques sont :

workspace.manifest.toml
project.manifest.toml

workspace.manifest.toml décrit uniquement un workspace. Il ne constitue jamais un package compilable.

project.manifest.toml est obligatoire à la racine de chaque projet/package, qu'il soit autonome ou membre d'un workspace.

Les deux manifests commencent par :

manifest-version = 1

manifest-version versionne le format du manifest ; il est distinct de la version SemVer du package.

35.2 Structure de workspace.manifest.toml — V1 REQUIS — FIGÉ

Structure V1 normative :

manifest-version = 1

[workspace]
projects-root = "projects"
members = [
    "core",
    "compiler",
    "sdk",
]

[workspace.output]
build-root = "build"
temp-build-root = ".saselang/tmp"

[workspace.defaults.project]
vendor = "saselang"
version = "0.1.0"
license = "..."
authors = ["..."]
repository = "..."

[workspace.defaults.source]
root = "src"

[workspace.defaults.build]
profile = "dev"
target = "host"

[workspace.defaults.paths]
dependencies = ["vendor"]
native-libraries = ["native/lib"]
native-includes = ["native/include"]

[workspace.dependencies."saselang/core@^1.0"]
source = "registry"

[workspace.dependencies."acme/math@^2.4"]
source = "git"
url = "https://example.invalid/acme/math.git"

[workspace.dependencies."local/tools@^1.0"]
source = "local"
path = "../shared/tools"

35.2.1 [workspace]

projects-root définit la racine à partir de laquelle les chemins de members sont résolus.

members contient la liste explicite des projets membres. Chaque membre doit contenir un project.manifest.toml valide.

V1 n'impose pas de découverte implicite récursive des projets ni de glob automatique. Ces mécanismes pourront être étudiés ultérieurement s'ils apportent un besoin concret.

35.2.2 [workspace.output]

Cette section configure les sorties du workspace :

build-root
    racine des sorties de build persistantes

temp-build-root
    racine des fichiers temporaires/intermédiaires de build

Ces champs sont propres au workspace et ne sont pas des propriétés de package. Le toolchain doit empêcher les collisions entre plusieurs projets sous ces racines, notamment en séparant les sorties par projet, target et profil.

35.2.3 [workspace.defaults.*]

Seules les valeurs placées sous workspace.defaults.* sont automatiquement héritables par les projets membres.

Catégories V1 :

workspace.defaults.project
workspace.defaults.source
workspace.defaults.build
workspace.defaults.paths

Un projet hérite d'une valeur absente de son propre manifest. S'il redéclare la même valeur, la valeur du projet la remplace.

Règles :

scalaire absent dans le projet
    -> valeur workspace héritée

scalaire présent dans le projet
    -> remplacement

liste absente dans le projet
    -> liste workspace héritée

liste présente dans le projet
    -> remplacement complet de la liste

Pas de concaténation ou fusion implicite de listes.

Les tables sont des conteneurs de clés ; le remplacement s'effectue sur la valeur de chaque clé explicitement redéclarée, sauf les entrées de dépendances qui sont atomiques.

35.2.4 Chemins hérités

Un chemin défini dans workspace.manifest.toml est résolu relativement à la racine du workspace.

Un chemin défini ou redéfini dans project.manifest.toml est résolu relativement à la racine du projet.

L'héritage ne change jamais la base de résolution d'un chemin provenant du workspace.

35.2.5 [workspace.dependencies]

Cette section est un catalogue de dépendances et de leurs moyens d'accès. Une entrée du catalogue ne devient jamais automatiquement une dépendance de chaque projet.

Chaque clé utilise le sélecteur canonique :

vendor/package@requirement

Les moyens d'accès prévus comprennent au minimum :

workspace
local
git
registry
native
system

La syntaxe et les champs propres à chaque source sont finalisés dans la section dédiée aux types de dépendances.

Le futur registry officiel Saselang utilisera le même modèle vendor/package@requirement ; son protocole et son hébergement ne sont pas requis pour définir le langage V1.

35.3 Structure de project.manifest.toml — V1 REQUIS — FIGÉ

Structure V1 de base :

manifest-version = 1

[project]
vendor = "acme"
name = "my-application"
version = "1.2.0"
type = "bin"
description = "..."
license = "..."
authors = ["..."]
repository = "..."

[source]
root = "src"

[build]
profile = "dev"
target = "host"

[paths]
dependencies = ["vendor"]
native-libraries = ["native/lib"]
native-includes = ["native/include"]

[dependencies]
"saselang/core@^1.0" = { workspace = true }

[build.dependencies]

[dev.dependencies]

[dev.unit.dependencies]

[dev.integration.dependencies]

[dev.environment.dependencies]

Les sections de features, artifacts et autres réglages spécialisés sont ajoutées dans leurs sections normatives respectives ; elles ne changent pas l'identité fondamentale du projet.

35.3.1 [project]

Après application de l'héritage du workspace, les valeurs effectives obligatoires sont :

vendor
name
version
type

name et type doivent être déclarés par le projet lui-même. Ils ne sont pas héritables, car ils définissent son identité locale et sa nature.

vendor et version peuvent être hérités depuis workspace.defaults.project afin de supporter proprement les workspaces partageant un vendor ou une politique de version commune.

version est une version SemVer 2.0.0 exacte, jamais un requirement.

Métadonnées telles que :

description
license
authors
repository

peuvent être héritées ou redéfinies. D'autres métadonnées de publication pourront être ajoutées seulement si elles ont une utilité concrète pour le toolchain/registry.

35.3.2 [source]

root indique le source_root du projet. La valeur V1 par défaut est :

src

Elle peut provenir de workspace.defaults.source.root.

35.3.3 [build]

Cette section contient les paramètres de build propres au projet pouvant remplacer les defaults du workspace, notamment :

profile
target

Les valeurs et la taxonomie exacte des targets sont définies dans la section targets. Les seuls profils V1 prévus sont dev et release, sous réserve de leur finalisation normative.

35.3.4 [paths]

Cette section peut remplacer les chemins hérités de workspace.defaults.paths.

Les catégories V1 prévues sont :

dependencies
native-libraries
native-includes

Ces chemins servent à la résolution/recherche et ne deviennent jamais des identités de dépendance.

35.3.5 Sélection des dépendances du workspace

Un projet utilise explicitement une dépendance du catalogue workspace :

[dependencies]
"saselang/core@^1.0" = { workspace = true }

Le sélecteur doit correspondre à une entrée du catalogue visible du workspace.

Le projet peut aussi déclarer directement une dépendance et son moyen d'accès :

[dependencies."acme/math@^2.4"]
source = "git"
url = "https://example.invalid/acme/math.git"

Si le projet redéclare directement le même sélecteur qu'une définition workspace, la déclaration du projet remplace entièrement la définition workspace sélectionnée pour ce sélecteur. Il n'existe pas de fusion implicite de source, url, path, features, mappings natifs ou autres propriétés de dépendance.

35.4 Règles générales d'héritage — V1 REQUIS — FIGÉ

La précédence est :

valeurs intrinsèques/defaults du langage/toolchain
    < workspace.defaults.*
    < project.manifest.toml
    < options explicites de la commande de build lorsque l'option est conçue pour être overridable

Une option de ligne de commande ne peut pas changer l'identité vendor/name@version du projet pendant un build normal.

Les sections workspace, workspace.output et workspace.dependencies sont des structures du workspace ; elles ne sont pas copiées implicitement dans le projet.

35.5 Types de package V1 — V1 REQUIS — FIGÉ

Exactement un type par projet/package :

lib
bin

Pas de combinaison lib + bin dans un même projet comme Cargo.

Si un produit a besoin d'une library, d'un CLI et d'un serveur, il utilise plusieurs projets/packages dans un workspace avec des dépendances explicites entre eux.

35.6 browser-binary — V1 RÉSERVÉ / FUTUR V3+

Type de projet/package envisagé pour l'environnement browser futur.

Direction possible :

• package d'entrée browser ;
• contient principalement/uniquement des .saselscript et ressources ;
• le code réutilisable est chargé via des dépendances lib ;
• produit ensuite des chunks/browser artifacts.

Cette conception est volontairement réservée et peut évoluer avant V3 sans changer les types V1 lib et bin.