https://github.com/kinderjosh/minstral-vm
Minstral (short for Minimal Instruction Translator) contains a virtual machine, assembler and disassembler.
https://github.com/kinderjosh/minstral-vm
assembly virtual-machine
Last synced: about 1 month ago
JSON representation
Minstral (short for Minimal Instruction Translator) contains a virtual machine, assembler and disassembler.
- Host: GitHub
- URL: https://github.com/kinderjosh/minstral-vm
- Owner: kinderjosh
- License: bsd-3-clause
- Created: 2025-07-24T22:09:47.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-27T15:03:02.000Z (11 months ago)
- Last Synced: 2025-07-27T15:16:00.040Z (11 months ago)
- Topics: assembly, virtual-machine
- Language: C
- Homepage:
- Size: 89.8 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Minstral VM
Minstral (short for Minimal Instruction Translator) contains a virtual machine, assembler and disassembler.
## Installation
All you need is ```gcc``` and ```make```, then clone the repository and run the makefile as root:
```bash
git clone https://github.com/kinderjosh/minstral-vm.git
cd minstral-vm
sudo make install
```
## Usage
```
mas [options]
```
### Commands
| Name | Description |
| --- | --- |
| asm | Assemble a machine code file. |
| dis | Disassemble a machine code file. |
| exe | Execute a machine code file. |
| run | Assemble and execute a machine code file. |
### Options
| Name | Description |
| --- | --- |
| -linebreak | Output linebreaks in machine code. |
| -o `````` | Specify the output filename. |
## Examples
### Assembling
Use the ```asm``` command to convert an assembly file to a machine code file.
> [examples/hi.min](./examples/hi.min):
```asm
; simple program that prints "Hi"
.text
opc 'H' ; print character H
opc 'i' ; print character i
opc '\n' ; print a new line
hlt ; stop execution
```
Assemble it:
```console
$ mas asm examples/hi.min
```
a.out:
```asm
7 72 7 105 7 10 1 0
```
### Disassembling
Use the ```dis``` command to convert a machine code file to an assembly file.
(Using the same example from above):
```console
$ mas dis a.out
```
dis.min:
```asm
opc 72
opc 105
opc 10
hlt
```
### Executing
Use the ```exe``` command to execute a machine code file.
(Using the same example from above):
```console
$ mas exe a.out
Hi
```
### Running
You can assemble and execute an assembly file at once with the ```run``` command.
```console
$ mas run examples/hi.min
Hi
```
## Syntax Highlighting
Syntax highlighting for VSCode is available in the [editor](./editor/) directory in the form of a VSIX file.
## Documentation
See the [manual](https://github.com/kinderjosh/minstral-vm/wiki).
## License
Minstral is distributed under the [BSD 3-Clause](./LICENSE) license.