何もインストールせずに CyberTrain を試すには、プレイグラウンドを開いてください:GitHub Codespaces が、チュートリアルのブログ、cybertrain コマンド、固定された Spinel のリリースを、ブラウザーの中の VS Code で開きます。同じイメージは Docker を使ってローカルでも動きます。
必要なもの
- Spinel の、
Cybertrain::SPINEL_TAGのリリース(cybertrain/version.rb。cybertrain doctorが表示し、.github/workflows/ci.yml のSPINEL_TAGと同じリリース)。saeki-mototsune/spinel(Cybertrain::SPINEL_REPOSITORY)のリリースで、CyberTrain が必要とする修正を本家のリリースより先に取り込んだ matz/spinel のフォークです。他のバージョンでは未テストです。手動でインストールする必要はありません:cybertrainコマンドが、初めて必要になったときにそのリリースを~/.cybertrainにビルドします(cybertrain setupは求めに応じてそれを行います)。ただし、そのリリースのspinelがすでにPATH上にある場合は除きます — Spinel のインストールの仕組みを参照してください。 - そのビルドには:C ツールチェーン(
cc、またはCCで指定したコンパイラ)とmake— Spinel はすべてのプログラムを C にコンパイルします — さらにgitとcurl。 - SQLite 3 のヘッダーとライブラリ(Debian/Ubuntu では
libsqlite3-dev。macOS では Xcode のコマンドラインツールに含まれています) — モデルは gem ではなく、Spinel の FFI を直接使います。 - zlib のヘッダーとライブラリ(Debian/Ubuntu では
zlib1g-dev。macOS では SDK に含まれています) — gzip されたリクエストボディ(request.decoded_body)は、同じ方法でバインドしたシステムの zlib で展開されます。 - OpenSSL のヘッダーとライブラリ(Debian/Ubuntu では
libssl-dev) — どのアプリケーションもリンクします:セッション Cookie とcookies.encryptedは Spinel のopensslパッケージによる AES-256-GCM で、Spinel はヘッダーがあるときだけこのパッケージをビルドします。macOS では Homebrew のもの(brew install openssl@3)を入れ、keg-only なのでコンパイラのパスに加えます:export LIBRARY_PATH="$(brew --prefix openssl@3)/lib" CPATH="$(brew --prefix openssl@3)/include"。 - Ruby 3.2+ と RubyGems。
cybertrainコマンドと、開発サーバーの CRuby プレビューに必要です。プレビューにはさらに Ruby のfiddleライブラリが必要です(libffi が要ります)。fiddleがなければ、cybertrain serverはコンパイル版のループだけを実行します。デプロイしたアプリケーションが CRuby 上で動くことはありません。Ruby 3.2 では、Spinel のビルドにprismgem も必要です(下記)。
cybertrain doctor はこれらのツールとヘッダー、PATH 上の ruby が fiddle を読み込めるかどうか、Spinel のインストールを確認します。必要なものが欠けている場合は、プラットフォームに応じたインストールコマンドも表示します(fiddle がないことは数えません:サーバーはコンパイル版で動くからです)。
その他のパッケージRuby 3.2 での prism、任意の jemalloc
- Spinel のビルドには Ruby の
prismgem が必要で、Ruby 3.3 以上には同梱されています。Ruby 3.2 ではgem install prismを実行します(Ruby の開発用ヘッダーが必要です。Debian/Ubuntu ならruby-dev)。cybertrain doctorが確認します。 - OpenSSL のヘッダーを入れる前にビルドした Spinel には
opensslパッケージがなく、アプリケーションのビルドが失敗します。ヘッダーを入れたらcybertrain setup --forceで作り直してください。同じパッケージが TLS(require "cybertrain/net/tls")と暗号化されたカラム(encrypts)にも使われます。 - jemalloc の開発用パッケージ(
libjemalloc-dev、brew install jemalloc)は任意です:アプリがこれを必要とするのは、そのspin.tomlにallocator = "jemalloc"と書いたときだけで、cybertrain newはこの行をコメントアウトして書き出します。本番環境では有効にする価値があります:examples/blog で毎秒のリクエスト数が 1.1〜1.4 倍になります(docs/benchmark.md)。
CLI をインストールする
gem install cybertrain
cybertrain doctor
1 行目で RubyGems からコマンドをインストールし、2 行目で必要なものを確認します。そこから先は、cybertrain new から cybertrain build まで、チュートリアルが続けます。
cybertrain コマンド
cybertrain help はこれらのコマンドを表示します:
cybertrain new NAME [--path DIR | --version V | --git URL [--ref R]] [--skip-spin]は NAME にアプリケーションを作成し、その中でspin lockとSPIN_DEBUG=1 spin run genを実行します。必要なら先に Spinel をインストールします(CLI は gen とbin/db.rbを spin のデバッグモードでビルドします)。cybertrain generate scaffold NAME field:type ...(エイリアスはg scaffold)は、カレントディレクトリのアプリケーションにリソースを追加します。cybertrain generate authenticationは、そのアプリケーションにメールアドレスとパスワードによるサインインを追加します:users と sessions のテーブル、UserとSessionのモデル、サインインとサインアップのコントローラーとビュー、ルート、ApplicationControllerのbefore_action、そしてテストです(サインインを追加するを参照)。--invite-onlyを付けるとサインアップのページはありません:ユーザーは./NAME user EMAILで作成し、ユーザーがまだいない間は、最初のユーザーを/setupページでも作成できます。このページはサーバー自身のマシンにだけ応答し、起動時の警告が表示するワンタイムトークンを必要とします。cybertrain generate attachment MODEL FIELD [--any]は、スキャフォールド済みのモデルにファイルアップロードを追加します:5 つのメタデータカラム、モデルのメソッドとコールバック、ダウンロードのアクション、ルート、フォームのフィールド、そしてテストです(カバー画像を追加するを参照)。スキャフォールドのフィールドcover:attachmentも同じことを行います。cybertrain db migrateは生成を行い、未適用のマイグレーションを適用して、もう一度生成します(SPIN_DEBUG=1 spin run gen; SPIN_DEBUG=1 spin run db -- migrate; SPIN_DEBUG=1 spin run gen)。cybertrain migrationもエイリアスとして残されています。cybertrain db COMMAND...はSPIN_DEBUG=1 spin run genの後に、その他のデータベースコマンドを実行します:status、rollback [N](実行後にもう一度生成します)、schema:dump、create。cybertrain server [PORT] [--spinel]は開発サーバーを起動します(デフォルトのポートは 3000)。変更の直後はアプリケーションが CRuby で動き、その間に Spinel がバックグラウンドでビルドし、ビルドが成功するとコンパイル済みのバイナリがポートを引き継ぎます。アプリケーションのレスポンスにはX-Cybertrain-Runtime: crubyかspinelが付きます(開発ループ)。--spinelはコンパイル版のループだけを実行し、変更のたびにビルドを待ちます(SPIN_DEBUG=1 spin run gen。build/bin/NAMEより新しい Ruby ファイルがあればspin build NAME -- --incremental。spin run NAME、またはspin run NAME -- PORT)。cybertrain buildはapp/views/を埋め込んで NAME をビルドし、dist/(バイナリ、public/、storage/、tmp/)を組み立てます。cybertrain test [FILE|DIR ...] [-n NAME|-n /TEXT/]は生成し、test/以下のすべてのテストを 1 つのプログラムにコンパイルして(何かが変わったときだけ)実行し、引数が指定したテストだけを残します(アプリをテストするを参照)。cybertrain spin ARGS...は、固定された Spinel でspinを任意のディレクトリから実行します(cybertrain spin test、cybertrain spin run gen -- --check)。cybertrain setup [--force]は固定された Spinel のリリースを~/.cybertrainにインストールします(そのリリースのspinelがすでにPATH上にある場合を除く)。--forceは~/.cybertrain以下のコピーを再ビルドします。cybertrain doctorは C ツールチェーン、SQLite のヘッダー、Ruby がfiddleを読み込めるかどうか(CRuby プレビューに必要です)、Spinel のインストールを確認します。cybertrain versionはバージョンを表示します。
db、server、build はアプリケーションの中で実行します。NAME はそのアプリケーションの spin.toml にある [package] name です。
Spinel のインストールの仕組み
spin を実行するすべてのコマンド(new、db、server、build、spin)は、まず Cybertrain::SPINEL_TAG のリリースの Spinel が使えることを確かめます。PATH 上の spinel(spin を伴うもの)の spinel --version がそのリリースを報告すれば、それをそのまま使います。そうでなければ、cybertrain が ~/.cybertrain/spinel/<SPINEL_TAG>/ 以下に置いているコピーを使います。それもなければ、cybertrain が Cybertrain::SPINEL_REPOSITORY のリリースタグからそのコピーをビルドします(git clone、make deps、make -j、make install PREFIX=...)。ビルドは一度だけで、数分かかります。ビルドのログは ~/.cybertrain/log/spinel-<SPINEL_TAG>-build.log です(手順が失敗すると、その最後の数行が表示されます)。
ビルドに必要なツールが欠けている場合、cybertrain はビルドを始める前に、どれが足りないかを伝え、プラットフォームに応じたインストールコマンドを表示します。PATH 上にある別リリースの spinel が使われたり変更されたりすることはありません:cybertrain は自前のコピーを持ちます(そしてインストールするときにそう伝えます)。
cybertrain setup は同じことを求めに応じて行います。さらに、自前のコピーが使われている場合は、spin を自分で実行するために、それを PATH に加える行を表示します:
export PATH="$HOME/.cybertrain/bin:$PATH"
~/.cybertrain/bin には使用中のリリースを指す spinel と spin のリンクがあるので、リリースが上がってもこの行はそのまま使えます。cybertrain spin ... には PATH はまったく必要ありません。
環境変数CYBERTRAIN_HOME は ~/.cybertrain を移し、CYBERTRAIN_SPINEL_HOME は既存のインストールを使う
2 つの環境変数がこれらすべてを上書きします:
CYBERTRAIN_HOMEは~/.cybertrainの代わりになります(スペース、引用符、$、:を含まないパスにします。Spinel の Makefile とPATHがこれらを扱えないためです)。CYBERTRAIN_SPINEL_HOME=PREFIXは既存のインストールを強制します:そのときcybertrainはPREFIX/binにある(spinelがPREFIXの直下にあればPREFIX自体にある)spinelとspinを使い、それらがそのリリースでなければエラーで停止します。
gem とフレームワーク
gem install cybertrain がインストールするのはコマンドであり、フレームワークではありません。gem は cybertrain コマンドで、手元のマシン上で CRuby(3.2 以降)で動く素の Ruby であり、Spinel の spin ツールを代わりに呼び出します。フレームワークも Spinel も gem には含まれません。フレームワークは、アプリが spin.toml で依存する Spinel のパッケージです:Spinel がそれをあなたのコードと一緒に事前(AOT)コンパイルし、出荷されるのはこの部分です。dist/ のバイナリは Ruby、gem、Spinel なしで動きます。アプリケーションのコードが、フレームワークも含めて CRuby でも動くのは開発時だけです:cybertrain server は、コンパイル済みのバイナリが引き継ぐまで、アプリケーションの CRuby プレビューを配信します。
cybertrain new が書き出すもの
cybertrain new はアプリケーションを書き出し、その spin.toml は CLI と一致するリリースを指します(cybertrain = { git =
"https://github.com/saeki-mototsune/cybertrain", ref = "vX.Y.Z" }。X.Y.Z は cybertrain version が表示するもの)。次に Spinel がインストールされていることを確認し、spin lock(spin がフレームワークをキャッシュ ~/.cache/spin/packages/ に取得し、コミットを spin.lock に固定します)と SPIN_DEBUG=1 spin run gen を実行します。rails new が bundle install を実行するのと同じようなものです。そして次の手順を表示します。フレームワークのファイルはアプリに一切コピーされません。spin.toml と spin.lock をコミットしてください。bin/<app>.rb と bin/db.rb は、オプションのサブシステムを除いたフレームワーク cybertrain/core を require します。サブシステムが必要なジェネレーターは、その行を追加します(サブシステム)。
Spinel のインストールか、2 つの spin ステップのいずれかが失敗した場合、ファイルは残したまま new は終了コード 1 で終了し、原因を解消した後に実行すべきコマンドを表示します(Spinel の場合:cybertrain setup を実行し、続いて新しいディレクトリで cybertrain spin lock && SPIN_DEBUG=1 cybertrain spin run gen)。
4 つのオプションが、書き出すものと実行するものを変えます:
--skip-spinはファイルを書き出すだけです:Spinel のインストールも、spin lockも、spin run genも行いません。--path DIRは代わりにローカルのチェックアウトに依存します(CyberTrain 自体を開発するときは、チェックアウトのある場所に合わせて--path ~/src/cybertrain)。--git URL [--ref R]は URL にあるフレームワーク(ブランチまたはタグ R)に依存します。--version Vは、フレームワークがspin-indexに登録された後、そこにあるリリース V に依存します(cybertrain = "V"):インデックスのバージョンを見てください。
--path、--version、--git はひとつだけ指定してください。--ref には --git が必要です。
インデックスのバージョン
spin-index は、spin がパッケージの名前を引く一覧です。フレームワークはまだ登録されていません:登録されるまでは、--version で作ったアプリで spin lock を実行すると not in the index: cybertrain と返り、リリースに依存する方法は new が既定で書き出すタグです。登録された後は、cybertrain new NAME --version X.Y.Z が cybertrain = "X.Y.Z" を書き出し、spin がそのリリースのコミットをインデックスから見つけ、spin.lock はタグの場合と同じ 3 つ(バージョン、リポジトリ、コミット)を固定します。そのため、どのコマンドも、new が書き出す CI のワークフローも、既定の場合と同じように動きます。Gemfile から想像するものと違う点が 3 つあります:
- リリースをひとつ指定します。 制約を満たすリリースのうち、spin が選ぶのは最新ではなく最も低いものです:
"~> X.Y"は、X.Y 以上で次のメジャーバージョン未満のリリースのうち、インデックスにある最も低いものです(X.Y の範囲にとどまるのは"~> X.Y.Z"だけです)。後のリリースが公開されても、それは変わりません。ですから、正確なバージョン、つまりcybertrain versionが表示するものを書いてください。V がそれ以外のとき、newは注意を表示します。 - Spinel は引き続き
cybertrainコマンドが用意します。 インデックスの項目は Spinel のリリースを指定しません。フレームワークはひとつのリリース、つまりcybertrain setupがビルドするものに向けて書かれ、それでテストされていて、同じバージョンのcybertrainコマンドがそれをインストールします。別の Spinel でビルドするプロジェクトでspin add cybertrainだけを実行する使い方は、テストされていません。 - spin はインデックスの手元のコピーを読みます。 spin はインデックスを一度だけ
~/.cache/spin/にクローンし、spin lockはそのコピーを更新しません。spin search cybertrainは更新し、最新のリリースを表示します。
アプリを新しいリリースに移行する
gem とフレームワークは同じタグからリリースされるため、バージョンは一致します:X.Y.Z の gem は、フレームワーク vX.Y.Z に依存するアプリを書き出します。アプリを新しいリリースに移行するには、gem を更新し、spin.toml を新しいタグに向けてから、アプリの中で次を実行します:
rm spin.lock
cybertrain spin lock
cybertrain spin run gen
spin lock は、git の依存について固定済みのコミットを、spin.toml の ref が何に変わっても保ちます。先にロックを消すのはそのためです。ほかにも依存があるアプリでは、代わりに spin.lock から [lock.cybertrain] のテーブルだけを消せば、ほかの固定は残ります。インデックスのバージョンに依存するアプリ(cybertrain = "X.Y.Z")に rm は要りません:その場合は spin lock が固定を動かします。
インデックスのバージョンに依存するアプリでは、まず cybertrain spin search cybertrain を実行して spin のインデックスのコピーを更新し、spin.toml の cybertrain = の行のバージョンを新しいリリースに変えてから、cybertrain spin lock と cybertrain spin run gen を実行します。
両者が一致していることは、コマンドが確認します。server、build、db、test、generate は、spin を実行したりファイルを書き出したりする前に、spin がビルドするフレームワークのバージョン、つまりアプリの spin.lock に固定されたバージョンを、コマンド自身のバージョン(cybertrain version)と比べます:アプリをコンパイルする Spinel のリリースを決めるのはアプリではなくコマンドであり、コマンドのテンプレートとジェネレーターは、同じリリースのフレームワーク向けに書かれているからです。バージョンが異なると、コマンドは終了コード 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
どちらか一方を行ってください。cybertrain spin ... は確認の対象にならないので、cybertrain spin lock はいつでも実行できます。git の依存では、spin.toml を書き換えても何も変わらず、そのあと spin lock を実行しても変わりません:そのロックを消すまで、spin は spin.lock のコミットをビルドし続けます。rm が要るのはそのためです。インデックスのバージョンに依存している場合、メッセージは cybertrain = "A.B.C" と cybertrain spin lock だけを示します。spin が固定されたリリースをビルドするのは spin.toml がそれを許している間だけなので、spin.toml が指すバージョンがロックと違えば、すぐにそのバージョンが比べられます。範囲("~> X.Y")が固定されたリリースを許さなくなった場合は、cybertrain spin lock を実行するまで拒否されます。フレームワークのチェックアウトに依存するアプリ(path = ...)は確認されません。spin.lock のないアプリは、spin.toml が指すリリース("X.Y.Z" または ref = "vX.Y.Z")と比べられます。ブランチ、コミット、範囲はリリースを指さないので、確認されません。
0.4 向けに書いたアプリケーションには、いくつか変更が要ります(どのセッションも一度だけ終わる、OpenSSL をリンクする、ドットを含むルートのセグメントには format: false が要る、など):0.4 のアプリを更新するを見てください。