v0.2.12
This commit is contained in:
@@ -0,0 +1,475 @@
|
||||
# 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
|
||||
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.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user