Skip to content

Commit

Permalink
Update Readme to reference wiki
Browse files Browse the repository at this point in the history
  • Loading branch information
nbbeeken committed Sep 16, 2019
1 parent fe81d92 commit ec5451e
Showing 1 changed file with 5 additions and 70 deletions.
75 changes: 5 additions & 70 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,76 +1,11 @@
# Dashmips

Dashmips is a Mips Interpreter CLI Program.
<img src="https://roadkillco.gallerycdn.vsassets.io/extensions/roadkillco/dashmips-debugger/0.1.2/1567790555112/Microsoft.VisualStudio.Services.Icons.Default" height="128" align="right" alt="dashmips icon">

## Requirements
`dashmips` is a Mips Interpreter CLI program.

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.
## [Documentation](https://github.com/nbbeeken/dashmips/wiki)

## Install
You can reference [this repository's wiki page](https://github.com/nbbeeken/dashmips/wiki) for CLI usage, debugging, and more!

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
```

## Running

```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).

### Debugger Protocol

The dashmips process loads the program from a file and opens a websocket. The supported commands can be found in dashmips/debug.py as functions prepended with `debug_`.
The protocol loosely follows JSONRPC for the sake of quick development iteration it is not compliant however this could be easily remedied in a future release.

## 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!
<sub>Happy coding!</sub>

0 comments on commit ec5451e

Please sign in to comment.