To try CyberTrain without installing anything, open the playground:
GitHub Codespaces opens the tutorial's blog, the cybertrain command and
the pinned Spinel release in VS Code in your browser. The same image also runs locally under Docker.
Requirements
- Spinel, at the release in
Cybertrain::SPINEL_TAG(cybertrain/version.rb;cybertrain doctorprints it, and CI'sSPINEL_TAGin .github/workflows/ci.yml is the same), a release of saeki-mototsune/spinel (Cybertrain::SPINEL_REPOSITORY), the fork of matz/spinel that carries the fixes CyberTrain needs ahead of an upstream release; untested against other versions. You do not install it by hand: thecybertraincommand builds that release into~/.cybertrainthe first time it needs it (cybertrain setupdoes that on request), unless aspinelof that release is already onPATH— see How Spinel is installed. - To build it: a C toolchain (
cc, or the compilerCCnames) andmake— Spinel compiles every program to C — plusgitandcurl. - SQLite 3 headers/library (
libsqlite3-devon Debian/Ubuntu; present with Xcode's command line tools on macOS) — models use Spinel's FFI directly, not a gem. - zlib headers/library (
zlib1g-devon Debian/Ubuntu; in the macOS SDK) — gzip request bodies (request.decoded_body) are inflated through the system zlib, bound the same way. - OpenSSL headers/library (
libssl-devon Debian/Ubuntu) — every application links them: the session cookie andcookies.encryptedare AES-256-GCM through Spinel'sopensslpackage, which Spinel builds only when the headers are there. On macOS install Homebrew's (brew install openssl@3), which is keg-only, and put it on the compiler's paths:export LIBRARY_PATH="$(brew --prefix openssl@3)/lib" CPATH="$(brew --prefix openssl@3)/include". - Ruby 3.2+ and RubyGems, for the
cybertraincommand and the development server's CRuby preview, which also needs Ruby'sfiddlelibrary (it needs libffi); withoutfiddle,cybertrain serverruns the compiled loop only. A deployed application never runs on CRuby. On Ruby 3.2, building Spinel also needs theprismgem (below).
cybertrain doctor checks these tools and headers, whether the ruby on
PATH loads fiddle, and the Spinel install; when a required one is
missing it also prints the install command for your platform (a missing
fiddle does not count: the server still runs, compiled).
More packagesprism on Ruby 3.2; jemalloc, optional
- Building Spinel needs Ruby's
prismgem, which Ruby 3.3 and newer bundle; on Ruby 3.2,gem install prism(with Ruby's development headers,ruby-devon Debian/Ubuntu).cybertrain doctorchecks it. - A Spinel built before the OpenSSL headers were installed has no
opensslpackage, and an application then fails to build; runcybertrain setup --forceonce they are there to rebuild it. The same package serves TLS (require "cybertrain/net/tls") and encrypted columns (encrypts). - jemalloc's development package (
libjemalloc-dev;brew install jemalloc) is optional: an app needs it only once itsspin.tomlsaysallocator = "jemalloc", whichcybertrain newwrites commented out. It is worth turning on for production: 1.1 to 1.4 times the requests per second on examples/blog (docs/benchmark.md).
Install the CLI
gem install cybertrain
cybertrain doctor
The first line installs the command from RubyGems and the second checks the
requirements; the tutorial goes on
from there, from cybertrain new to cybertrain build.
The cybertrain command
cybertrain help prints these commands:
cybertrain new NAME [--path DIR | --version V | --git URL [--ref R]] [--skip-spin]creates an application in NAME, then runsspin lockandSPIN_DEBUG=1 spin run genin it, installing Spinel first when it is needed (the CLI builds gen andbin/db.rbin spin's debug mode).cybertrain generate scaffold NAME field:type ...(aliasg scaffold) adds a resource to the application in the current directory.cybertrain generate authenticationadds email-and-password sign-in to it: users and sessions tables,UserandSessionmodels, the sign-in and sign-up controllers and views, the routes, abefore_actioninApplicationControllerand a test (see Add sign-in). With--invite-onlythere is no sign-up page: users are created with./NAME user EMAIL, and the first one also at a/setuppage that answers only to the server's own machine, with the one-time token its boot warning prints, while no user exists.cybertrain generate attachment MODEL FIELD [--any]adds a file upload to a scaffolded model: five metadata columns, model methods and callbacks, a download action, the route, the form field and a test (see Add a cover image). A scaffold fieldcover:attachmentdoes the same.cybertrain db migrategenerates, applies pending migrations, and generates again (SPIN_DEBUG=1 spin run gen; SPIN_DEBUG=1 spin run db -- migrate; SPIN_DEBUG=1 spin run gen);cybertrain migrationis kept as an alias.cybertrain db COMMAND...runs any other database command afterSPIN_DEBUG=1 spin run gen:status,rollback [N](which generates again afterwards),schema:dump,create.cybertrain server [PORT] [--spinel]starts the development server (default port 3000). Right after a change the application runs under CRuby while Spinel builds it in the background, and the compiled binary takes the port when its build succeeds; the application's responses carryX-Cybertrain-Runtime: crubyorspinel(The development loop).--spinelruns the compiled loop only, every change waiting for its build (SPIN_DEBUG=1 spin run gen;spin build NAME -- --incrementalwhen a Ruby file is newer thanbuild/bin/NAME;spin run NAME, orspin run NAME -- PORT).cybertrain buildbuilds NAME withapp/views/embedded and assemblesdist/(the binary,public/,storage/,tmp/).cybertrain test [FILE|DIR ...] [-n NAME|-n /TEXT/]generates, compiles every test undertest/into one program (again only when something changed) and runs it, keeping the tests the arguments name (see Testing an app).cybertrain spin ARGS...runsspinwith the pinned Spinel from any directory (cybertrain spin test,cybertrain spin run gen -- --check).cybertrain setup [--force]installs the pinned Spinel release into~/.cybertrainunless aspinelof that release is already onPATH;--forcerebuilds the copy under~/.cybertrain.cybertrain doctorchecks the C toolchain, the SQLite headers, whether Ruby loadsfiddle(the CRuby preview needs it) and the Spinel install.cybertrain versionprints the version.
db, server and build run inside an application; NAME is the
[package] name in its spin.toml.
How Spinel is installed
Every command that runs spin (new, db, server, build, spin) first
makes sure a Spinel of the release in Cybertrain::SPINEL_TAG is available. A
spinel on PATH (with a spin) whose spinel --version reports that
release is used as it is; otherwise the copy cybertrain keeps under
~/.cybertrain/spinel/<SPINEL_TAG>/; otherwise cybertrain builds that
copy from the release tag of Cybertrain::SPINEL_REPOSITORY (git clone,
make deps, make -j, make install PREFIX=...), once, in a few minutes,
logging to ~/.cybertrain/log/spinel-<SPINEL_TAG>-build.log (its last
lines are printed if a step fails).
If a tool the build needs is missing,
cybertrain says which and prints the install command for your platform
before it starts. A spinel of another release on PATH is never used or
touched: cybertrain keeps its own copy (and says so when it installs it).
cybertrain setup does the same on request and, whenever its own copy is
the one in use, prints the line that puts it on PATH, for running spin
yourself:
export PATH="$HOME/.cybertrain/bin:$PATH"
~/.cybertrain/bin holds spinel and spin links to the release in use, so
the line survives a release bump; cybertrain spin ... needs no PATH at all.
Environment variablesCYBERTRAIN_HOME moves ~/.cybertrain, CYBERTRAIN_SPINEL_HOME uses an existing install
Two environment variables override all this:
CYBERTRAIN_HOMEreplaces~/.cybertrain(a path without spaces, quotes,$or:, which Spinel's Makefile andPATHcannot take).CYBERTRAIN_SPINEL_HOME=PREFIXforces an existing install:cybertrainthen uses thespinelandspininPREFIX/bin(or inPREFIXitself, ifspinelis directly in it) and stops with an error if they are not that release.
The gem and the framework
gem install cybertrain installs a command, not the framework. The gem is
the cybertrain command, plain Ruby that runs on your machine under CRuby
(3.2 or newer) and calls Spinel's spin tool for you; neither the framework
nor Spinel is in the gem. The framework is a Spinel package your app depends
on in its spin.toml: Spinel compiles it together with your code ahead of
time, and it is the part that ships. The binary in dist/ runs without
Ruby, the gem or Spinel. Only in development does the application's code,
the framework included, also run under CRuby: cybertrain server serves a
CRuby preview of the application until the compiled binary takes over.
What cybertrain new writes
cybertrain new writes the application with its spin.toml pointing at
the release matching the CLI (cybertrain = { git =
"https://github.com/saeki-mototsune/cybertrain", ref = "vX.Y.Z" }, where
X.Y.Z is what cybertrain version prints), makes
sure Spinel is installed, then runs spin lock (spin fetches the framework
into its cache, ~/.cache/spin/packages/, and pins the commit in
spin.lock) and SPIN_DEBUG=1 spin run gen, much as rails new runs
bundle install, and prints the next steps. Nothing of the framework is copied into the app;
commit spin.toml and spin.lock. bin/<app>.rb and bin/db.rb require
cybertrain/core, the framework without its optional subsystems; the
generators that need one add its line
(Subsystems).
If Spinel or one of the two spin steps fails, the files stay, new exits
with 1 and prints what to run once the cause is fixed (for Spinel:
cybertrain setup, then cybertrain spin lock && SPIN_DEBUG=1 cybertrain spin
run gen in the new directory).
Four options change what it writes and runs:
--skip-spinonly writes the files: no Spinel install, nospin lock, nospin run gen.--path DIRdepends on a local checkout instead (--path ~/src/cybertrain, wherever the checkout is, when working on CyberTrain itself).--git URL [--ref R]depends on the framework at URL (at branch or tag R).--version Vdepends on release V in aspin-index(cybertrain = "V"), once the framework is on one: see An index version.
Give only one of --path, --version and --git; --ref needs --git.
An index version
A spin-index is the list of packages spin looks a name up in. The
framework is not on one yet: until it is, spin lock in an app created with
--version answers not in the index: cybertrain, and the tag that new
writes by default is the way to depend on a release. Once it is,
cybertrain new NAME --version X.Y.Z writes cybertrain = "X.Y.Z", spin
finds that release's commit in the index, and spin.lock pins the same three
things it pins for the tag (the version, the repository and the commit), so
every command and the CI workflow new writes work as they do by default.
Three things differ from what a Gemfile leads you to expect:
- Name one release. Of the releases that satisfy a constraint, spin
selects the lowest, not the newest:
"~> X.Y"is the lowest release in the index from X.Y up to the next major version (only"~> X.Y.Z"stays inside X.Y), and stays that one when later ones are published. So write the exact version, the onecybertrain versionprints;newprints a note when V is anything else. - Spinel still comes from the
cybertraincommand. An index entry names no Spinel release. The framework is written for and tested with one, the release thatcybertrain setupbuilds, and thecybertraincommand of the same version installs it. Plainspin add cybertrainin a project built with another Spinel is untested. - spin reads its own copy of the index. It clones the index once, into
~/.cache/spin/, andspin lockdoes not update that copy;spin search cybertraindoes, and prints the newest release.
Moving an app to a new release
The gem and the framework are released from the same tag, so their versions
match: the X.Y.Z gem writes apps that depend on framework vX.Y.Z. To move an
app to a new release, update the gem, point spin.toml at the new tag, then
run, in the app:
rm spin.lock
cybertrain spin lock
cybertrain spin run gen
spin lock keeps the commit it has locked for a git dependency, whatever
ref has become in spin.toml, which is why the lock is removed first. In
an app with other dependencies you can delete only the [lock.cybertrain]
table from spin.lock instead, and keep the other pins. An app that depends
on a version from the index (cybertrain = "X.Y.Z") needs no rm: there
spin lock moves the pin.
For an app that depends on an index version, run
cybertrain spin search cybertrain first, which updates spin's copy of the
index, then change the version on the cybertrain = line of spin.toml to
the new release and run cybertrain spin lock and cybertrain spin run gen.
The command checks that the two match. Before server, build, db,
test or generate runs spin or writes a file, it compares the version of
the framework spin would build, the one locked in the app's spin.lock,
with its own (cybertrain version): the command, not the app, decides which
Spinel release compiles the app, and its templates and generators are
written for its own release of the framework. When the versions differ, the
command stops with exit status 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
Do one or the other. cybertrain spin ... is never checked, so cybertrain
spin lock always runs. With a git dependency, editing spin.toml changes
nothing, and neither does spin lock after it: spin goes on building the
commit in spin.lock until that lock is removed, hence the rm. With a
version from the index, the message names cybertrain = "A.B.C" and
cybertrain spin lock alone; spin builds the locked release only while
spin.toml still allows it, so the version spin.toml names is compared
as soon as it differs from the lock, and a range ("~> X.Y") that no longer
allows the locked release is refused until cybertrain spin lock has run.
An app that depends on a checkout of the framework (path = ...) is not
checked. An app with no spin.lock is checked against the release its
spin.toml names ("X.Y.Z" or ref = "vX.Y.Z"); a branch, a commit or a
range names none, so it is not checked.
An application written for 0.4 has a few changes to make (every session
ends once, OpenSSL is linked, a dotted route segment needs format: false,
and more): see Upgrading an application from 0.4.