Pour essayer CyberTrain sans rien installer, ouvrez le bac à sable :
GitHub Codespaces ouvre le blog du tutoriel, la commande cybertrain et
la version épinglée de Spinel dans VS Code, dans votre navigateur. La même image tourne aussi en local avec Docker.
Prérequis
- Spinel, à la version de
Cybertrain::SPINEL_TAG(cybertrain/version.rb ;cybertrain doctorl’affiche, et leSPINEL_TAGde la CI dans .github/workflows/ci.yml est le même), une version de saeki-mototsune/spinel (Cybertrain::SPINEL_REPOSITORY), le fork de matz/spinel qui intègre les corrections dont CyberTrain a besoin avant une version amont ; non testé avec d’autres versions. Vous ne l’installez pas à la main : la commandecybertraincompile cette version dans~/.cybertrainla première fois qu’elle en a besoin (cybertrain setuple fait à la demande), sauf si unspinelde cette version est déjà dans lePATH— voir Comment Spinel est installé. - Pour le compiler : une chaîne de compilation C (
cc, ou le compilateur désigné parCC) etmake— Spinel compile chaque programme en C —, plusgitetcurl. - En-têtes et bibliothèque SQLite 3 (
libsqlite3-devsous Debian/Ubuntu ; fournis avec les Command Line Tools de Xcode sous macOS) — les modèles utilisent directement la FFI de Spinel, pas une gem. - En-têtes et bibliothèque zlib (
zlib1g-devsous Debian/Ubuntu ; dans le SDK de macOS) — les corps de requête gzip (request.decoded_body) sont décompressés par la zlib du système, liée de la même façon. - En-têtes et bibliothèque OpenSSL (
libssl-devsous Debian/Ubuntu) — chaque application les lie : le cookie de session etcookies.encryptedsont en AES-256-GCM par le paquetopensslde Spinel, que Spinel ne compile que si les en-têtes sont présents. Sous macOS, installez celui de Homebrew (brew install openssl@3), qui est keg-only, et placez-le dans les chemins du compilateur :export LIBRARY_PATH="$(brew --prefix openssl@3)/lib" CPATH="$(brew --prefix openssl@3)/include". - Ruby 3.2+ et RubyGems, pour la commande
cybertrainet pour l’aperçu CRuby du serveur de développement, qui demande aussi la bibliothèquefiddlede Ruby (elle a besoin de libffi) ; sansfiddle,cybertrain serverne lance que la boucle compilée. Une application déployée ne tourne jamais sur CRuby. Avec Ruby 3.2, la compilation de Spinel demande aussi la gemprism(ci-dessous).
cybertrain doctor vérifie ces outils et en-têtes, si le ruby du PATH
charge fiddle, ainsi que l’installation de Spinel ; quand un élément
requis manque, il affiche aussi la commande d’installation pour votre
plateforme (un fiddle manquant ne compte pas : le serveur tourne
quand même, compilé).
Autres paquetsprism avec Ruby 3.2 ; jemalloc, facultatif
- La compilation de Spinel demande la gem
prismde Ruby, que Ruby 3.3 et plus récent incluent ; avec Ruby 3.2,gem install prism(avec les en-têtes de développement de Ruby,ruby-devsous Debian/Ubuntu).cybertrain doctorle vérifie. - Un Spinel compilé avant l’installation des en-têtes OpenSSL n’a pas de paquet
openssl, et la compilation d’une application échoue alors ; lancezcybertrain setup --forceune fois qu’ils sont là pour le recompiler. Le même paquet sert à TLS (require "cybertrain/net/tls") et aux colonnes chiffrées (encrypts). - Le paquet de développement de jemalloc (
libjemalloc-dev;brew install jemalloc) est facultatif : une application n’en a besoin qu’une fois que sonspin.tomlindiqueallocator = "jemalloc", ligne quecybertrain newécrit en commentaire. Cela vaut la peine de l’activer en production : de 1,1 à 1,4 fois plus de requêtes par seconde sur examples/blog (docs/benchmark.md).
Installer la CLI
gem install cybertrain
cybertrain doctor
La première ligne installe la commande depuis RubyGems et la seconde vérifie les
prérequis ; le tutoriel continue à
partir de là, de cybertrain new à cybertrain build.
La commande cybertrain
cybertrain help affiche ces commandes :
cybertrain new NAME [--path DIR | --version V | --git URL [--ref R]] [--skip-spin]crée une application dans NAME, puis y lancespin locketSPIN_DEBUG=1 spin run gen, en installant d’abord Spinel si nécessaire (la CLI compile gen etbin/db.rbdans le mode debug de spin).cybertrain generate scaffold NAME field:type ...(aliasg scaffold) ajoute une ressource à l’application du répertoire courant.cybertrain generate authenticationy ajoute la connexion par adresse e-mail et mot de passe : les tables users et sessions, les modèlesUseretSession, les contrôleurs et vues de connexion et d’inscription, les routes, unbefore_actiondansApplicationControlleret un test (voir Ajouter la connexion). Avec--invite-only, il n’y a pas de page d’inscription : les utilisateurs sont créés avec./NAME user EMAIL, et le premier aussi sur une page/setupqui ne répond qu’à la machine du serveur elle-même, avec le jeton à usage unique qu’affiche son avertissement de démarrage, tant qu’aucun utilisateur n’existe.cybertrain generate attachment MODEL FIELD [--any]ajoute l’envoi d’un fichier à un modèle généré par scaffold : cinq colonnes de métadonnées, des méthodes et callbacks de modèle, une action de téléchargement, la route, le champ de formulaire et un test (voir Ajouter une image de couverture). Un champ de scaffoldcover:attachmentfait la même chose.cybertrain db migrategénère, applique les migrations en attente, puis génère à nouveau (SPIN_DEBUG=1 spin run gen; SPIN_DEBUG=1 spin run db -- migrate; SPIN_DEBUG=1 spin run gen) ;cybertrain migrationest conservé comme alias.cybertrain db COMMAND...lance toute autre commande de base de données aprèsSPIN_DEBUG=1 spin run gen:status,rollback [N](qui génère à nouveau ensuite),schema:dump,create.cybertrain server [PORT] [--spinel]démarre le serveur de développement (port 3000 par défaut). Juste après un changement, l’application tourne sous CRuby pendant que Spinel la compile en arrière-plan, et le binaire compilé reprend le port quand sa compilation réussit ; les réponses de l’application portentX-Cybertrain-Runtime: crubyouspinel(La boucle de développement).--spinelne lance que la boucle compilée, chaque changement attendant sa compilation (SPIN_DEBUG=1 spin run gen;spin build NAME -- --incrementalsi un fichier Ruby est plus récent quebuild/bin/NAME;spin run NAME, ouspin run NAME -- PORT).cybertrain buildcompile NAME avecapp/views/intégré et assembledist/(le binaire,public/,storage/,tmp/).cybertrain test [FILE|DIR ...] [-n NAME|-n /TEXT/]génère, compile tous les tests detest/en un seul programme (seulement quand quelque chose a changé) et l’exécute, en gardant les tests que les arguments désignent (voir Tester une application).cybertrain spin ARGS...lancespinavec le Spinel épinglé, depuis n’importe quel répertoire (cybertrain spin test,cybertrain spin run gen -- --check).cybertrain setup [--force]installe la version épinglée de Spinel dans~/.cybertrain, sauf si unspinelde cette version est déjà dans lePATH;--forcerecompile la copie sous~/.cybertrain.cybertrain doctorvérifie la chaîne de compilation C, les en-têtes SQLite, si Ruby chargefiddle(l’aperçu CRuby en a besoin) et l’installation de Spinel.cybertrain versionaffiche la version.
db, server et build s’exécutent dans une application ; NAME est le
[package] name de son spin.toml.
Comment Spinel est installé
Chaque commande qui lance spin (new, db, server, build, spin)
s’assure d’abord qu’un Spinel de la version de Cybertrain::SPINEL_TAG est
disponible. Un spinel du PATH (accompagné d’un spin) dont
spinel --version indique cette version est utilisé tel quel ; sinon, la
copie que cybertrain conserve sous ~/.cybertrain/spinel/<SPINEL_TAG>/
est utilisée ; sinon, cybertrain compile cette copie à partir du tag de
version de Cybertrain::SPINEL_REPOSITORY (git clone, make deps,
make -j, make install PREFIX=...), une seule fois, en quelques minutes. Le
journal de compilation est ~/.cybertrain/log/spinel-<SPINEL_TAG>-build.log
(ses dernières lignes sont affichées si une étape échoue).
S’il manque un
outil nécessaire à la compilation, cybertrain indique lequel et affiche la
commande d’installation pour votre plateforme avant de commencer. Un spinel
d’une autre version présent dans le PATH n’est jamais utilisé ni
modifié : cybertrain conserve sa propre copie (et le signale quand il
l’installe).
cybertrain setup fait la même chose à la demande et, chaque fois que c’est sa
propre copie qui est utilisée, affiche la ligne qui la place dans le PATH,
pour lancer spin vous-même :
export PATH="$HOME/.cybertrain/bin:$PATH"
~/.cybertrain/bin contient des liens spinel et spin vers la version
utilisée, la ligne reste donc valable après un changement de version ;
cybertrain spin ... n’a besoin d’aucun PATH.
Variables d’environnementCYBERTRAIN_HOME déplace ~/.cybertrain, CYBERTRAIN_SPINEL_HOME utilise une installation existante
Deux variables d’environnement remplacent tout cela :
CYBERTRAIN_HOMEremplace~/.cybertrain(un chemin sans espaces, guillemets,$ni:, que le Makefile de Spinel et lePATHne supportent pas).CYBERTRAIN_SPINEL_HOME=PREFIXimpose une installation existante :cybertrainutilise alors lespinelet lespindePREFIX/bin(ou dePREFIXlui-même, sispinels’y trouve directement) et s’arrête sur une erreur s’ils ne sont pas de cette version.
La gem et le framework
gem install cybertrain installe une commande, pas le framework. La gem est la
commande cybertrain, du Ruby pur qui s’exécute sur votre machine sous CRuby
(3.2 ou plus récent) et appelle pour vous l’outil spin de Spinel ; ni le
framework ni Spinel ne sont dans la gem. Le framework est un paquet Spinel dont
votre application dépend dans son spin.toml : Spinel le compile à
l’avance avec votre code, et c’est la partie qui est livrée. Le binaire de
dist/ tourne sans Ruby, sans la gem et sans Spinel. Le code de
l’application, framework compris, ne tourne aussi sous CRuby qu’en
développement : cybertrain server sert un aperçu CRuby de
l’application jusqu’à ce que le binaire compilé prenne le relais.
Ce que cybertrain new écrit
cybertrain new écrit l’application avec un spin.toml qui pointe vers la
version correspondant à la CLI (cybertrain = { git =
"https://github.com/saeki-mototsune/cybertrain", ref = "vX.Y.Z" }, où
X.Y.Z est ce qu’affiche cybertrain version), s’assure
que Spinel est installé, puis lance spin lock (spin récupère le framework dans
son cache, ~/.cache/spin/packages/, et épingle le commit dans spin.lock) et
SPIN_DEBUG=1 spin run gen, un peu comme rails new lance bundle install, et affiche les
étapes suivantes. Rien du framework n’est copié dans l’application ;
commitez spin.toml et spin.lock. bin/<app>.rb et bin/db.rb requièrent
cybertrain/core, le framework sans ses sous-systèmes optionnels ; les
générateurs qui en demandent un ajoutent sa ligne
(Sous-systèmes).
Si Spinel ou l’une des deux étapes spin échoue, les fichiers restent en
place, new sort avec le code 1 et affiche ce qu’il faut lancer une fois la
cause corrigée (pour Spinel : cybertrain setup, puis
cybertrain spin lock && SPIN_DEBUG=1 cybertrain spin run gen dans le nouveau répertoire).
Quatre options changent ce qu’elle écrit et lance :
--skip-spinse contente d’écrire les fichiers : pas d’installation de Spinel, pas despin lock, pas despin run gen.--path DIRfait plutôt dépendre l’application d’une copie locale du dépôt (--path ~/src/cybertrain, là où se trouve la copie, pour travailler sur CyberTrain lui-même).--git URL [--ref R]fait dépendre l’application du framework situé à URL (à la branche ou au tag R).--version Vfait dépendre l’application de la version V d’unspin-index(cybertrain = "V"), une fois que le framework y sera : voir Une version de l’index.
N’indiquez qu’une seule des options --path, --version et --git ;
--ref exige --git.
Une version de l’index
Un spin-index est la liste de paquets dans laquelle spin cherche un nom. Le
framework n’y est pas encore : d’ici là, spin lock dans une application
créée avec --version répond not in the index: cybertrain, et le tag que
new écrit par défaut est la façon de dépendre d’une version. Une fois qu’il y
sera, cybertrain new NAME --version X.Y.Z écrira cybertrain = "X.Y.Z", spin
trouvera le commit de cette version dans l’index, et spin.lock fixera les
trois mêmes choses que pour le tag (la version, le dépôt et le commit) :
toutes les commandes et le workflow de CI que new écrit fonctionnent donc
comme par défaut. Trois choses diffèrent de ce qu’un Gemfile laisse
attendre :
- Nommez une seule version. Parmi les versions qui satisfont une
contrainte, spin choisit la plus basse, pas la plus récente :
"~> X.Y"est la version la plus basse de l’index à partir de X.Y et avant la version majeure suivante (seul"~> X.Y.Z"reste dans X.Y), et reste celle-là quand d’autres sont publiées ensuite. Écrivez donc la version exacte, celle qu’affichecybertrain version;newaffiche une remarque quand V est autre chose. - Spinel vient toujours de la commande
cybertrain. Une entrée de l’index ne nomme aucune version de Spinel. Le framework est écrit pour une seule version et testé avec elle, celle quecybertrain setupcompile, et la commandecybertrainde la même version l’installe. Un simplespin add cybertraindans un projet compilé avec un autre Spinel n’est pas testé. - spin lit sa propre copie de l’index. Il clone l’index une seule fois,
dans
~/.cache/spin/, etspin lockne met pas cette copie à jour ;spin search cybertrainle fait, et affiche la version la plus récente.
Passer une application à une nouvelle version
La gem et le framework sont publiés à partir du même tag, leurs versions
correspondent donc : la gem X.Y.Z crée des applications qui dépendent du
framework vX.Y.Z. Pour passer une application à une nouvelle version, mettez
à jour la gem, faites pointer spin.toml vers le nouveau tag, puis lancez, dans
l’application :
rm spin.lock
cybertrain spin lock
cybertrain spin run gen
spin lock garde le commit qu’il a verrouillé pour une dépendance git, quel
que soit le ref désormais écrit dans spin.toml : c’est pourquoi le
verrou est supprimé d’abord. Dans une application qui a d’autres dépendances,
vous pouvez à la place supprimer de spin.lock la seule table
[lock.cybertrain] et garder les autres verrous. Une application qui dépend
d’une version de l’index (cybertrain = "X.Y.Z") n’a pas besoin du rm :
là, spin lock déplace le verrou.
Pour une application qui dépend d’une version de l’index,
lancez d’abord cybertrain spin search cybertrain, qui met à jour la copie de
l’index de spin, puis remplacez la version sur la ligne cybertrain = de
spin.toml par la nouvelle version et lancez cybertrain spin lock puis cybertrain spin run gen.
La commande vérifie que les deux correspondent. Avant que server, build,
db, test ou generate ne lance spin ou n’écrive un fichier, elle compare
la version du framework que spin compilerait, celle qui est verrouillée dans
le spin.lock de l’application, avec la sienne (cybertrain version) :
c’est la commande, et non l’application, qui décide de la version de Spinel
qui compile l’application, et ses modèles et générateurs sont écrits pour sa
propre version du framework. Quand les versions diffèrent, la commande
s’arrête avec le code 1 :
error: this application's framework is cybertrain X.Y.Z (spin.lock), but this cybertrain command is A.B.C.
The command decides the Spinel release, the templates and the generators, so the two must be the same version. Either
gem install cybertrain -v X.Y.Z # the command the application is on
or point the cybertrain dependency in spin.toml at A.B.C (ref = "vA.B.C"), then relock from nothing (spin lock keeps a locked git commit)
rm spin.lock && cybertrain spin lock
Faites l’un ou l’autre. cybertrain spin ... n’est jamais vérifié, donc
cybertrain spin lock s’exécute toujours. Avec une dépendance git, modifier
spin.toml ne change rien, et spin lock ensuite non plus : spin
continue de compiler le commit de spin.lock tant que ce verrou n’est pas
supprimé, d’où le rm. Avec une version de l’index, le message nomme
cybertrain = "A.B.C" et cybertrain spin lock seul ; spin ne compile
la version verrouillée que tant que spin.toml l’autorise encore : la
version que nomme spin.toml est donc comparée dès qu’elle diffère du
verrou, et une plage ("~> X.Y") qui n’autorise plus la version verrouillée
est refusée tant que cybertrain spin lock n’a pas été lancé. Une
application qui dépend d’une copie locale du framework (path = ...) n’est
pas vérifiée. Une application sans spin.lock est comparée à la version que
nomme son spin.toml ("X.Y.Z" ou ref = "vX.Y.Z") ; une branche, un
commit ou une plage n’en nomme aucune, elle n’est donc pas vérifiée.
Une application écrite pour 0.4 a quelques changements à faire (chaque session
prend fin une fois, OpenSSL est lié, un segment de route contenant un point a
besoin de format: false, etc.) : voir Mettre à jour une application écrite pour 0.4.