Ensure that you have the following software installed:

• Clang
• Rust compiler and cargo (https://rustup.rs)
• RetroArch (https://www.retroarch.com/)

cargo build --release

retroarch -L target/release/liboxid_8.so rom.ch8

Where rom.ch8 is the path to the ROM file to be executed.

By default, the emulation speed is 10 instructions per frame. Since programs run at 60FPS, this corresponds to 600 instructions per second. Certain programs can benefit from a slower / faster emulation speed. Using the ipf command-line argument, this value can be changed. For example, the following command will make the emulation run at twice the speed.

retroarch -L target/release/liboxid_8.so rom.ch8 ipf=20

Certain CHIP-8 programs rely on abnormal instruction behaviour (so-called "quirks") to function properly. These quirks can be enabled from the command line by specifying them after the ROM to load. The following quirks are available:

• quirk-memory: instructions that write to or read from RAM no longer increment the I register.
• quirk-shift: shift instructions now shift register VX directly instead of shifting VY and storing the result in VX
• quirk-collision: draw sprite instruction now stores the number of sprite rows that collided with an existing sprite or were clipped by the bottom of the screen in register VF
• quirk-resolution: switching between resolutions now clears the frame buffer
• quirk-lores16: permits drawing 16x16 sprites in low-resolution mode with the DXY0 instruction

As an example, the following command activates both the memory and shift quirks:

retroarch -L target/release/liboxid_8.so rom_quirks.ch8 quirk-memory quirk-shift