// Copyright (C) VOLT Foundation 2024-present = vasm VOLT Foundation v1.0.0 :description: Volt compiler README.

The VOLT assembly compiler. Turns human readable instructions into usable output binaries for multiple formats.

== Optimization

The VOLT assembler conforms to the LR assembly standard and is an optimizing compiler, meaning that there are multiple passes through the procedure map that allow for smart decisions to be made about the control flow that improve the performance and size of an application.

For more on optimizations, see link:./OPTIMIZATIONS.md[the OPTIMIZATIONS file].

== Building vasm

To build the VOLT Assembly compiler, you will need to install Zig 0.14.0-dev.1671+085cc54aa or above (backward compatibility is not guaranteed). An upgrade into a newer Zig version will happen whenever the upstream tar downloads work and are at a reliable point. For Windows-esque devices, the following commands can be used:

=== Requirements

• A zig compiler (upstream currently built with Zig 0.14.0-dev.1671+085cc54aa but any Zig v0.14.0 should work fine.)
• zig build
• Git (either link:https://git-scm.com/downloads/win[Git For Windows] or link:https://git-scm.com/downloads/linux[Git Installations for Linux])
• asciidoctor (for documentation)

[source,shell]

To install:

$ git clone https://github.com/kdgonz7/vasm.git $ cd vasm $ python x.py all # to build everything $ python x.py build # to just build VASM

For Unix-like devices with make: (verify that you have sudo and git installed)

[source, shell]

To install:

$ git clone https://github.com/kdgonz7/vasm.git $ cd vasm $ make && sudo make install

To uninstall (the inverse operations of sudo make install):

$ sudo make uninstall

To make documentation (builds man pages)

$ make doc

To open the relative documentation (man/man1/vasm.1)

$ make help

To run tests

$ make tests

OR

$ make tests-summary # for a summary of passed and failed tests

== Development for vasm

The project comes with several files designed for the link:https://code.visualstudio.com/[Visual Studio Code] text editor. These include things such as building, cleaning, documentation, and testing. Other IDEs will not be worked on.

== Description

vasm is a LunarRED Assembly compiler for x86_64 machines that compiles input assembler into multiple different formats using a vendor runtime implementation of the instruction set. vasm, (historically VOLT, "Versatile Optimized Language Transpiler") follows a strict set of rules known as the LR Assembly standard, updated infrequently to provide a basis for how the language should look and perform. vasm is a modern version of the old 'VOLT' compiler which was also designed to compile into different formats, however lacked much of the security, type safety, and flexibility vasm provides.

VOLT traditionally had to be built in 32-bit or 8-bit modes respectively to compile to those destination formats. VASM instead takes a new approach using Vendors, that provide a shared API for executing, creating, and managing instructions. VASM is much more comprehensive and exhaustive than VOLT is, taking care of many abstractions to make writing LR assembly code a stable and usable experience.

=== Migrating Legacy Codebase

VASM plans to be as compatible with old assembler code as possible. The known incompatibilies of syntax between VASM and other compilers is as follows:

// as time passes, more will be here

• LunarRED (legacy) ** Uses old procedure syntax which is specifically obsoleted by the standard

Other compilers such as SIBC use the VOLT assembler syntax to compile, which is much more uncomplicated and lightweight. The syntax that is completely obsolete and never truly had a starting point was the black compiler syntax.