Badges

asl-releases

Custom version of AS, intended to track the original source and fix some issues.

Create and install the package

You need a C development toolchain, and cmake at least 3.19. You also need Git. When everything is setup, run the following commands:

cmake -S . -B build -G <generator>
cmake --build build -j

Here, <generator> stands for any backend for cmake to use. I personally use Ninja, but you can also use any others, like Unix Makefiles, or MSYS Makefiles. Check cmake help for generators available in your platform.

To install the program, run

cmake --install build

Where the later will probably require administrative privileges.

To run tests, build as above then run:

ctest --build-run-dir build --test-dir build -j

This build procedure has been tested on the following environments:

• FreeBSD (x86-64 build)
• Mac OS X (x86-64 build) with Ninja and XCode
• OmniOS (x86-64 build)
• Ubuntu (x86-64 build)
• Windows (32- and 64-bit builds) with MinGW64/MSYS2
• Windows (64-bit build) with Microsoft Visual Studio
• WASM/Emscripten cross compiled from Linux

I would like to know if it works on other circumstances, particularly when cross-compiling.

Cross-compiling

To cross-compile, you need to have an appropriate toolchain file for your target, in addition to the actual toolchain. You start by doing a (potentially partial) host build:

cmake -S . -B build-host -G <host-generator>
cmake --build build-host -j --target rescomp

Then you do the cross-compile build itself:

cmake -S . -B build-target -G <target-generator> \
        -DIMPORT_EXECUTABLES=build-host/ImportExecutables.cmake \
        -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain/file.cmake
cmake --build build-target -j

If the toolchain file defines an appropriate emulator, you can even run the tests:

ctest --build-run-dir build-target --test-dir build-target -j

Worked cross-compile example: WASM target, Linux host

Here is a full example of how to cross-compile to WASM/Emscripten. This is based on this. Start by getting the latest SDK:

cd ~
mkdir emsdk
cd emsdk
git clone https://github.com/emscripten-core/emsdk.git .
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh   # Change this to match your shell

Then on the asl-releases directory:

cd ~
mkdir asl
cd asl
git clone https://github.com/flamewing/asl-releases.git .
cmake -S . -B build-host -G <host-generator>
cmake --build build-host -j --target rescomp
emcmake cmake -S . -B build-wasm \
        -DIMPORT_EXECUTABLES=build-host/ImportExecutables.cmake
cmake --build build-wasm -j
cmake --build build-wasm -j --target test

Building the documentation

The documentation is built by default if you have Pandoc installed and available through the PATH environment variable; otherwise, it is skipped.

"Building", in this case, means turning a loose bunch of Markdown files into a self-contained html file, which will be installed to the docs directory when running cmake --install build.

Pandoc can be installed in a few OSes as follows (adapted from this):

• Windows: there are 3 choices: either the installer, or one of the following options:

  winget install --source winget --exact --id JohnMacFarlane.Pandoc

  or

  choco install pandoc

  There is, unfortunately, no package available for MSYS2 (see the tracking issue). So if you are using this environment, you will have to add the installation path of Pandoc to the PATH environment on your profile's .bashrc.

• macOS:

  brew install pandoc

• Linux: use your distro's package manager.

• BSD: use your OS's package manager.

Preparing your disassembly

This is only relevant for Sonic disassemblies based on older versions of the Sonic Retro community disassemblies.

More recent versions of AS have made a few changes that impact older disassemblies. Here are the changes and how to deal with them:

• AS by default will look for includes in the directory of the current file being assembled. This has an effect on files being included by other files inside a subdirectory. In the S2 Git disassembly, this issue was dealt with in this commit, which just adds the disassembly's directory to the command line.
• moveq no longer silently sign-extends a value; instead, it gives an error if you do use a value that cannot be represented as a byte sign-extended to 32-bits. This issue was dealt with in this commit in the S2 Git disassembly.
• phase/dephase were changed to be a stack: you now need a matching dephase for every phase. This issue was dealt with in this commit in the S2 Git disassembly.
• Adding a character constant to an integer results in a character constant, which can overflow the limits of a character and give an error. This issue was dealt with in this commit in the S2 Git disassembly.