Metadata-Version: 2.1
Name: dashmips
Version: 0.1.0
Summary: Mips Interpreter
Home-page: https://github.com/nbbeeken/dashmips
License: MIT
Author: Neal Beeken
Author-email: nbbeeken@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Assembly
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Assemblers
Requires-Dist: dataclasses (>=0.6,<0.7); python_version == "3.6"
Requires-Dist: websockets (>=8.0.2,<9.0.0)
Project-URL: Repository, https://github.com/nbbeeken/dashmips
Description-Content-Type: text/markdown

# Dashmips

Dashmips is a Mips Interpreter CLI Program.

## Requirements

Dashmips has no dependencies beyond requiring `python 3.7`.
There is a dataclasses module for python 3.6 that may make this module work but it is untested.

## Install

The recommended way to install dashmips is with pip:

```sh
pip install dashmips
```

## Usage

If you installed via pip you should now have a binary in your path that you can launch by typing:

```sh
dashmips
```

or equivalently

```sh
python -m dashmips
```

## "Compiling"

To compile or run a mips program you run:

```sh
dashmips compile FILE.mips
```

What "compilation" means in dashmips is a conversion of the source file to a json format that is better understood by the program. You can use this json format to inspect the internals of how your mips program is interpreted by dashmips.

## Running

This one's easy:

```sh
dashmips run FILE.mips
```

> Note: FILE is a positional argument in the run subcommand

## Debugging

In order to leave a flexible environment for debugging dashmips doesn't provide an interface for human debugging of a mips program. Instead the debugger included is a server that accepts the json format of a mips program over the network and will do the requested operations returning an updated MipsProgram json object.

There is a vscode extension that can speak dashmips specific json language [here](https://github.com/nbbeeken/dashmips-debugger).

### Debugging protocol

Small notes about the protocol if you want to proceed with a manual debugging. The JSON you send to the debug server is expected to take the following format:

```ts
interface DebugMessage {
    command: 'start' | 'step' | 'continue' | 'stop';
    program: MipsProgram;  // MipsProgram can be found in `dashmips/models.py`
    // properties below are optional
    breakpoints?: number[];
    message?: string;
    error?: boolean;
}
```

The commands listed are `start`, `step`, `continue`, and `stop`. In short each operation does the following:

- Start: sets the pc to the main label
- Step: runs exactly one instruction from current pc
- Continue: runs as many instructions as there are between current pc and a breakpoint
- Stop: Does nothing

The server is designed to be stateless so it can handle many clients at once.

## Contributing

### Getting Setup

If you want to contribute to the dashmips project you will need the following:

- [Poetry](https://poetry.eustace.io/docs/) is used for dependencies, it will help get you up and running
- After installing Poetry, and cloning this repository:
- `poetry install` - will install the dashmips dependencies in a virtual environment that won't harm your global set up.
- `poetry run X` - can run X command in the correct python environment
- Try `poetry run pytest --tap-stream --tap-outdir=testout --mypy --docstyle --codestyle` to ensure all tests are passing correctly


### Adding Syscalls / Adding Instructions

You can add to the existing files in the `dashmips/instructions` and `dashmips/syscalls` directories using the relevant decorator (`@`).
If you add instructions or syscalls to a new file in these subdirectories ensure that the new file is named with the pattern: `*_instructions.py` or `*_syscalls.py` where `*` is whatever identifier you choose.

### Testing environment install

To make sure dashmips installs correctly in a clean environment I've created a dockerfile that sets up the minimal required env for dashmips. The command below can be used to create the image.

```sh
docker build --rm -f "tests\test_env\Dockerfile" -t dashmips_test_env:latest .
```

Happy coding!

