Skip to content

Installation and Usage

Jump to bottom
Michael Kamprath edited this page Apr 22, 2023 · 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.
  • --binary/-b or --no-binary/-n - A flag that indicates whether the binary image file containing the compiled byte code should be generated. Defaults to --generate-binary.
  • --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.
  • --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.
  • --verbose/-v - Verbose output. Can be replicated 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). Multiple include directories can be indicated with multiple instances of this option.
  • --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. Not suitable for complex macro definitions, these should be done in code.

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

Supported option for the generate-extension 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.
  • --editor-config-dir/-d - The directory where the editor's configuration and extensions are installed. Defaults to ~/.vscode/ for vscode and ~/ for sublime.
  • --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.

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 pallets 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 the language name you configured in the instruction set configuration file used to generate the relevant .sublime-package file.

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