DOCSEARCHbyAlgolia
Submit Docs

libSFX Super Nintendo Assembler Development Framework

repository·master·Indexed 42 days ago

https://github.com/optiroc/libsfx

A development framework for the Super Nintendo (SNES) providing a system runtime, register tracking macros, data transfer routines, S-SMP communication, and drivers for mouse and LZ4. Includes syntax highlighting extensions for ca65 assembler (65816, SPC700, and GSU-1/SuperFX) for Visual Studio Code and Sublime Text.

Tokens
1.7K
Snippets
6
Records
13
Agent score
54%

What's inside libSFX

  4. Install dependencies for libSFX

    master

    To use libSFX, you need a C/C++ toolchain, make, git, and a command line interface.

    • Unix-like (Mac, Linux, etc.): Should work out of the box.
    • Windows: It is recommended to install Cygwin and include the following mingw64 toolchain packages:
      • mingw64-x86_64-binutils
      • mingw64-x86_64-gcc-core
      • mingw64-x86_64-gcc-g++

  6. Install libSFX VS Code syntax definitions

    master

    To use the syntax definitions for the ca65 assembler (supporting 65816, SPC700, and GSU-1/SuperFX instruction sets) in Visual Studio Code, manually install the extension by copying the provided folders into your VS Code extensions directory.

    Installation Path: ~/.vscode/extensions

    # Manual installation via terminal (example)
cp -r ./extras/VisualStudioCode ~/.vscode/extensions/

  7. Build libSFX and its bundled tools

    master

    libSFX includes several tools as git submodules that must be built first. Run make from the libSFX root directory to initialize the submodules and build these tools. Once completed, you can run make from any example directory to assemble source files and link a Super Nintendo ROM image (*.sfc).

    # From the libSFX root path
make

  8. Set up a new libSFX project

    master

    To start a new project, use the provided template:

    1. Copy examples/Template to your desired project location.
    2. Open the Makefile in your project directory.
    3. Ensure the libsfx_dir variable points to the absolute path of your libSFX root directory.
    # In your project's Makefile
libsfx_dir = /path/to/your/libsfx_root

  9. Install libSFX syntax definitions for Sublime Text

    master

    To enable syntax highlighting for the ca65 assembler with 65816, SPC700, and GSU-1 (SuperFX) instruction sets in Sublime Text, manually install the syntax files:

    1. Locate the *.tmLanguage files in this repository.
    2. Copy them to your Sublime Text user package directory.
    3. (Optional) Copy any *.sublime-settings files to the same directory to apply specific configurations.

    Common User Package Paths:

    • macOS (Sublime Text 3): ~/Library/Application Support/Sublime Text 3/Packages/User
    • Windows: %APPDATA%\Sublime Text 3\Packages\User
    • Linux: ~/.config/sublime-text/Packages/User
    # Example path for macOS
~/Library/Application\ Support/Sublime\ Text\ 3/Packages/User

  10. NaturalDocs file format conventions

    master

    When interacting with or extending the binary file formats used by NaturalDocs, adhere to these conventions:

    • Endianness: All integers are stored in big-endian format. For example, a UInt16 should be handled using the 'n' flag in Perl's pack and unpack functions.
    • UString16: This type consists of a big-endian UInt16 followed by that many UTF-8 bytes. It does not include a null-terminator.
    • Opaque Types: If a high-level type (like <SymbolString>) is described in a format, the loading and saving logic is encapsulated within that package (e.g., <NaturalDocs::SymbolString->ToBinaryFile()>). Treat these underlying formats as opaque.

  11. Understand NaturalDocs basic types

    master

    The NaturalDocs engine uses several specialized types for internal consistency. While Perl is weakly typed, these types define how data is handled:

    • FileName: An absolute, platform-dependent string representing a file path. All path manipulation must be performed via <NaturalDocs::File>. Relative paths are not supported.
    • VersionInt: A comparable integer representing a version number. Conversion to/from text or binary is handled by <NaturalDocs::Version>.
    • SymbolString: A scalar encoding a normalized array of identifier strings representing a full or partially-resolved symbol. To ensure consistent separation and normalization, all symbols must be retrieved from plain text using <NaturalDocs::SymbolString->FromText()>. These are comparable and sortable.
    • ReferenceString: A string encoding all information that makes a reference unique, including its <SymbolString>, its scope <SymbolString>, the scope <SymbolStrings> it has access to via "using", and its <ReferenceType>.

  12. Customize project configuration and memory maps

    master

    By default, libSFX uses configuration files located in $(libsfx_dir)/include/Configurations. To customize your project (e.g., extending ROM size, adding SRAM, defining special code segments, or changing stack/scratchpad sizes), you must provide your own configuration files in your project's root directory.

    Required files for customization:

    • libSFX.cfg
    • Map.cfg

    To override defaults, copy the files from $(libsfx_dir)/include/Configurations into your project directory and edit them. You can find additional Map.cfg examples in that same directory, or study the examples/SixteenMegaPower and examples/SuperFX projects for reference.