rgbenv

This is a version manager for RGBDS. It is a pure shell script.* Inspired by pyenv and rbenv, it lets you easily switch between multiple versions of the RGBDS suite to suit different projects.

* Bash script, at the moment. Compatibility with other shells is not guaranteed.

Quickstart (Debian)

1. Get rgbenv

sudo apt install -y libpng-dev pkg-config build-essential bison git curl
sudo curl -o /usr/local/bin/rgbenv https://raw.githubusercontent.com/gbdev/rgbenv/master/rgbenv
sudo chmod +x /usr/local/bin/rgbenv

2. Install a version and set it as the default

rgbenv install 0.7.0
rgbenv use 0.7.0

3. Use the default version

rgbenv exec rgbasm -V

(replace rgbasm -V with your desired command)

To use it without rgbenv exec…

echo 'export PATH="$HOME/.local/share/rgbenv/default/bin:$PATH"' >> .bashrc
source .bashrc
rgbasm -V

4. Execute with another version

rgbenv install 0.6.1
rgbenv exec -v 0.6.1 rgbasm -V

(replace rgbasm -V with your desired command)

What does it do?

• Installs or uninstalls a specific version of the RGBDS suite.
• Lets you configure the default version to use.
• Lets you specify a version to be used with a specific project.

How does it do that?

PATH is the variable used by the system to determine where to find some program. It contains a list of directories, separated by a colon each:

/usr/local/bin:/usr/bin:/bin:/usr/local/sbin

Left-most directories take priority. If a program isn't found there, it will search the directory next to it.

As an example, if you installed RGBDS 0.6.0 through your package manager, it would place the suite programs in /usr/bin. If you compiled, say, version 0.4.1 of RGBDS manually and placed it in /usr/local/bin, then that version would take precedence over 0.6.0.

What rgbenv does is override this variable so that its managed folder takes precedence over that of the system. In Unix-like systems, you can check which directory a program is to be run from (for example, rgbasm) using this command:

$ which rgbasm

What do I need?

• A Unix-like environment
  • Linux or BSD preferable
  • On Windows, you may use either:
    • WSL with a distro of choice
    • MSYS2
    • Cygwin
• git
• curl
• RGBDS build dependencies

You can use these commands to get them:

• Debian:

  # apt update
  # apt install libpng-dev pkg-config build-essential bison git curl
  

• Alpine Linux:

  # apk add git curl make libpng-dev bison gcc g++ libc-dev
  

• OpenBSD:

  # pkg_add png git bash curl bison
  

  In case something goes wrong, try using GCC as the compiler:

  # pkg_add g++ gcc
  $ CC=egcc CXX=eg++ rgbenv install $YOUR_DESIRED_VERSION

• Windows MSYS2 (MinGW64):

  $ pacman -S git make bison pkgconf mingw-w64-x86_64-gcc mingw-w64-x86_64-libpng
  

  If you're using another environment with MSYS2, replace mingw-w64-x86_64 with the corresponding name. You may need to do mkdir -p /usr/local/bin first.
• Windows Cygwin: From the setup program, select the latest versions of these packages:
  • git
  • gcc-g++
  • libpng-devel
  • pkgconf
  • bison
  • make

How do I set it up?

1. Install whatever dependencies it needs, through the above section.
2. Download the rgbenv script, and place it in /usr/local/bin/ (or any directory listed when you run echo $PATH) The fastest way is through:

   # curl https://raw.githubusercontent.com/gbdev/rgbenv/master/rgbenv > /usr/local/bin/rgbenv

3. Ensure the script is executable:

   # chmod +x /usr/local/bin/rgbenv
   

   (replace /usr/local/bin/rgbenv with where you put the rgbenv script)
4. Install the version you want, say 0.6.0:

   $ rgbenv install 0.6.0
   

5. When prompted to add export PATH=... to .bash_profile, do so, then run:

   $ source ~/.bash_profile
   

   Note: in some shells, you may need to specify .profile instead of .bash_profile.
6. Set your version as the default:

   $ rgbenv use 0.6.0
   

7. Verify that RGBDS really is the version you picked:

   $ rgbasm -V
   

How to set a project-specified version

On the current working directory, make a file named .rgbds-version. This shall be a text file containing only the version number to be used. For example:

$ cat .rgbds-version
0.6.0

Quick commands

• rgbenv use 0.5.1 - set default RGBDS version to 0.5.1
• rgbenv no-use - clear the defaults and use the system-provided RGBDS, if any
• rgbenv exec -v 0.4.2 make - run make using RGBDS 0.4.2
• rgbenv exec make - run make with the project-specified RGBDS version.

Development

At the moment, rgbenv is hosted on GitHub.

To run the unit tests on your own machine, clone the rgbenv repo (instead of just downloading the script as above), and then run make test:

$ git clone https://github.com/gbdev/rgbenv
$ cd rgbenv
$ make test

As the unit tests use Bats, the Bats repo will be cloned automatically inside the rgbenv directory if it is not present, and then Bats will be run from there.