Skip to content

Installation and Usage

Jump to bottom
Michael Kamprath edited this page Jan 4, 2022 · 15 revisions

Requirements

bespokeasm requires Python 3.9 or greater.

Installation

To install, clone this repository and install using pip. Preferably, you have a python virtual environment set up when you do this.

git clone [email protected]:michaelkamprath/bespokeasm.git
pip install ./bespokeasm/

Usage

Compiling Byte Code

Once installed, assembly code can be compiled in this manner:

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

Supported options to the compile command are:

  • --config-file/-c - File path the JSON or YAML instruction set architecture configuration file. Can also be set with the BESPOKEASM_COMPILE_CONFIG_FILE environment variable. It is required to set the configuration file either by this option of the environment variable.
  • --output-file/-o - File path to where the byte code binary image should be written. If note provided, it will default 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 byte value that should be used to fill empty addresses when generating 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 generate fill bytes, but will emit bytes created via directives such as .zerountil.
  • --verbose/-v - Verbose output. Can be replicated for higher levels of verbosity, for example, -vvv will have a more verbose output than -v.
  • -include/-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). Multiple include directories can be indicated with multiple instances of this option.

Installing Language Extensions

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

Visual Studio Code

To install the language extension for Visual Studio Code:

bespokeasm generate-extension vscode -c isa-config.yaml

Supported option for the generate-extension vscode command are:

  • --config-file/-c - File path the JSON or YAML instruction set architecture configuration file. Can also be set with the BESPOKEASM_COMPILE_CONFIG_FILE environment variable. It is required to set the configuration file either by this option of the environment variable.
  • --verbose/-v - Verbose output. Can be replicated for higher levels of verbosity, for example, -vvv will have a more verbose output than -v.
  • --vscode-config-dir/-d - The directory where Visual Studio Code's configuration and extensions are installed. Defaults to ~/.vscode/ if not specified.
  • --language-name/-l - The name of the language that is reported to Visual Studio Code. Defaults to the concatenation of the configuration file's general/identifier/name field and the string -assembly, or if that is not present, then the configuration file's base name.
  • --language-version/-k - The version string of the language that is reported to Visual Studio Code. Defaults to the configuration file's general/identifier/version value, or if that is not present, then 0.0.1. Should be formatted as a semantic version string.
  • --code-extension/-x - The file extension to identify code files of this assembly language. Defaults to asm if this option is not present.

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.

Clone this wiki locally