Installation
Touba fournit une CLI autonome pour macOS, Linux et Windows, ainsi qu’une extension VS Code. Choisissez votre plateforme dans le Hub. Chaque fiche indique la version, les prérequis et l’empreinte SHA-256 du fichier.
Les installateurs macOS Apple Silicon et Intel sont signés et notariés par Apple.
Choisir son installation
| Plateforme | Prérequis système | Assistant | Archive autonome |
|---|---|---|---|
| macOS Apple Silicon | macOS 13.5 ou ultérieur, arm64 | .dmg | .tar.gz |
| macOS Intel | macOS 13.5 ou ultérieur, x64 | .dmg | .tar.gz |
| Linux x64 | Ubuntu 24.04 ou système compatible, glibc 2.39+ | .deb | .tar.gz |
| Windows x64 | Windows 64 bits, x64 | .exe | .tar.gz |
Les archives comprennent le compilateur, le runtime Node, les commandes Touba et les deux archives SDK. L’utilisation de la CLI ne demande pas d’installer Node, Rust, Cargo ou pnpm séparément. Les prérequis des applications hôtes JavaScript et Python sont précisés plus bas.
Avec un installateur
- macOS : ouvrez le DMG, puis Install Touba.app. L’installation s’effectue pour votre compte.
- Windows : lancez l’EXE et suivez l’assistant pour votre compte.
- Linux : ouvrez le DEB avec votre gestionnaire de logiciels, ou utilisez
sudo apt install ./touba-v1.0.0-linux-x64-setup.deb. L’installation est système.
Windows et SmartScreen
L’installateur Windows actuel n’est pas signé. SmartScreen peut afficher « Windows a protégé votre ordinateur » pour une application encore peu connue. Cet avertissement de réputation ne constitue pas, à lui seul, une détection de logiciel malveillant. Microsoft explique ces contrôles.
-
Téléchargez l’installateur depuis le Hub et comparez son empreinte SHA-256 avec celle affichée dans Détails :
Get-FileHash .\touba-v1.0.0-win32-x64-setup.exe -Algorithm SHA256 -
Si l’origine et l’empreinte correspondent, que vous faites confiance au fichier et que le message concerne seulement une application non reconnue, ouvrez Informations complémentaires, puis Exécuter quand même, si Windows le propose.
-
Si une menace est détectée, si l’empreinte diffère ou si votre organisation bloque l’exécution, arrêtez l’installation et contactez votre administrateur ou l’équipe Touba.
Conservez SmartScreen et l’antivirus actifs, quel que soit le navigateur utilisé. La signature éditeur Windows est à venir : l’équipe prépare cette amélioration pour faciliter l’installation. Une signature identifie l’éditeur ; la réputation se construit aussi dans le temps.
Avec une archive
Téléchargez le fichier de votre plateforme depuis le Hub, puis extrayez-le. Exemple pour macOS Apple Silicon :
tar -xzf touba-v1.0.0-darwin-arm64.tar.gz
sh touba-v1.0.0-darwin-arm64/install.sh
Pour macOS Intel, utilisez darwin-x64 ; pour Linux, utilisez linux-x64
dans le nom du fichier et du dossier. L’installation se fait dans $HOME/.touba
par défaut. Le script propose d’ajouter son dossier bin au PATH.
tar -xzf touba-v1.0.0-win32-x64.tar.gz
& .\touba-v1.0.0-win32-x64\install.ps1 -Prefix "$HOME\.touba"
Sous Windows, appliquez la politique d’exécution de votre organisation.
Ajoutez $HOME\.touba\bin au PATH utilisateur si nécessaire.
Ouvrez ensuite un nouveau terminal.
Vérifier le téléchargement
Comparez le résultat avec l’empreinte affichée dans Détails sur le Hub :
shasum -a 256 touba-v1.0.0-darwin-arm64.tar.gz
sha256sum touba-v1.0.0-linux-x64.tar.gz
Get-FileHash .\touba-v1.0.0-win32-x64.tar.gz -Algorithm SHA256
Adaptez le nom au fichier téléchargé, archive ou installateur.
Choisir le SDK de son application
La CLI exécute les programmes Touba. Le SDK est une dépendance de votre application hôte, à installer depuis sa racine :
| Application | Commande | Prérequis |
|---|---|---|
| JavaScript, ou TypeScript consommant le SDK JavaScript | touba sdk install javascript | Node.js 24.22.1+ (branche 24) et npm |
| Python | touba sdk install python | Python 3.11+ avec uv, ou venv et pip |
Vous pouvez installer les deux dans le même projet. Le SDK Python crée ou
réutilise .venv ; rien n’est installé globalement. Touba vérifie les archives
livrées, les conserve dans vendor/touba-sdk/<empreinte>/ et installe hors ligne.
Conservez ce dossier et les déclarations de dépendances dans Git, pas
node_modules ni .venv.
touba sdk --help
touba sdk install python --python python3.12
touba sdk install python --manager uv
touba sdk path javascript
touba sdk path python
--python choisit l’interpréteur lors de la création d’un venv. sdk path
retourne une archive vérifiée pour votre propre gestionnaire de dépendances.
Un projet pnpm/Yarn/Bun conserve son gestionnaire : sdk install javascript
refuse d’écrire un lockfile npm concurrent.
Pour les handlers, choisissez touba init --language javascript ou
touba init --language python. prepare génère ensuite les fichiers et
tests du langage choisi. Installer un SDK ne modifie ni le programme .tb,
ni sa gouvernance, ni le choix de langage hôte d’un projet existant.
Voir les guides JavaScript et Python.
Après une mise à jour de la CLI, relancez sdk install dans chaque application
à actualiser, puis ses tests métier. Les autres applications restent inchangées.
Installer l’extension VS Code
Installez Touba Language Toolkit depuis le Visual Studio Marketplace, ou utilisez la commande VS Code :
code --install-extension touba.touba-tools
Sur macOS, si vous obtenez zsh: command not found: code, suivez la procédure
activer la commande VS Code.
Vous pouvez aussi rechercher @id:touba.touba-tools dans la vue Extensions
de VS Code et cliquer sur Installer, sans passer par le terminal.
Le Marketplace sélectionne votre plateforme. Pour un fichier VSIX fourni par le Hub, ouvrez Extensions → … → Install from VSIX… et choisissez le fichier correspondant à votre système. VS Code 1.119.0 ou ultérieur est requis.
L’extension fournit les diagnostics et outils d’édition. Installez aussi la CLI
pour les commandes terminal. Run Current File peut aussi utiliser le runtime
embarqué de l’extension pour les fichiers autonomes.
L’extension cherche TOUBA_CLI_PATH dans l’environnement qui lance VS Code,
puis touba dans le PATH, puis $HOME/.touba/bin/touba.
Un chemin explicite invalide est signalé. Après un changement, relancez VS Code
et exécutez Touba: Check CLI.
Vérifier l’installation
touba version
touba doctor
Continuez avec votre premier programme. La
référence CLI présente les commandes et leurs options.
touba update --json indique la build installée et les informations de mise à jour.
Mettre à jour ou désinstaller
Arrêtez vos services Touba avant de remplacer la toolchain. Pour une archive
macOS ou Linux, lancez le nouveau install.sh --force ; pour Windows,
le nouveau install.ps1 -Force. Les projets et leurs SDK se mettent à jour séparément.
Pour désinstaller une installation par archive, utilisez le script
uninstall.sh ou uninstall.ps1 de cette archive avec le même préfixe.
Pour le DEB, utilisez votre gestionnaire de paquets. La section suivante décrit
la sauvegarde et la reprise des projets ayant des traitements en attente.
Changer de build sans perdre les attentes
Le numéro produit (par exemple 1.0.0), l’empreinte de build et les contrats de données ne désignent pas la même chose. Deux builds de développement peuvent partager le même numéro et avoir des contrats incompatibles.
Avant une mise à jour, arrêtez proprement le service. Sauvegardez ensemble
le projet, ses sources/configurations, .touba/, les journaux d’effets,
preuves et éventuels stores placés à des chemins explicites. Une copie à
chaud d’une base SQLite ne constitue pas cette sauvegarde.
Depuis le projet arrêté, contrôlez l’état avec la CLI candidate :
/chemin/vers/la-candidate/bin/touba serve --project-root . --check-state
La sortie JSON touba-state-preflight-v1 indique les stores contrôlés, les
attentes actives, la build candidate et la provenance connue. Aucun provider,
handler, timer d’expiration ou mécanisme de recovery n’est lancé.
structurally_valid signifie que les contrôles structurels passent, pas
que les règles métier ont été migrées. Une provenance unrecorded reste
inconnue ; elle n’est pas attribuée artificiellement à la nouvelle build.
Une origine enregistrée dans un autre projet ou une autre build provoque
un refus explicite. Ne modifiez pas cette origine pour contourner le contrôle.
Les scripts d’archive et les assistants macOS/Windows conservent le payload précédent sous builds/<empreinte>/
dans le préfixe d’installation. Ce dossier est autonome : invoquez son
bin/touba pour finir les attentes avec leur build d’origine, en pointant
vers le même projet arrêté. N’exécutez pas deux builds sur ses stores à la fois.
--force autorise le remplacement de la build active, pas la suppression
des archives de reprise. Les archives existantes ne sont pas écrasées.
Le paquet DEB remplace la toolchain système sous /opt/touba/toolchain.
Avant sa mise à jour, conservez séparément la build nécessaire aux attentes en cours.
Si le candidat refuse l’état, gardez cet état hors ligne ou terminez les attentes avec la build d’origine. Il n’y a pas de migration automatique ni de lecteur ancien ajouté au runtime. Restaurer un dossier ne rembobine jamais un effet externe : vérifiez le journal avant la reprise et ne relancez pas le traitement depuis son début. Conservez l’archive et la sauvegarde tant que des attentes ou obligations d’audit en dépendent.