Setting up oracles-disasm

The disassembly uses WLA-DX as its assembler. Follow this guide to set up oracles-disasm into a compileable state.

This tutorial is available in video form.

Windows

Since the disassembly was created for a Linux-like environment, you will need to set up such an environment on a Windows machine. Currently, "Windows Subsystem for Linux" is the favored method. "Cygwin" is an older method.

Option A: Windows Subsystem for Linux

You will need a recent version of Windows 10 in order to follow these instructions. In particular, as of 2020, the ability to access Linux files from Windows programs (which is important for this setup) is a relatively recent addition.

The below instructions will explain how to set up WSL 1, but WSL 2 (a more recent version) should also work (and might be faster).

1. Set up windows for WSL.
   • Open powershell as an administrator and run the following commands (see hyperlink above for more details):

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

   • Restart your machine.
2. Install Ubuntu (20.04) from the Microsoft Store (I can't believe I'm typing this sentence)
3. Once installed, open a Ubuntu terminal and run the following commands to install some necessary packages:

   sudo apt update
   sudo apt install make

   (Other important packages include "git", "python3", and "python3-yaml", but these seem to be installed by default)

   (Note: You may want to enable copy/paste with Ctrl-Shift-V by right-clicking on the window's titlebar and clicking on "Properties".)

4. Now follow the instructions in the Linux section.
5. At any time, you may run the command "explorer.exe ." to open Window Explorer within your current directory in Linux. You may want to pin the "oracles-disasm" folder to Quick Access or create a shortcut to it. However, it may be the case that you need to have a Ubuntu terminal running in order to access the directory in Windows Explorer.

Option B: Cygwin

(This method is considered obsolete, and Windows Subsystem for Linux is favored. But if you have an older windows version, or if WSL doesn't work for you, this will also work.)

1. Download and install Cygwin on your computer (64-bit version). Cygwin provides a linux-like environment on Windows.
2. Continue with the default settings in the installer until you reach the "Select Packages" window. If you accidentally went past this, you can run the installer again to select the packages.
3. Select the following packages:
   • Interpreters -> python3 (NOT python2, although you can install that too)
     • NOTE: As of 2020-04-27 the disassembly has switched from Python2 to Python3.
     • NOTE 2: You need to install python through Cygwin. Python also has separate windows installers, but these versions behave differently and may not work in cygwin.
   • Devel -> git
   • Devel -> make
   • Devel -> cmake
4. Start up a Cygwin terminal and follow the instructions for Linux.

Linux

Prerequisites

• Standard building tools (Bash, Make, gcc)
• Git
• Python 3
• CMake (if compiling WLA-DX)

Obtaining WLA-DX

You can either download precompiled WLA-DX binaries or compile it yourself. Currently, the disassembly targets WLA-DX v9.11.

Option A: Download it

Run the following commands to download wla-dx.

For Linux, or Windows Subsystem for Linux:

sudo curl https://wiki.zeldahacking.net/files/oracles-disasm/wla-gb -o /usr/local/bin/wla-gb
sudo curl https://wiki.zeldahacking.net/files/oracles-disasm/wlalink -o /usr/local/bin/wlalink
sudo chmod +x /usr/local/bin/wla*

For Cygwin (64-bit):

curl https://wiki.zeldahacking.net/files/oracles-disasm/wla-gb.exe -o /usr/local/bin/wla-gb.exe
curl https://wiki.zeldahacking.net/files/oracles-disasm/wlalink.exe -o /usr/local/bin/wlalink.exe
chmod +x /usr/local/bin/wla*

Option B: Compile it

I recommend using the precompiled binaries instead (explained above), but if you prefer to compile WLA-DX yourself, then perform the following instructions:

1. Clone wla-dx:

   git clone https://github.com/vhelin/wla-dx
   cd wla-dx

2. Checkout v9.11:

   git checkout v9.11-fix-fix-fix

3. Compile it:

   cmake .
   make

4. Copy the binaries to somewhere in your PATH:

   cp binaries/* /usr/local/bin/

Downloading the disassembly

Now that you have WLA-DX you're ready to download the disassembly and attempt to compile it.

1. Clone the disassembly:

   cd ~
   git clone https://github.com/Drenn1/oracles-disasm
   cd oracles-disasm

2. Checkout the "hack-base" branch, which makes certain modifications for the benefit of hacking (consider this a must if you're planning to use LynnaLab):

   git checkout hack-base

3. If you intend to collaborate with others, run the following command, which will install git "merge drivers" to better handle git merge conflicts:

   tools/git/installMergeDriver.sh

4. Run make -j4. This will produce a ROM named "ages.gbc". The "-j4" flag tells it to use 4 threads (useful if you have multiple cores).
5. To build only one game instead of both, change the ".DEFAULT_GOAL" line in the Makefile.
6. You can now run ages.gbc using your favorite emulator!

What next?

Check out the setup instructions for LynnaLab for level editing. See also the video tutorials for that.

Also join the discord to get in touch with more Oracles hackers!

Potential errors

Cygwin

PARSE_DEFINES_AND_GET_FINAL_NAME: Error in commandline options.

You're using the incorrect version of wla-dx. You should either use the provided binaries, or a recent build from github.

ImportError: No module named site

This seems to be caused by conflicting python installations between Windows and Cygwin.

A temporary fix is to run export PYTHONHOME=/usr/ before running make again. Add this line to your ~/.bashrc file to make the fix permanent.