-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
5 additions
and
70 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> |