Чтобы попробовать CyberTrain, ничего не устанавливая, откройте песочницу:
GitHub Codespaces открывает в вашем браузере, в VS Code, блог из учебника, команду cybertrain и
зафиксированный релиз Spinel. Тот же образ запускается и локально под Docker.
Требования
- Spinel в релизе из
Cybertrain::SPINEL_TAG(cybertrain/version.rb; его выводитcybertrain doctor, иSPINEL_TAGCI в .github/workflows/ci.yml тот же) — релиз saeki-mototsune/spinel (Cybertrain::SPINEL_REPOSITORY), форка matz/spinel, в котором исправления, нужные CyberTrain, появляются раньше, чем в релизе основного проекта; с другими версиями не тестировался. Вручную его устанавливать не нужно: командаcybertrainсобирает этот релиз в~/.cybertrain, когда он впервые понадобится (cybertrain setupделает это по запросу), если толькоspinelэтого релиза уже нет вPATH, — см. Как устанавливается Spinel. - Для его сборки: инструменты C (
ccили компилятор, указанный вCC) иmake— Spinel компилирует каждую программу в C, — а такжеgitиcurl. - Заголовки и библиотека SQLite 3 (
libsqlite3-devв Debian/Ubuntu; на macOS входят в Xcode command line tools) — модели используют FFI Spinel напрямую, а не гем. - Заголовки и библиотека zlib (
zlib1g-devв Debian/Ubuntu; в macOS SDK) — тела запросов в gzip (request.decoded_body) распаковываются через системную zlib, привязанную тем же способом. - Заголовки и библиотека OpenSSL (
libssl-devв Debian/Ubuntu) — их линкует каждое приложение: cookie сессии иcookies.encryptedшифруются AES-256-GCM через пакетopensslSpinel, который Spinel собирает, только когда заголовки есть. На macOS установите OpenSSL из 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-превью сервера разработки, которому нужна ещё библиотека Rubyfiddle(ей нужен libffi); безfiddlecybertrain serverзапускает только скомпилированный цикл. Развёрнутое приложение никогда не запускается на CRuby. На Ruby 3.2 для сборки Spinel также нужен gemprism(ниже).
cybertrain doctor проверяет эти инструменты и заголовки, загружает ли
ruby из PATH библиотеку fiddle, а также установку Spinel; если чего-то
обязательного не хватает, она также выводит команду установки для вашей
платформы (отсутствие fiddle не считается: сервер всё равно работает,
скомпилированным).
Ещё пакетыprism на Ruby 3.2; jemalloc, необязателен
- Для сборки Spinel нужен gem
prism, который в Ruby 3.3 и новее входит в поставку; на Ruby 3.2 выполнитеgem install prism(нужны заголовки разработки Ruby,ruby-devв Debian/Ubuntu).cybertrain doctorэто проверяет. - Spinel, собранный до установки заголовков OpenSSL, не имеет пакета
openssl, и сборка приложения тогда не удаётся; когда заголовки появятся, выполнитеcybertrain setup --force, чтобы пересобрать его. Тот же пакет обслуживает TLS (require "cybertrain/net/tls") и зашифрованные столбцы (encrypts). - Пакет разработки jemalloc (
libjemalloc-dev;brew install jemalloc) необязателен: он нужен приложению, только когда в егоspin.tomlуказаноallocator = "jemalloc", чтоcybertrain newзаписывает закомментированным. Его стоит включить для продакшена: в 1,1–1,4 раза больше запросов в секунду на examples/blog (docs/benchmark.md).
Установка CLI
gem install cybertrain
cybertrain doctor
Первая строка устанавливает команду из RubyGems, а вторая проверяет
требования; учебник продолжает отсюда, от
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, контроллеры и представления входа и регистрации, маршруты,before_actionвApplicationControllerи тест (см. Добавление входа). С--invite-onlyстраницы регистрации нет: пользователи создаются командой./NAME user EMAIL, а первый — также на странице/setup, которая отвечает только машине самого сервера, с одноразовым токеном, который выводит предупреждение при запуске, пока не существует ни одного пользователя.cybertrain generate attachment MODEL FIELD [--any]добавляет загрузку файла в модель со скаффолдом: пять столбцов метаданных, методы и колбэки модели, действие для скачивания, маршрут, поле формы и тест (см. Добавление обложки). Поле скаффолда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;spin build NAME -- --incremental, если какой-то Ruby-файл новееbuild/bin/NAME;spin run NAMEилиspin run NAME -- PORT).cybertrain buildсобирает NAME со встроеннымиapp/views/и формируетdist/(бинарный файл,public/,storage/,tmp/).cybertrain test [FILE|DIR ...] [-n NAME|-n /TEXT/]выполняет генерацию, компилирует все тесты изtest/в одну программу (только когда что-то изменилось) и запускает её, оставляя тесты, названные аргументами (см. Тестирование приложения).cybertrain spin ARGS...запускаетspinс зафиксированным Spinel из любого каталога (cybertrain spin test,cybertrain spin run gen -- --check).cybertrain setup [--force]устанавливает зафиксированный релиз Spinel в~/.cybertrain, еслиspinelэтого релиза ещё нет вPATH;--forceпересобирает копию в~/.cybertrain.cybertrain doctorпроверяет инструменты C, заголовки SQLite, загружает ли Rubyfiddle(он нужен CRuby-превью) и установку Spinel.cybertrain versionвыводит версию.
db, server и build запускаются внутри приложения; NAME — это
[package] name из его spin.toml.
Как устанавливается Spinel
Каждая команда, которая запускает spin (new, db, server, build, spin),
сначала убеждается, что доступен Spinel релиза из Cybertrain::SPINEL_TAG.
spinel в PATH (вместе с 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 ещё до её начала
сообщает, какого именно, и выводит команду установки для вашей платформы. spinel другого
релиза в PATH никогда не используется и не затрагивается: cybertrain держит
собственную копию (и сообщает об этом, когда её устанавливает).
cybertrain setup делает то же самое по запросу и, если используется именно
её копия, выводит строку, добавляющую её в PATH, чтобы запускать spin
самостоятельно:
export PATH="$HOME/.cybertrain/bin:$PATH"
В ~/.cybertrain/bin лежат ссылки spinel и spin на используемый релиз,
поэтому строка переживает смену релиза; команде cybertrain spin ... PATH
вообще не нужен.
Переменные окруженияCYBERTRAIN_HOME переносит ~/.cybertrain, CYBERTRAIN_SPINEL_HOME использует существующую установку
Две переменные окружения переопределяют всё это:
CYBERTRAIN_HOMEзаменяет~/.cybertrain(путь без пробелов, кавычек,$и:, которые не принимают Makefile Spinel иPATH).CYBERTRAIN_SPINEL_HOME=PREFIXпринудительно задаёт существующую установку: тогдаcybertrainиспользуетspinelиspinизPREFIX/bin(или из самогоPREFIX, еслиspinelлежит прямо в нём) и останавливается с ошибкой, если это не тот релиз.
Гем и фреймворк
gem install cybertrain устанавливает команду, а не фреймворк. Гем — это
команда cybertrain, обычный Ruby, который работает на вашей машине под CRuby
(3.2 или новее) и вызывает за вас инструмент Spinel spin; ни фреймворка, ни
Spinel в геме нет. Фреймворк — это пакет Spinel, от которого зависит ваше
приложение в spin.toml: Spinel заранее компилирует его вместе с вашим кодом,
и именно он попадает в поставку. Бинарный файл в dist/ работает без Ruby,
гема и 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 — фреймворк без необязательных
подсистем; генераторы, которым нужна подсистема, добавляют её строку
(Подсистемы).
Если не удаётся установить Spinel или выполнить один из двух шагов spin, файлы
остаются, new завершается с кодом 1 и выводит, что запустить после устранения
причины (для Spinel: cybertrain setup, затем
cybertrain spin lock && SPIN_DEBUG=1 cybertrain spin run gen в новом каталоге).
Четыре параметра меняют то, что она записывает и запускает:
--skip-spinтолько записывает файлы: без установки Spinel, безspin lock, безspin run gen.--path DIRвместо этого делает зависимостью локальную копию репозитория (--path ~/src/cybertrain, где бы ни лежала копия, при работе над самим CyberTrain).--git URL [--ref R]делает зависимостью фреймворк по адресу URL (на ветке или теге R).--version Vделает зависимостью релиз V изspin-index(cybertrain = "V"), когда фреймворк там появится: см. Версия из индекса.
Указывайте только один из --path, --version и --git; --ref требует --git.
Версия из индекса
spin-index — это список пакетов, в котором spin ищет имя. Фреймворка в нём
пока нет: до тех пор spin lock в приложении, созданном с --version,
отвечает not in the index: cybertrain, а зависеть от релиза следует через
тег, который new записывает по умолчанию. Когда фреймворк там появится,
cybertrain new NAME --version X.Y.Z запишет cybertrain = "X.Y.Z", spin
найдёт коммит этого релиза в индексе, а spin.lock зафиксирует те же три
вещи, что и для тега (версию, репозиторий и коммит), поэтому все команды и
процесс CI, который записывает new, работают так же, как по умолчанию. Три
вещи отличаются от того, чего заставляет ждать Gemfile:
- Указывайте один релиз. Из релизов, удовлетворяющих ограничению, spin
выбирает самый младший, а не самый новый:
"~> X.Y"— это самый младший релиз в индексе от X.Y до следующей мажорной версии (в пределах X.Y остаётся только"~> X.Y.Z"), и он остаётся тем же, когда выходят следующие. Поэтому пишите точную версию, ту, что печатаетcybertrain version; если V записана иначе,newпечатает примечание. - Spinel по-прежнему ставит команда
cybertrain. Запись в индексе не называет релиз Spinel. Фреймворк написан для одного релиза и проверен на нём: это тот, который собираетcybertrain setup, и его устанавливает командаcybertrainтой же версии. Простоspin add cybertrainв проекте, который собирается другим Spinel, не проверялся. - spin читает собственную копию индекса. Он клонирует индекс один раз,
в
~/.cache/spin/, иspin lockэту копию не обновляет;spin search cybertrainобновляет её и печатает самый новый релиз.
Перевод приложения на новый релиз
Гем и фреймворк выпускаются из одного тега, поэтому их версии совпадают: гем
X.Y.Z создаёт приложения, зависящие от фреймворка vX.Y.Z. Чтобы перевести
приложение на новый релиз, обновите гем, укажите в spin.toml новый тег, затем
выполните в приложении:
rm spin.lock
cybertrain spin lock
cybertrain spin run gen
spin lock сохраняет коммит, зафиксированный для git-зависимости, каким бы
ни стал ref в spin.toml, поэтому сначала удаляется файл блокировки. В
приложении с другими зависимостями можно вместо этого удалить из spin.lock
только таблицу [lock.cybertrain] и сохранить остальные фиксации.
Приложению, зависящему от версии из индекса (cybertrain = "X.Y.Z"), rm не
нужен: там spin lock сам переносит фиксацию.
В приложении, которое зависит от версии из индекса,
сначала выполните cybertrain spin search cybertrain, чтобы обновить копию
индекса у spin, затем замените версию в строке cybertrain = файла
spin.toml на новый релиз и выполните 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.