Installing RGBDS
You can either use a pre-built version, if one is available for your operating system; or you can build RGBDS from source.
Pre-built
Below is a list of OSes we know are supported.
If your OS isn’t listed below, try finding rgbds
in your package manager—refer to your OS' documentation for help.
If you still can’t find RGBDS, or the specific version you are looking for is unavailable, you will have to compile it from source.
Arch Linux
RGBDS is now available in the official repos as community/rgbds
; you can also get the latest master via the rgbds-git
AUR package, or RGBDS 0.2.5 from rgbds2
, still from the AUR.
pacman -S rgbds
We refer you to the Arch Linux wiki on how to install official packages or AUR packages, or to find and use an AUR helper.
macOS
RGBDS is available on Homebrew as the rgbds
package.
brew install rgbds
You can also install the master
branch by passing the --HEAD
flag:
brew install rgbds --HEAD
Windows
The install instructions change a bit depending on the environment you wish to use RGBDS with.
The "plain Windows" instructions may also work for some environments listed further below, since most of them pick up Windows' PATH
.
However, if you have such an environment, we recommend you follow its specific install instructions instead.
- "Plain" Windows (CMD, PowerShell)
- Cygwin, MSYS2
- WSL, and all other Linux-like environments
- First, pick the version you want to install. If you want to use
master
instead of a release, go here. - Follow the "release page" link below "GitHub links", and grab either of the
win32
(for 32-bit Windows) orwin64
(for 64-bit Windows).zip
files, near the bottom of the page. - Unzip that file, you should get the
.exe
files alongside a couple of.dll
s. - Either:
- Put all of the files in a directory, then add it to the
PATH
. This will permanently allow you to use RGBDS. If you only want to modify the PATH temporarily, instead of the permanentsetx
command, you can use the temporaryset
one:set PATH="%PATH%<rgbds_path>
forcmd.exe
. Use one of the following methods:- Graphically:
- Open Control Panel
- Click "User Accounts"
- Click "User Accounts" again
- Click "Change my environment variables"
- Select the "Path" line in the top panel
- Click "Edit..."
- Click "Browse...", select the folder the files are in, and click OK
- Make sure that the new entry (which should be highlighted) is at the bottom of the list; if not, click on "Move Down" until it is
- Click "OK"
- Click "OK"
- Using a command line:
- Use Explorer to go into the folder the files are in (you should see
rgbasm.exe
etc.), and click a blank part of the address bar near the top. Copy this path, and use this instead of<rgbds_path>
in the third step! - Open
cmd
or PowerShell - Type
setx PATH "%PATH%<rgbds_path>;"
forcmd.exe
, orsetx PATH ${"{"}Env:PATH}<rgbds_path>;
for PowerShell; replace<rgbds_path>
with the path you copied in the first step - Close the window for the changes to take effect
- Use Explorer to go into the folder the files are in (you should see
- Graphically:
- Put all of the files in your project's directory
- Put all of the files in a directory already in the
PATH
- Put all of the files in a directory, then add it to the
- Profit! RGBDS can now be used from your favorite command line (
cmd.exe
or PowerShell, most likely). You can test it by runningrgbasm --version
.
Follow steps 1 to 3 of the "plain Windows" instructions to get the release's files; then, copy all of the .exe
and .dll
files to the /usr/local/bin
directory of Cygwin/MSYS2's installation.
(You can get its equivalent Windows path by running cygpath -w /usr/local/bin
.)
Do not put them in a subdirectory (e.g. /usr/local/bin/rgbds
)!
This would not work.
After that, you should be able to use RGBDS from within the Cygwin/MSYS2 terminal, which you can confirm by running rgbasm -V
.
If this doesn't work, check that /usr/local/bin
is within the PATH there (echo $PATH
); if it isn't, you must add it (e.g. export PATH="/usr/local/bin:$PATH"
in the ~/.bashrc
).
Note: if you can choose between using Cygwin or MSYS2, be advised that Cygwin is slower and has been reported to cause a bit of trouble to some.
For these, you have to build from source. On WSL, you should install any build prerequisites using apt-get
(example: sudo apt-get install libpng-dev
).
Building from source
RGBDS is open-source, which means you can always compile it yourself, for example if no pre-built solution is available to you, or if you want a specific version.
RGBDS aims to be relatively painless to compile, keeping its dependencies to a minimum:
- A C11-compatible compiler
libpng
(optional, only required for RGBGFX)
Some of the build steps vary between systems, so the instructions provided here are somewhat generic. Windows works largely differently from everything else, so some expertise is expected if attempting this on Windows.
1. Get the source
You first need to get the source files to be compiled, using one of the methods below.
Using Git
First, clone the repository. Then, run git checkout <version>
(e.g. git checkout v0.4.1
), and you're set.
Downloading source snapshots
Pick a release, then under that release "GitHub links", follow the release page
link.
Near the bottom of that page is a list of assets; grab either of the last three (rgbds-<version>.tar.gz
, "Source code (zip
)", or "Source code (tar.gz
)"), and extract it.
2. Build
The following are required to build RGBDS; it's possible that some are already installed on your system.
make
and/orcmake
, depending on what method you choose belowbash
shell- a C compiler, typically
gcc
orclang
bison
(oryacc
/byacc
prior to RGBDS 0.5.0)pkg-config
(unless usingcmake
)
If you are building RGBGFX, the following are also required:
- a C++ compiler, typically
g++
orclang
libpng
's development headers. For Linux users: the package is typically calledlibpng-dev
,libpng-devel
, or sometimes plainlylibpng
. Additionally, a16
or1.6
may be present afterlibpng
(example).
Two build systems are supported: plain old make
, and CMake.
Both can be used on most systems, but Windows users will almost certainly be unable to use make
.
Make sure to run all of the following commands from the root directory of the sources!
That directory should contain a file called Makefile
, another called CMakeLists.txt
, and a few more.
Using Make
Simply run the following two commands:
make
sudo make install
The second command is optional if you don't want to install RGBDS system-wide.
The following variables can be defined to control installation, like so: make Q=
, make install PREFIX=~/.local
PREFIX
: Location where RGBDS will be installed. Defaults to/usr/local
.bindir
: Location where the binaries will be installed. Defaults to${PREFIX}/bin
.mandir
: Location where the manpages will be installed. Defaults to${PREFIX}/share/man
.DESTDIR
: This is prepended to all paths during the installation. It is mainly used for packaging.Q
: Whether to quiet the build or not. To make the build more verbose, clear this variable. Defaults to@
.STRIP
: Whether to strip the installed binaries of debug symbols or not. Defaults to-s
.BINMODE
: Permissions of the installed binaries. Defaults to755
.MANMODE
: Permissions of the installed man pages. Defaults to644
.
Using CMake
Building RGBDS with CMake requires CMake 3.9 or later.
First, run CMake on the project.
cmake
3.13 and later:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake
3.12.4 and earlier:
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cd ..
Then, build RGBDS:
cmake --build build
Finally, you may install RGBDS.
You are not required to, you can do whatever with the four binaries in build/src
at this point.
cmake
3.15 and later:
sudo cmake --install build
cmake
3.14 and earlier:
cd build
sudo make install
Using RGBDS master
Using a package manager
Your package manager may have a master
version of RGBDS available, such as Arch's rgbds-git
AUR package.
There is no single way, you will have to look for it manually.
Building yourself
Build the source as usual, but replace step 1 with getting the master
repo instead.
The recommended way is to clone the repo (see GitHub's help on it if you have trouble), but you can also download the repo as ZIP.
Then, follow the rest of the instructions to build from source.
Using our CI
RGBDS has continuous integration: as part of our testing process, each time a modification is made to the code, a server builds RGBDS for several platforms, and runs a battery of tests to ensure nothing was broken. The executables built during the process are made available on GitHub.
We only recommend doing this on Windows, as the Windows zips are stand-alone, but the others aren't. You can still use them if you know what you're doing, but we don't recommend it.