Skip to content

Installation and Usage

Jump to bottom
Michael Kamprath edited this page Sep 13, 2025 · 19 revisions

Requirements

bespokeasm requires Python 3.11 or greater.

Installation

To install, clone this repository and install using pip.

git clone git@github.com:michaelkamprath/bespokeasm.git
pip install ./bespokeasm/

Preferably, you use a python virtual environment to install BespokeASM into. For example:

git clone git@github.com:michaelkamprath/bespokeasm.git
cd bespokeasm
python3 -m venv .venv/bespokeasm
source .venv/bespokeasm/bin/activate
pip install .
bespokeasm —version

Usage

Command Summary

Command Description Config File Environment Variable
compile (default) Compile an assembly file into bytecode BESPOKEASM_COMPILE_CONFIG_FILE
update-config Update an ISA configuration file to the latest format -
generate-extension vscode Generate a VSCode language syntax highlighting extension -
generate-extension sublime Generate a Sublime Text language syntax highlighting extension -
generate-extension vim Generate Vim syntax highlighting (syntax + ftdetect) -

Compiling Byte Code

You can now compile code by running either:

bespokeasm compile -c isa-config.json awesome-code.asm

or, equivalently:

bespokeasm -c isa-config.json awesome-code.asm

The 'compile' command is the default, so you do not need to specify it explicitly. Other commands (such as 'update-config' and 'generate-extension') still require their explicit subcommand.

Supported options to the compile command are:

  • --config-file/-c - File path to the JSON or YAML instruction set architecture configuration file. Required. Can also be set with the BESPOKEASM_COMPILE_CONFIG_FILE environment variable.
  • --binary/-b or --no-binary/-n - Flag to indicate whether the binary image file containing the compiled byte code should be generated. Defaults to --binary.
  • --output-file/-o - File path to where the byte code binary image should be written. If not provided, defaults to the same file path as the input assembly file, with the file extension changed to .bin.
  • --binary-min-address/-s - The address of the generated code that should be the first address written to the output file. Defaults to 0. Useful when generating ROM images for a given address range.
  • --binary-max-address/-e - The address of the generated code that should be the last address (inclusive) written to the output file. Defaults to the maximum address of the generated byte code. If larger than the generated byte code, bytes will be padded using the binary fill value. Useful when generating ROM images for a given address range.
  • --binary-fill/-f - The word value that should be used to fill empty addresses when generating a binary image of a specific size. Defaults to 0.
  • --pretty-print/-p - When present, will emit a human readable version of the compilation. Does not emit automatically generated fill bytes, but will emit bytes created via directives such as .zerountil.
  • --pretty-print-format/-t - Indicates the format that should be used when pretty printing. Must be one of: hex, intel_hex, minhex, or listing. Defaults to listing if this option is not present.
  • --pretty-print-output - If pretty-print is enabled, this specifies the output file. Defaults to stdout.
  • --verbose/-v - Verbose output. Can be repeated for higher levels of verbosity, for example, -vvv will have a more verbose output than -v.
  • --include-path/-I - Include a specific directory in the search path for #include files in addition to the default search directory (the containing directory of the target assembly file). Can be specified multiple times.
  • --macro-symbol/-D - A preprocessor macro symbol definition. Can either be just the symbol name, in which case the value of an empty string is assumed, or a <symbol-name>=<macro-value> formatted definition. Can be specified multiple times. Not suitable for complex macro definitions; these should be done in code.

Updating ISA Configuration Files

You can update an existing instruction set architecture (ISA) configuration file to the latest format using:

bespokeasm update-config -c <config-file> [-o <output-file>]

Options:

  • --config-file/-c (required): Path to the YAML or JSON configuration file to update. Can also be set with the BESPOKEASM_UPDATE_CONFIG_CONFIG_FILE environment variable.
  • --output-file/-o: Path to write the updated configuration file. If omitted, the updated configuration is printed to stdout.

If the configuration file is already up to date, a message will be printed and no output will be written. If changes are made, the updated configuration will be written to the specified output file or to stdout.

Installing Language Extensions

BespokeASM can generate a language extension for various editors that enables several features such as syntax highlighting and code completion.

The general syntax is:

bespokeasm generate-extension editor-key -c isa-config.yaml -d /path/to/config/directory

Where editor-key is one of:

  • vscode - Visual Studio Code
  • sublime - Sublime Text
  • vim - Vim (syntax highlighting + filetype detection)

Supported options for the generate-extension command are:

  • --config-file/-c - File path to the JSON or YAML instruction set architecture configuration file. Required.
  • --verbose/-v - Verbose output. Can be repeated for higher levels of verbosity, for example, -vvv will have a more verbose output than -v.
  • --editor-config-dir/-d - The directory where the editor's configuration and extensions are installed. Defaults:
    • vscode: ~/.vscode/ - For Cursor, this should be set to ~/.cursor/
    • sublime: ~/
    • vim: ~/.vim/ - For Neovim, this should be set to ~/.config/nvim/
  • --language-name/-l - The name of the language that is reported to the editor. Defaults to the value provided in the instruction set configuration file.
  • --language-version/-k - The version string of the language that is reported to the editor. Defaults to the value provided in the instruction set configuration file, or 0.0.1 if not present. Should be formatted as a semantic version string. (Unused by Vim, kept for parity.)
  • --code-extension/-x - The file extension to identify code files of this assembly language. Defaults to asm if this option is not present.

Visual Studio Code

Visual Studio Code must be restarted for the installed language extension to take effect.

Note that in Visual Studio Code, only one extension will be used to configure a language as identified by a file extension. If you have more than one extension configuring the file extension you use to generate the language extension, Visual Studio Code might not use the language extension you generated with BespokeASM. If this happens, the best course of action is to disable the competing extension(s) for the workspace that your BespokeASM-compiled project is in.

The Visual Studio extension includes a color theme titled "BespokeASM Color Theme" that is tuned for the BespokeASM syntax highlighting. Visual Studio does not have the ability to assign a specific color scheme to specific code languages, however, this Visual Studio extension does enable this sort of feature.

Sublime Text

Once generated, move the .sublime-package file to the Installed Packages directory of the Sublime Text application settings directory. On MacOS, this can be found at ~/Library/Application Support/Sublime Text/Installed Packages. Of course, this directory can also be used for the -d option in the generate-extension command. Sublime Text must be restarted for the installed .sublime-package file to take effect.

The generated .sublime-package file includes a color scheme tuned for the BespokeASM syntax highlighting. It is recommended that this color scheme be assigned to the file type your created the .sublime-package file for (e.g., .asm). To do that, in Sublime Text open a BespokeASM assembly file, then open the Sublime Text command palette and find/select the "Preferences: Settings - Syntax Specific" command. A JSON editing window will open, then add the following item to the JSON:

    "color_scheme": "your-language-name.sublime-color-scheme"

Where your-language-name is the language name you configured in the instruction set configuration file used to generate the relevant .sublime-package file.

Vim

The Vim generator creates two files under your Vim configuration directory (default ~/.vim/):

  • syntax/<language-id>.vim: syntax highlight groups and colors
  • ftdetect/<language-id>.vim: filetype detection for your chosen code extension (e.g., *.asm)

Notes:

  • The Vim filetype is derived from your ISA name as <isa-name>-assembly, lowercased with dashes removed (e.g., bespokeasm-test-assembly → bespokeasmtestassembly).
  • After generation, restart Vim or reload your configuration. If using Neovim, the same files work in ~/.config/nvim/.
  • This generator focuses on syntax highlighting and filetype detection; it does not install snippets or language configuration.

You should add the following settings to your .vimrc file to ensure that your syntax highlighting is applied to your code files:

filetype indent plugin on
syntax on
set termguicolors

Contributions

Contributions are welcome. All contributions should pass the configured linters. A pre-commit hook can be configured to lint all code at commit time. The configuration can be found in the .pre-commit-config.yaml file in this repository. To install:

cd /path/to/bespokeasm/repository
pipenv sync --dev
pre-commit install
Clone this wiki locally