drenv - DragonRuby Environment Manager

drenv is a cross-platform CLI tool that helps you declutter your DragonRuby installations.

drenv is built with Deno and is inspired by rbenv.

Installation

Download the executable for your platform from the releases page, then run:

drenv setup

This moves the executable to ~/.drenv/bin and prints the line to add to your shell profile.

Note

On macOS, if you see a Gatekeeper warning, run:

xattr -d com.apple.quarantine ./drenv

Note

Once installed, keep drenv up to date by running drenv upgrade.

Alternatively, you can build from source:

deno compile -A --unstable-kv --output=builds/drenv --target=aarch64-apple-darwin main.ts

Getting Started

1. Install DragonRuby

drenv install

This signs into your itch.io account and downloads the latest version of DragonRuby GTK. Your credentials are stored as a revocable API key — never as a plaintext password.

Note

drenv install requires a DragonRuby GTK purchase on itch.io. Only the standard tier is supported at this time.

2. Set a global version

drenv global <version>

3. Create a project

drenv new my-game

---

Managing DragonRuby Versions

drenv install [tier]

Downloads and installs the latest version of DragonRuby GTK from itch.io.

drenv register <path>

Registers a local DragonRuby installation manually. The path can be a .zip file or a directory containing the dragonruby executable. Useful if you already have a copy downloaded.

drenv global [version]

Sets the global DragonRuby version used when creating new projects. Running without arguments prints the current global version.

drenv versions

Lists all registered versions, with the current local version marked:

  6.4
* 6.3
  5.32

Managing DragonRuby Projects

drenv new <name>

Creates a new DragonRuby project by copying a registered version into a new directory, and writes a project .gitignore (covering the DragonRuby binaries, builds/, tmp/, logs/, docs, and samples). Uses the global version by default; pass --version <version> for a specific one, or --skip-gitignore to skip writing the .gitignore.

drenv update

Updates the current project to a registered DragonRuby version, preserving the mygame directory. Defaults to the latest installed version; pass --version <version> for a specific one. Asks for confirmation first.

drenv run [args...]

Syncs the current project's dependencies and launches it with DragonRuby. While the game runs, drenv watches any path: dependencies and re-vendors them as you edit, so changes hot-reload into the running game — handy when developing a library alongside it. Pass --no-watch to turn that off (--frozen skips it too). Extra arguments are forwarded to the dragonruby binary.

Managing Dependencies

drenv vendors dependencies into your game, bundler-style. Declare them in mygame/drenv.toml and drenv resolves them into mygame/vendor/, pins them in mygame/drenv.lock, and generates mygame/app/drenv_bundle.rb with the matching require lines.

# mygame/drenv.toml
[dependencies.conjuration]
github = "Nitemaeric/conjuration"   # entrypoint resolved from the library

[dependencies.draco]
github = "guitsaru/draco"
tag = "v0.7.0"
entrypoint = "draco.rb"             # ...or pin it explicitly

[dependencies.local_lib]
path = "../local_lib"

Each dependency declares exactly one source — github, url, git, or path. The entrypoint is optional: drenv resolves it from the library's own [package] declaration, or by convention (lib/<name>.rb, then <name>.rb). You can edit drenv.toml by hand or manage it with drenv add / drenv remove. Either way, add a single line to the top of mygame/app/main.rb:

require 'app/drenv_bundle.rb'

Commit drenv.toml and drenv.lock. drenv keeps mygame/vendor/ out of version control for you with a generated vendor/.gitignore, since vendored dependencies are reproducible from the lockfile.

drenv add <source>

Adds a dependency to mygame/drenv.toml and vendors it. The source is kind:value:

drenv add github:Nitemaeric/conjuration        # entrypoint resolved for you
drenv add github:guitsaru/draco@v0.7.0
drenv add git:https://gitlab.com/me/my_engine.git --branch main
drenv add path:../local_lib

Pass -e, --entrypoint only when the library doesn't declare or follow a conventional entrypoint, -n, --name to override the derived name, and --tag/--branch/--ref to pin a github/git revision.

drenv remove <name>

Removes a dependency from mygame/drenv.toml, deletes its vendored copy, and updates the lock.

drenv bundle

Resolves every dependency in mygame/drenv.toml, vendors it into mygame/vendor/, and writes mygame/drenv.lock and mygame/app/drenv_bundle.rb. drenv run does this for you before launching; run it directly when you only want to refresh dependencies. Pass --frozen (also valid on drenv run) to verify against the lockfile without updating it — handy in CI.

drenv publish [args...]

Verifies dependencies against the lockfile (like --frozen), then runs dragonruby-publish on mygame, forwarding any arguments. So drenv publish --package packages locally and drenv publish publishes to itch.io — always shipping exactly what's locked.

Publishing a library

If you maintain a DragonRuby library, add a [package] section to a drenv.toml at your repo root so consumers can drenv add it with no extra flags:

[package]
root = "lib"                  # only this directory is vendored (default ".")
entrypoint = "conjuration.rb" # the file to require, relative to root

Without it, drenv falls back to convention — lib/<name>.rb, then <name>.rb — so many libraries (a lib/<name>.rb layout) work with zero configuration.

Managing drenv

drenv setup

Moves the drenv executable to ~/.drenv/bin and shows instructions for adding it to your $PATH.

drenv upgrade

Downloads and installs the latest version of drenv.

---

Tested on macOS (Apple Silicon) with DragonRuby standard 5.32, 6.3, 6.4, and 6.18.