gdenv

A single-purpose, CI-friendly command-line interface for managing Godot editor versions. Inspired by pyenv, rbenv, and volta.

How it works

The gdenv application maintains a cache of downloaded Godot executables (typically $HOME/.gdenv) and provides a shim which should be set to the system's godot executable. This shim intercepts normal use of the godot command and, based on the directory from which the godot command is invoked (or the --path option), transparently invokes the correct version of Godot with the provided arguments.

In order to track pinned versions of Godot, the pin subcommand will place a .godot-version file in the specified directory (or within $GDENV_HOME if pinning a global version with -g). This is what the godot shim will use to determine the correct Godot version.

Getting started

These instructions will help you install gdenv and pin projects (or your system) to specific versions of Godot.

Example usage

Install a global (system-wide) Godot version

NOTE: For Mono-flavored builds, see Version selection (C#/Mono support).

gdenv pin -ig 4.0

Pin a project to a specific Godot version

# Omit the `--path` option to pin the current directory;
#   the `-i` flag instructs `gdenv` to download the pinned version to its cache.
gdenv pin -i --path /path/to/project 4.0

Vendor the Godot source code

gdenv vendor --out /path/to/project 4.0

Check which version of Godot would be used

# Omit the `--path` option to pin the current directory
gdenv which --path /path/to/check 4.0

Installation

See docs/installation.md for detailed instructions on how to download gdenv.

API Reference

Commands

See docs/commands.md for a detailed reference on how to use each command.

Manage installed versions

• install — gdenv install [OPTIONS] [VERSION]
• uninstall — gdenv uninstall [OPTIONS] [VERSION]
• vendor — gdenv vendor [OPTIONS] [VERSION]

Pin projects/set system default

• pin — gdenv pin [OPTIONS] <VERSION>
• unpin — gdenv unpin [OPTIONS]

Inspect versions

• ls/list — gdenv ls [OPTIONS]
• which — gdenv which [OPTIONS]

Platform selection

By default gdenv will install Godot executables for the host platform (i.e. the system gdenv is running on). To change which platform gdenv selections, the following environment variables can be set in front of any gdenv command:

❕ NOTE: These options are meant to circumvent incorrect platform detection by gdenv or facilitate installing different Godot editor versions in a CI environment. Most users will not need to set these when using gdenv locally.

• GDENV_OS - set the target operating system (still uses the host's CPU architecture)
• GDENV_ARCH - set the target CPU architecture (still uses the host's operating system)
• GDENV_PLATFORM - set the literal string suffix of the Godot editor (e.g. macos.universal or win64)

Version selection (C#/Mono support)

gdenv considers Mono variants of Godot to be part of the version and not the platform. As such, to have gdenv install Mono builds of Godot editors all version specifications should be suffixed with stable_mono (e.g. gdenv pin 4.0-stable_mono or gdenv install 4.1.1-stable_mono). Although gdenv normally assumes a stable release if the label is omitted, Mono builds must be explicitly specified.

However, to simplify use of gdenv when Mono builds are desired, the following environment variable can be set to have gdenv default to using Mono builds when the version label is omitted. A non-Mono build can then be specified by passing a version label of stable without the _mono suffix.

• GDENV_DEFAULT_MONO - set to 1 to have gdenv interpret missing version labels as stable_mono instead of stable

Development

Setup

The following instructions outline how to get the project set up for local development:

1. Follow the instructions to install Go (see go.mod for the minimum required version).
2. Clone the coffeebeats/gdenv repository.
3. Install the tools used below by following each of their specific installation instructions.

Code submission

When submitting code for review, ensure the following requirements are met:

❕ NOTE: These instructions do not persist the tools to your development environment. When regular use is required, follow each tool's individual instructions to install permanent versions.

1. The project is correctly formatted using goimports:

   go run golang.org/x/tools/cmd/goimports@latest -w .

2. All golangci-lint linter warnings are addressed:

   go run github.com/golangci/golangci-lint/cmd/golangci-lint@latest run ./...

3. All unit tests pass and no data races are found:

   go test -race ./...

4. The gdenv and gdenv-shim binaries successfully compile with goreleaser (release artifacts will be available at ./dist):

   go run github.com/goreleaser/goreleaser@latest release --clean --skip=publish --snapshot

Contributing

All contributions are welcome! Feel free to file bugs and feature requests and/or open pull requests.

Version history

See CHANGELOG.md.

License

MIT License