Installation
Follow the instructions for your platform to set up the project:
The Windows installation instructions provided are not exhaustive. They are designed to offer the most straightforward and reliable approach for getting started, particularly for those new to working with C and SDL2. If you already have a development environment configured, you may choose to use it; however, these steps are intended to provide a simple and tested starting point.
Target OS: Windows 10 (VirtualBox)
Dependency installation instructions are outlined in the following section.
- MSYS2
- GCC
- Make
- Git
- mingw-w64-x86_64-SDL2
- mingw-w64-x86_64-SDL2_ttf
Navigate to the MSYS2 homepage and then download and launch the installer. If you receive a "Windows Protected your PC" message, you may dismiss it by clicking on More Info > Run anyway (MSYS2 is safe to run). Once the installer launches, proceed with all the default prompts.
Allow the installation to finish, but it is recommended that you uncheck the "Run MSYS2 now" checkbox, since we'll be using MSYS MINGW64 instead of the default.
Open the Windows menu and run the MSYS MINGW64 program, which will launch a MINGW64 terminal. Enter the following command to update the dependency package manager:
pacman -Syu
Accept all prompts by typing "Y". The terminal might need to restart, in which case, relaunch it through the Windows menu as before. Then, proceed by installing the project dependencies:
pacman -S git gcc make mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_ttf
Once again, accept all prompts by typing "Y" and wait for the installation to finish.
Clone the project repository by entering:
git clone https://github.com/zeim839/nes-tools.git
Then, navigate to the project by entering:
cd nes-tools
To configure the project, you'll need to specify the location of your SDL2 header and library files. If you've followed the instructions above, these should be in /mingw64/include/SDL2 and /mingw64/lib, respectively. To verify your installation location, you may run:
ls /mingw64/include/SDL2
If you see the SDL header files (including SDL_ttf.h), then you should be good to go. Otherwise, you'll need to search through your system to identify the correct installation path. Similarly, you can verify that the libraries are in place by running:
ls /mingw64/lib
You should be able to find the libSDL2.a and libSDL2_ttf.a files. Next, configure the project by specifying your header and library paths as arguments to the ./configure script:
./configure --with-sdl-headers=/mingw64/include/SDL2 --with-sdl-lib=/mingw64/lib
If the configuration script fails, then there's probably a problem with your MSYS environment or the specified SDL2 paths.
To build the project, simply run make:
make
To run the project, call the compiled binary as follows:
./src/nes-tools.exe help
Running the help subcommand will show the help menu. If you wish to run a game ROM, run:
./src/nes-tools.exe run [PATH-TO-ROM]
Where [PATH-TO-ROM] should be replaced by a file system path pointing to your desired ROM file.
Dependency installation instructions are outlined in the following section.
- xCode developer tools
- Homebrew
- Make
- Git
- SDL2
- SDL2_ttf
If this is your first time developing on MacOS, you may need to install xCode's developer tools. This can be done by opening a terminal and running the following command:
xcode-select --install
Homebrew is a dependency manager that will allow you to conveniently install the SDL2 dependencies. Homebrew can be downloaded here.
Once Homebrew is installed, install the project's dependencies with the following command:
brew install gcc git make sdl2 sdl2_ttf
Clone the project repository by entering the following into your terminal:
git clone https://github.com/zeim839/nes-tools.git
Then, navigate to the project root directory:
cd nes-tools
Depending on your system, Homebrew's default installation directory may be in either /opt/homebrew/Cellar/sdl2/... or /usr/local/Cellar/sdl2/.... Run the following commands to identify which of the two your system uses:
ls /opt/homebrew/Cellar/SDL2
ls /usr/local/Cellar/SDL2
Once you've identified the path prefix, you'll need to pass it as an argument to the ./configure script. You'll also need to specify the path to SDL2_ttf, which can likewise be found either in /opt/homebrew/Cellar/SDL2_ttf or /usr/local/Cellar/SDL2_ttf. Note that the aforementioned directories will include different subdirectories for each installed version of the SDL2 library. You'll need to specify the path, including the version, as shown below:
./configure \
--with-sdl-headers=/usr/local/Cellar/sdl2/2.30.9/include/SDL2 \
--with-sdl-lib=/usr/local/Cellar/sdl2/2.30.9/lib \
--with-sdl-ttf-headers=/usr/local/Cellar/sdl2_ttf/2.22.0/include/SDL2 \
--with-sdl-ttf-lib=/usr/local/Cellar/sdl2_ttf/2.22.0/lib
In other targets, the SDL2 and SDL2_ttf header files are included in the same directory. On MacOS, Homebrew installs them on separate directories, so they need to be manually specified.
If the configure script fails, then there's probably a problem with your development environment or the paths specified above.
Build the project by running make:
make
./src/nes-tools help
Running the help subcommand will show the help menu. If you wish to run a game ROM, run:
./src/nes-tools run [PATH-TO-ROM]
Target OS: Ubuntu-24.04-Desktop
- GCC
- Make
- Git
- SDL2
- SDL2_ttf
Open a terminal, and begin by updating the package manager's repository list:
sudo apt update
Then, install build-essential and git. build-essential automatically includes the gcc and make dependencies:
sudo apt install -y build-essential git
Finally, install SDL2 and SDL2_ttf:
sudo apt install -y libsdl2-dev libsdl2-ttf-dev
Clone the project repository by entering:
git clone https://github.com/zeim839/nes-tools.git
Then, navigate to the project by entering:
cd nes-tools
Run the configure script:
./configure --with-sdl-headers=/usr/include/SDL2
Depending on your distribution, you may need to modify the --with-sdl-headers and --with-sdl-lib flags. The --with-sdl-headers variable should point to within you SDL2 directory (i.e. SDL2 is the root). The --with-sdl-lib flag should point to the directory containing libSDL2.a and libSDL2_ttf.a (in most cases, this will be automatically detected by configure and should be left unchanged).
Finally, build the project by running make:
make
./src/nes-tools help
Running the help subcommand will show the help menu. If you wish to run a game ROM, run:
./src/nes-tools run [PATH-TO-ROM]