476 lines
13 KiB
Markdown
476 lines
13 KiB
Markdown
# 41. Artifacts, exports, profils et réservation des formats futurs
|
|
|
|
## 41.1 Type de package vs artifact — V1 REQUIS — FIGÉ
|
|
|
|
Le type du package reste strictement :
|
|
|
|
```text
|
|
lib
|
|
bin
|
|
```
|
|
|
|
Un package ne combine pas les deux rôles.
|
|
|
|
`browser-binary` est réservé comme troisième type possible FUTUR V3+, sans obligation d'implémentation V1.
|
|
|
|
## 41.2 Artifacts V1 d'un package `lib` — V1 REQUIS — FIGÉS EN PRINCIPE
|
|
|
|
Les artifacts fondamentaux V1 sont :
|
|
|
|
```text
|
|
Saselib
|
|
NativeStatic
|
|
NativeShared
|
|
```
|
|
|
|
`Saselib` est l'artifact canonique de dépendance Saselang.
|
|
|
|
Les formats physiques de `NativeStatic`/`NativeShared` dépendent de la plateforme et ne deviennent pas de nouveaux types d'artifact (`.a`, `.lib`, `.so`, `.dll`, `.dylib`, etc.).
|
|
|
|
## 41.3 Artifacts V1 d'un package `bin` — V1 REQUIS — FIGÉ EN PRINCIPE
|
|
|
|
L'artifact fondamental V1 est :
|
|
|
|
```text
|
|
NativeExecutable
|
|
```
|
|
|
|
Les sorties techniques du backend :
|
|
|
|
```text
|
|
LLVM IR
|
|
object
|
|
assembly
|
|
```
|
|
|
|
sont des `emit`/outputs techniques et non des types de package ni nécessairement des artifacts publiables de premier rang.
|
|
|
|
## 41.4 `.saselib` — V1 REQUIS — DIRECTION FIGÉE
|
|
|
|
Une `.saselib` doit être aussi target-neutral que possible et transporter les informations nécessaires à la consommation/recompilation finale, notamment :
|
|
|
|
```text
|
|
identité vendor/package
|
|
version exacte
|
|
version de format saselib
|
|
API publique
|
|
métadonnées de types/generics nécessaires
|
|
Sase IR ou représentation compilable équivalente
|
|
dépendances requises
|
|
features pertinentes
|
|
contraintes de target/capability lorsque nécessaires
|
|
intégrité/métadonnées
|
|
```
|
|
|
|
Le format physique V1 est fixé :
|
|
|
|
```text
|
|
TAR POSIX/PAX
|
|
compressé par Zstandard
|
|
extension publique .saselib
|
|
```
|
|
|
|
La première entrée du flux TAR est obligatoirement :
|
|
|
|
```text
|
|
META-INF/saselib.manifest.toml
|
|
```
|
|
|
|
L'ordre des autres entrées et le niveau Zstandard canonique seront déterminés plus tard par benchmark, sans modifier le modèle logique ni l'extension `.saselib`.
|
|
|
|
Les portions dépendantes d'une ABI/FFI native peuvent réduire la portabilité de la `.saselib` sans changer son rôle logique.
|
|
|
|
## 41.5 Mode de distribution d'exécutable — V1 REQUIS — FIGÉ EN PRINCIPE
|
|
|
|
Pour `NativeExecutable`, V1 prévoit au minimum :
|
|
|
|
```text
|
|
external
|
|
standalone
|
|
```
|
|
|
|
`standalone` signifie que la toolchain inclut ou accompagne tout ce qui peut raisonnablement et légalement être rendu autonome : runtime Saselang, libraries statiquement intégrables et ressources nécessaires.
|
|
|
|
Il ne promet pas l'absence absolue de tout prérequis système lorsque cela est impossible.
|
|
|
|
Le mode n'est pas un type de package.
|
|
|
|
## 41.6 Export formats — V1 RÉSERVÉ / FUTUR
|
|
|
|
Les formats :
|
|
|
|
```text
|
|
zip
|
|
tar
|
|
tar.gz
|
|
tar.zst
|
|
```
|
|
|
|
sont des formats d'export/distribution, pas des artifacts fondamentaux.
|
|
|
|
Le modèle doit également pouvoir accueillir à terme :
|
|
|
|
```text
|
|
deb
|
|
rpm
|
|
apk
|
|
AppImage
|
|
.run
|
|
msi
|
|
pkg
|
|
dmg
|
|
jar
|
|
browser chunks
|
|
Android packages
|
|
iOS packages
|
|
```
|
|
|
|
sans modifier les notions `PackageType`, `ArtifactKind` ou `TargetFamily` existantes.
|
|
|
|
## 41.7 Séparation artifact / distribution / export — V1 REQUIS — FIGÉE
|
|
|
|
Exemple conceptuel :
|
|
|
|
```text
|
|
package type = bin
|
|
artifact = NativeExecutable
|
|
target family = Native
|
|
platform = Linux
|
|
architecture = X86_64
|
|
ABI = Gnu
|
|
distribution = Debian (optionnel/réservé)
|
|
export format = Deb (futur)
|
|
```
|
|
|
|
Chaque axe répond à une question différente et ne doit pas être réencodé dans le nom d'un autre axe.
|
|
|
|
## 41.8 Profils V1 — V1 REQUIS — FIGÉ
|
|
|
|
Les seuls profils standards V1 sont :
|
|
|
|
```text
|
|
dev
|
|
release
|
|
```
|
|
|
|
Un profil décrit **comment compiler**. Il ne décrit ni l'action exécutée, ni le scope de dépendances actif, ni une variante sémantique du langage.
|
|
|
|
La V1 n'introduit pas de profils standards distincts `test`, `benchmark`, `documentation`, `integration`, etc. Ces notions relèvent des commandes, des scopes de dépendances ou d'outils spécialisés. Les profils nommés supplémentaires restent une possibilité future, mais ne doivent pas être nécessaires à l'architecture V1.
|
|
|
|
### 41.8.1 Propriétés génériques d'un profil
|
|
|
|
Les propriétés communes V1 sont limitées à des réglages indépendants du backend :
|
|
|
|
```text
|
|
optimization
|
|
debug-info
|
|
incremental
|
|
```
|
|
|
|
`optimization` utilise un domaine sémantique et non des niveaux propres à LLVM :
|
|
|
|
```text
|
|
none
|
|
low
|
|
balanced
|
|
speed
|
|
size
|
|
```
|
|
|
|
`debug-info` utilise :
|
|
|
|
```text
|
|
none
|
|
line
|
|
full
|
|
```
|
|
|
|
`incremental` est booléen.
|
|
|
|
Exemple :
|
|
|
|
```toml
|
|
[profiles.dev]
|
|
optimization = "none"
|
|
debug-info = "full"
|
|
incremental = true
|
|
|
|
[profiles.release]
|
|
optimization = "speed"
|
|
debug-info = "line"
|
|
incremental = false
|
|
```
|
|
|
|
Les defaults normatifs V1 sont ceux de cet exemple.
|
|
|
|
Le mapping d'un niveau générique vers les options concrètes du backend appartient à l'implémentation du backend, mais deux backends conformes ne doivent pas modifier la sémantique observable de Saselang pour interpréter différemment un profil.
|
|
|
|
### 41.8.2 Ce qu'un profil ne peut jamais modifier
|
|
|
|
Un profil ne peut notamment pas :
|
|
|
|
```text
|
|
désactiver les contrôles d'overflow définis par Saselang
|
|
modifier la sémantique d'un index hors limites
|
|
modifier l'ordre d'évaluation
|
|
modifier la représentation sémantique des types
|
|
changer les règles Result/throws/faults
|
|
désactiver les vérifications de sûreté du langage
|
|
faire varier la validité d'un programme Saselang autrement que par une limite propre au backend/target
|
|
```
|
|
|
|
`dev` et `release` doivent donc compiler le **même programme Saselang** ; seuls le coût de compilation, l'optimisation, les informations de debug et les caractéristiques non sémantiques de l'artifact peuvent varier.
|
|
|
|
### 41.8.3 Options propres au backend
|
|
|
|
Les options non portables vivent dans un sous-espace explicitement backend-specific :
|
|
|
|
```toml
|
|
[profiles.release.backend.llvm]
|
|
lto = "thin"
|
|
```
|
|
|
|
La V1 réserve cette structure générale :
|
|
|
|
```text
|
|
profiles.<profile>.backend.<backend>
|
|
```
|
|
|
|
sans faire des options LLVM des propriétés universelles du manifest.
|
|
|
|
Pour LLVM V1, le réglage `lto` peut prendre :
|
|
|
|
```text
|
|
off
|
|
thin
|
|
full
|
|
```
|
|
|
|
Les options backend supplémentaires ne doivent être ajoutées que lorsqu'un besoin réel existe.
|
|
|
|
Le choix de CPU, d'architecture, d'ABI ou de plateforme n'est pas une propriété du profil ; il appartient au target.
|
|
|
|
### 41.8.4 Sélection du profil
|
|
|
|
Les commandes de build utilisent `dev` par défaut, sauf demande explicite contraire.
|
|
|
|
Une commande peut sélectionner :
|
|
|
|
```text
|
|
--profile dev
|
|
--profile release
|
|
```
|
|
|
|
Un raccourci CLI `--release` peut exister comme équivalent strict de `--profile release`, mais il ne constitue pas un troisième mécanisme de configuration.
|
|
|
|
## 41.9 Principe de réservation V1 — V1 REQUIS — FIGÉ
|
|
|
|
La Bible V1 doit définir les **dimensions stables** nécessaires aux évolutions prévues, même lorsque la première toolchain n'implémente pas toutes leurs valeurs.
|
|
|
|
La V1 n'est pas tenue d'implémenter :
|
|
|
|
```text
|
|
browser runtime définitif
|
|
WASM/JVM/JS backends
|
|
packaging Android/iOS
|
|
.deb/.rpm/.apk/.msi/.dmg
|
|
installation automatique de dépendances système sur toutes les distributions
|
|
```
|
|
|
|
mais elle ne doit pas imposer un modèle de manifest, de target ou d'artifact qui obligerait à refaire ces abstractions en V3+.
|
|
|
|
## 41.9.1 Format physique `.saselib` V1 — V1 REQUIS — FIGÉ
|
|
|
|
L'artefact canonique d'un package Saselang de type `lib` est :
|
|
|
|
```text
|
|
<name>.saselib
|
|
```
|
|
|
|
Pour la version de format V1, une `.saselib` est physiquement :
|
|
|
|
```text
|
|
archive TAR POSIX/PAX
|
|
compressée par Zstandard
|
|
```
|
|
|
|
Le choix du conteneur et de la compression est un détail interne du format `.saselib` ; l'extension publique reste toujours `.saselib`.
|
|
|
|
La structure physique du format V1 impose que la première entrée du flux TAR soit :
|
|
|
|
```text
|
|
META-INF/saselib.manifest.toml
|
|
```
|
|
|
|
Cette entrée est obligatoire et doit permettre au toolchain de connaître immédiatement au moins :
|
|
|
|
```text
|
|
version du format saselib
|
|
identité vendor/package
|
|
version exacte SemVer du package
|
|
compatibilité de version du langage Saselang
|
|
nature/portabilité de la bibliothèque
|
|
inventaire logique des contenus présents
|
|
requirements de dépendances
|
|
features pertinentes
|
|
contraintes de target/capabilities
|
|
métadonnées FFI/native nécessaires
|
|
informations d'intégrité prévues par la version de format
|
|
```
|
|
|
|
Le format interne est extensible et versionné. Les autres contenus possibles peuvent inclure notamment :
|
|
|
|
```text
|
|
Sase IR
|
|
métadonnées publiques/types/generics
|
|
artifacts binaires spécifiques à certains targets
|
|
ressources
|
|
documentation
|
|
autres données définies par une version future du format
|
|
```
|
|
|
|
Leur présence dépend du `format-version` et de ce qui est déclaré dans `META-INF/saselib.manifest.toml`.
|
|
|
|
L'ordre exact des entrées après `META-INF/saselib.manifest.toml` n'est **pas encore normatif**. Il sera défini plus tard en fonction des besoins réels de chargement, de streaming, de cache et des benchmarks du toolchain.
|
|
|
|
Le format V1 ne dépend d'aucun format propriétaire :
|
|
|
|
```text
|
|
TAR POSIX/PAX
|
|
Zstandard
|
|
```
|
|
|
|
sont des formats ouverts et documentés.
|
|
|
|
La compression est appliquée au flux TAR complet, afin de favoriser à la fois :
|
|
|
|
```text
|
|
bon ratio de compression
|
|
décompression rapide
|
|
chargement séquentiel efficace par les outils
|
|
```
|
|
|
|
Le niveau Zstandard canonique n'est pas fixé par la Bible à ce stade. Il devra être déterminé par benchmark sur de vraies `.saselib`.
|
|
|
|
Une future version de format `.saselib` pourra changer son conteneur ou sa stratégie de compression si un autre format ouvert apporte un avantage démontré, sans changer l'extension ni le modèle logique Saselang.
|
|
|
|
## 41.10 Pilotage du build et commandes V1 — V1 REQUIS — FIGÉ EN SQUELETTE
|
|
|
|
La toolchain V1 conserve les noms d'outils dédiés :
|
|
|
|
```text
|
|
saselc
|
|
saseldoc
|
|
```
|
|
|
|
La V1 n'introduit pas un troisième outil générique uniquement pour masquer ces responsabilités.
|
|
|
|
### 41.10.1 Commandes minimales de `saselc`
|
|
|
|
Le squelette de commandes V1 est :
|
|
|
|
```text
|
|
saselc check
|
|
saselc build
|
|
saselc run
|
|
saselc test
|
|
saselc clean
|
|
saselc fetch
|
|
saselc update
|
|
```
|
|
|
|
Leur rôle est distinct :
|
|
|
|
```text
|
|
check
|
|
résolution du projet et des dépendances nécessaires
|
|
parsing, analyse sémantique et validations
|
|
pas de génération de l'artifact final
|
|
|
|
build
|
|
compilation et génération de l'artifact demandé
|
|
|
|
run
|
|
réservé à un projet de type bin
|
|
build si nécessaire puis exécution
|
|
transmet explicitement les arguments du programme
|
|
|
|
test
|
|
découverte/compilation/exécution des tests selon les règles V1
|
|
utilise les scopes dev appropriés
|
|
|
|
clean
|
|
supprime les sorties de build et temporary build de la racine concernée
|
|
ne supprime ni manifest ni lockfile
|
|
ne purge pas implicitement les caches globaux de dépendances
|
|
|
|
fetch
|
|
résout et récupère les dépendances nécessaires sans construire l'artifact
|
|
utilise le lock existant et le complète seulement si nécessaire
|
|
|
|
update
|
|
demande explicitement une nouvelle résolution compatible avec les requirements
|
|
met à jour le lockfile
|
|
peut cibler tout le graphe ou un selector/une identité précise
|
|
```
|
|
|
|
`build` n'effectue pas d'upgrade opportuniste lorsqu'une version verrouillée reste valide.
|
|
|
|
### 41.10.2 Emits techniques
|
|
|
|
Les sorties techniques ne deviennent pas des commandes ni des types de package supplémentaires.
|
|
|
|
`build` peut demander un ou plusieurs emits, par exemple conceptuellement :
|
|
|
|
```text
|
|
Sase IR
|
|
LLVM IR
|
|
object
|
|
assembly
|
|
```
|
|
|
|
La syntaxe CLI exacte peut prendre la forme d'une option `--emit`, à normaliser avec la CLI finale.
|
|
|
|
### 41.10.3 Racine de résolution
|
|
|
|
Lorsqu'elle est exécutée depuis un projet autonome, la toolchain utilise :
|
|
|
|
```text
|
|
project.manifest.toml
|
|
saselang.lock.toml
|
|
```
|
|
|
|
à la racine de résolution du projet.
|
|
|
|
Dans un workspace, `workspace.manifest.toml` et le lockfile de la racine workspace font autorité pour les projets membres construits dans ce contexte.
|
|
|
|
La CLI doit permettre de désigner explicitement un manifest/racine lorsqu'une découverte automatique ne convient pas. Le nom exact de cette option est à normaliser avec la grammaire CLI finale, sans changer le modèle de résolution.
|
|
|
|
### 41.10.4 Build de workspace et sélection de projet
|
|
|
|
Un appel de `saselc` depuis une racine workspace peut viser l'ensemble des membres compatibles avec la commande ou un membre explicite.
|
|
|
|
La sélection d'un projet doit utiliser son identité de package et non un nom de dossier ambigu.
|
|
|
|
La syntaxe exacte de sélection CLI reste à normaliser, mais cette capacité est requise par l'architecture workspace V1.
|
|
|
|
### 41.10.5 `saseldoc`
|
|
|
|
`saseldoc` est l'unique outil officiel de génération et validation de documentation Saselang. Il ne doit pas exister plusieurs générateurs officiels séparés selon la visibilité ou le format.
|
|
|
|
Le même outil reçoit des paramètres permettant au minimum de sélectionner :
|
|
|
|
```text
|
|
visibilités incluses
|
|
format de sortie
|
|
chemin de sortie
|
|
base path / base URL lorsque le format le nécessite, notamment HTML
|
|
projet/package/workspace ciblé
|
|
```
|
|
|
|
La grammaire CLI exacte reste à finaliser, mais ces dimensions appartiennent à la même commande/outillage `saseldoc`.
|
|
|
|
`saseldoc` utilise les mêmes règles de résolution de package, workspace, dépendances et visibilité que le compilateur. Il ne constitue pas un profil de build.
|
|
|
|
---
|