362 lines
10 KiB
Markdown
362 lines
10 KiB
Markdown
# 37. Dépendances et scopes
|
|
|
|
## 37.1 Deux axes indépendants — V1 REQUIS — FIGÉ
|
|
|
|
Une dépendance est décrite selon deux axes distincts :
|
|
|
|
```text
|
|
kind = nature logique de la dépendance
|
|
source = moyen utilisé pour la localiser/résoudre
|
|
```
|
|
|
|
V1 fixe au minimum les `kind` suivants :
|
|
|
|
```text
|
|
saselang
|
|
native
|
|
```
|
|
|
|
Les sources prévues par le schéma V1 sont :
|
|
|
|
```text
|
|
workspace
|
|
registry
|
|
local
|
|
git
|
|
artifact
|
|
system
|
|
```
|
|
|
|
Toutes les combinaisons ne sont pas nécessairement implémentées dès la première toolchain V1. Le schéma doit néanmoins permettre de les représenter sans refonte ultérieure.
|
|
|
|
Les dépendances npm/JVM/WASM et autres écosystèmes sont FUTUR V3+, mais doivent pouvoir être ajoutées comme nouveaux `kind`/modes de résolution sans changer l'identité canonique des dépendances.
|
|
|
|
## 37.2 Syntaxe unique des dépendances — V1 REQUIS — FIGÉE EN PRINCIPE
|
|
|
|
Tous les scopes et toutes les sources utilisent la même enveloppe TOML :
|
|
|
|
```toml
|
|
[dependencies."vendor/package@requirement"]
|
|
kind = "saselang"
|
|
source = "registry"
|
|
locator = "saselang"
|
|
```
|
|
|
|
Il n'existe pas en parallèle des raccourcis incompatibles de type :
|
|
|
|
```toml
|
|
foo = "^1.2"
|
|
foo = "../foo"
|
|
```
|
|
|
|
La clé canonique reste :
|
|
|
|
```text
|
|
vendor/package@requirement
|
|
```
|
|
|
|
`locator` désigne le moyen physique de retrouver la dépendance selon `source`. Sa sémantique exacte dépend de cette source, mais son rôle reste unique.
|
|
|
|
Exemples :
|
|
|
|
```toml
|
|
[dependencies."acme/math@^2.4"]
|
|
kind = "saselang"
|
|
source = "git"
|
|
locator = "https://example.org/acme/math.git"
|
|
```
|
|
|
|
```toml
|
|
[dependencies."acme/local-tools@^1.0"]
|
|
kind = "saselang"
|
|
source = "local"
|
|
locator = "../local-tools"
|
|
```
|
|
|
|
```toml
|
|
[dependencies."acme/parser@=1.4.2"]
|
|
kind = "saselang"
|
|
source = "artifact"
|
|
locator = "../libs/parser.saselib"
|
|
```
|
|
|
|
```toml
|
|
[dependencies."sdl/sdl@^3.0"]
|
|
kind = "native"
|
|
source = "system"
|
|
locator = "SDL3"
|
|
```
|
|
|
|
## 37.3 Dépendance workspace — V1 REQUIS — FIGÉE EN PRINCIPE
|
|
|
|
Le workspace peut définir un catalogue :
|
|
|
|
```toml
|
|
[workspace.dependencies."sdl/sdl@^3.0"]
|
|
kind = "native"
|
|
source = "system"
|
|
locator = "SDL3"
|
|
```
|
|
|
|
Un projet doit sélectionner explicitement l'entrée :
|
|
|
|
```toml
|
|
[dependencies."sdl/sdl@^3.0"]
|
|
kind = "native"
|
|
source = "workspace"
|
|
```
|
|
|
|
Le `kind` doit correspondre à celui défini par le catalogue. Une entrée du catalogue n'est jamais injectée automatiquement dans tous les projets.
|
|
|
|
## 37.4 Scopes V1 — V1 REQUIS — FIGÉS
|
|
|
|
Les scopes requis en V1 sont :
|
|
|
|
```text
|
|
dependencies
|
|
build.dependencies
|
|
|
|
dev.dependencies
|
|
dev.unit.dependencies
|
|
dev.integration.dependencies
|
|
dev.environment.dependencies
|
|
```
|
|
|
|
Les scopes suivants sont réservés mais non normatifs tant que leurs workflows ne sont pas définis :
|
|
|
|
```text
|
|
dev.benchmark.dependencies
|
|
dev.documentation.dependencies
|
|
dev.example.dependencies
|
|
```
|
|
|
|
`dependencies` contient les dépendances du produit.
|
|
|
|
`build.dependencies` constitue un graphe de visibilité séparé destiné aux outils/hooks de build ; une build-dependency ne devient pas importable par le produit.
|
|
|
|
`dev.dependencies` est commun aux contextes de développement.
|
|
|
|
Les scopes `dev.unit`, `dev.integration` et `dev.environment` spécialisent respectivement les tests unitaires, les tests d'intégration et les environnements/outils externes de développement/test.
|
|
|
|
## 37.5 Héritage des scopes — V1 REQUIS — FIGÉ
|
|
|
|
```text
|
|
dev.unit effective =
|
|
dependencies
|
|
+ dev.dependencies
|
|
+ dev.unit.dependencies
|
|
```
|
|
|
|
Même règle pour `dev.integration` et `dev.environment`.
|
|
|
|
`build.dependencies` n'est pas ajouté à la visibilité des imports du produit ni des tests ; il appartient au graphe du système de build.
|
|
|
|
## 37.6 Remplacement entre scopes — V1 REQUIS — FIGÉ
|
|
|
|
L'unité de shadowing entre scopes est l'identité :
|
|
|
|
```text
|
|
vendor/package
|
|
```
|
|
|
|
Dès qu'un scope enfant déclare au moins une entrée pour cette identité, toutes les entrées héritées de cette même identité sont masquées dans ce scope.
|
|
|
|
Si plusieurs versions doivent réellement coexister dans le scope enfant, toutes leurs contraintes disjointes sont redéclarées explicitement dans ce scope.
|
|
|
|
Aucune fusion implicite champ par champ n'est effectuée.
|
|
|
|
## 37.7 Multi-version direct — V1 REQUIS — FIGÉ
|
|
|
|
Un même scope effectif peut contenir plusieurs selectors d'une même identité uniquement si leurs ensembles de versions sont deux à deux disjoints.
|
|
|
|
Valide :
|
|
|
|
```text
|
|
sdl/sdl@2.1.*
|
|
sdl/sdl@^3.0
|
|
```
|
|
|
|
Interdit :
|
|
|
|
```text
|
|
sdl/sdl@^3.0
|
|
sdl/sdl@3.1.*
|
|
```
|
|
|
|
Le resolver doit détecter les intersections de ranges et produire une erreur de manifest déterministe avant compilation.
|
|
|
|
## 37.8 Dépendance Saselang normale — V1 REQUIS — FIGÉ
|
|
|
|
Une dépendance de `kind = "saselang"` désigne toujours un package logique :
|
|
|
|
```text
|
|
vendor/package@requirement
|
|
```
|
|
|
|
L'artifact de bibliothèque Saselang consommé après résolution/build est une `.saselib`.
|
|
|
|
Une source `local` ou `git` désigne normalement les sources du package ; `artifact` peut désigner directement une `.saselib` précompilée.
|
|
|
|
## 37.9 Dépendances natives — V1 REQUIS — FIGÉ EN PRINCIPE
|
|
|
|
Une bibliothèque native est également encapsulée derrière :
|
|
|
|
```text
|
|
vendor/package@requirement
|
|
```
|
|
|
|
Par exemple :
|
|
|
|
```text
|
|
sdl/sdl@^3.0
|
|
```
|
|
|
|
peut représenter physiquement :
|
|
|
|
```text
|
|
Linux -> libSDL3.so / SONAME approprié
|
|
Windows -> SDL3.dll + import library éventuelle
|
|
macOS -> libSDL3.dylib ou framework approprié
|
|
```
|
|
|
|
Le nom physique n'est jamais l'identité logique de la dépendance.
|
|
|
|
Le même schéma de dépendance doit pouvoir porter des mappings conditionnés par target/platform/ABI/distribution. La syntaxe exacte du mapping natif sera finalisée avec la FFI et le linker, mais aucune nouvelle forme d'identité ne devra être introduite.
|
|
|
|
## 37.9.1 Variants natifs et sélection par environnement — V1 REQUIS — SQUELETTE FIGÉ
|
|
|
|
Une dépendance native possède une déclaration logique commune et peut ajouter une liste homogène de `variants` lorsque sa représentation physique dépend de l'environnement.
|
|
|
|
Exemple conceptuel :
|
|
|
|
```toml
|
|
[dependencies."sdl/sdl@^3.0"]
|
|
kind = "native"
|
|
source = "system"
|
|
locator = "SDL3"
|
|
|
|
[[dependencies."sdl/sdl@^3.0".variants]]
|
|
platform = "linux"
|
|
library = "SDL3"
|
|
|
|
[[dependencies."sdl/sdl@^3.0".variants]]
|
|
platform = "windows"
|
|
library = "SDL3"
|
|
```
|
|
|
|
Un variant peut contraindre une combinaison des dimensions suivantes :
|
|
|
|
```text
|
|
target-family
|
|
platform
|
|
architecture
|
|
abi
|
|
distribution
|
|
distribution-version
|
|
capabilities
|
|
```
|
|
|
|
Les variants n'introduisent jamais une nouvelle identité de dépendance : l'identité logique reste `vendor/package@requirement`.
|
|
|
|
Un variant plus spécifique prévaut sur un variant strictement moins spécifique lorsque les deux correspondent. Si plusieurs variants applicables sont incomparables en spécificité et qu'aucun n'est l'unique meilleur candidat, le manifest est ambigu et la toolchain doit produire une erreur déterministe. L'ordre textuel des variants ne départage jamais un conflit.
|
|
|
|
Exemple d'ambiguïté à refuser pour un target Linux x86_64 GNU :
|
|
|
|
```text
|
|
variant A : platform=linux, architecture=x86_64
|
|
variant B : platform=linux, abi=gnu
|
|
```
|
|
|
|
Aucun des deux n'est strictement plus spécifique que l'autre.
|
|
|
|
Le noyau V1 des propriétés physiques peut comprendre :
|
|
|
|
```text
|
|
library
|
|
linkage = auto | static | shared
|
|
deployment = auto | external | bundled
|
|
search-paths
|
|
include-paths
|
|
```
|
|
|
|
Le modèle réserve sans obligation d'implémentation complète en V1 :
|
|
|
|
```text
|
|
runtime-files
|
|
link-files/import-libraries
|
|
frameworks
|
|
system-packages
|
|
resources
|
|
plugins
|
|
```
|
|
|
|
Une dépendance native représente donc un package natif logique pouvant comporter plusieurs composants physiques ; elle n'est jamais réduite au modèle « une dépendance = un unique fichier .so/.dll ».
|
|
|
|
## 37.10 Requirements SemVer — V1 REQUIS — FIGÉ
|
|
|
|
Les versions suivent strictement SemVer 2.0.0.
|
|
|
|
Les requirements V1 doivent au minimum pouvoir exprimer :
|
|
|
|
```text
|
|
=1.4.7
|
|
^4.5
|
|
~1.4.2
|
|
3.1.*
|
|
>=1.0
|
|
>=1.2,<2.0
|
|
```
|
|
|
|
Une version exacte canonique comporte toujours `MAJOR.MINOR.PATCH`.
|
|
|
|
Une forme abrégée telle que `2.1` ne peut être acceptée que comme requirement/range dont la signification est définie sans ambiguïté ; elle n'est jamais une version exacte SemVer incomplète.
|
|
|
|
## 37.11 Imports de dépendances — V1 REQUIS — FIGÉ EN PRINCIPE
|
|
|
|
Toute utilisation d'un symbole provenant d'une dépendance externe au package courant passe par un import explicite :
|
|
|
|
```text
|
|
import type namespace.Type
|
|
from "vendor/package@requirement"
|
|
as LocalType;
|
|
```
|
|
|
|
Même principe pour `func`, `const` et `var`.
|
|
|
|
`as` est facultatif tant que le nom local est unique ; il devient obligatoire en cas de collision locale.
|
|
|
|
Le `from` doit référencer un selector effectivement déclaré dans le graphe effectif du fichier. Il ne déclenche aucune résolution indépendante.
|
|
|
|
La qualification complète sans import reste limitée aux symboles du package courant.
|
|
|
|
|
|
## 37.10 Politique de bootstrap natif et remplacement progressif — DIRECTION FIGÉE
|
|
|
|
Les premières générations de Saselang peuvent s'appuyer largement sur des bibliothèques natives existantes afin d'accélérer le bootstrap de la toolchain et de l'écosystème.
|
|
|
|
Cette dépendance initiale n'est pas considérée comme l'architecture finale souhaitée.
|
|
|
|
La trajectoire retenue consiste à réimplémenter, porter, adapter ou améliorer progressivement les composants pertinents en Saselang, puis à les distribuer sous forme de bibliothèques `.saselib`.
|
|
|
|
Les familles envisagées peuvent inclure notamment :
|
|
|
|
```text
|
|
MapDB-like
|
|
RocksDB-like
|
|
PostgreSQL-compatible components
|
|
SDL-like multimedia
|
|
WebKit/WebView integrations ou remplacements
|
|
bibliothèques image/audio/vidéo
|
|
outils UI et multimedia
|
|
```
|
|
|
|
Ces noms désignent des directions d'écosystème, pas des APIs déjà réservées.
|
|
|
|
L'objectif à long terme est de réduire les dépendances natives au strict minimum nécessaire au target. La libc ou son équivalent peut rester utilisée si sa substitution complète n'est pas raisonnable ou n'apporte pas de bénéfice suffisant.
|
|
|
|
Une réimplémentation Saselang n'est pas tenue de reproduire aveuglément l'architecture d'origine : elle peut corriger, simplifier, étendre ou améliorer l'API et l'implémentation.
|
|
|
|
L'ambition est de permettre progressivement un écosystème de bibliothèques comparable ou supérieur en richesse fonctionnelle à de grands ensembles tels que Qt ou GTK, sans transformer ces bibliothèques spécialisées en obligations du langage/Core/SDK.
|
|
|
|
---
|