emul: update README

This commit is contained in:
Virgil Dupras 2020-06-27 07:53:58 -04:00
parent 0eb9bd090a
commit 490c57834f

View File

@ -8,16 +8,6 @@ emulator.
You need `ncurses` to build the `forth` executable. In debian-based distros,
it's `libncurses5-dev`.
## Not real hardware
In the few emulated apps described below, we don't try to emulate real hardware
because the goal here is to facilitate "high level" development.
These apps run on imaginary hardware and use many cheats to simplify I/Os.
For real hardware emulation (which helps developing drivers), see the `hw`
folder.
## Build
First, make sure that the `libz80` git submodule is checked out. If not, run
@ -27,34 +17,18 @@ After that, you can run `make` and it builds the `forth` interpreter.
## Usage
Run `./forth` to get the Collapse OS prompt. Type `0 LIST` for help.
The `./forth` executable here works like the one in `/cvm`, except that it runs
under an emulated z80 machine instead of running natively. Refer to
`/cvm/README.md` for details.
The program is a curses interface with a limited, fixed size so that it can
provide a AT-XY interface.
## Not real hardware
You can get a REPL by launching the program with [`rlwrap(1)`][rlwrap] like
this:
`./forth` doesn't try to emulate real hardware
because the goal here is to facilitate "high level" development.
rlwrap -e '' -m -S '> ' ./forth /dev/stdin
These apps run on imaginary hardware and use many cheats to simplify I/Os.
## Problems?
If the `forth` executable works badly (hangs, spew garbage, etc.),
it's probably because you've broken your bootstrap binaries. They're easy to
mistakenly break. To verify if you've done that, look at your git status. If
`forth.bin` is modified, try resetting it and then run `make clean all`. Things
should go better afterwards.
A modified `blkfs` can also break things (although even with a completely broken
blkfs, you should still get to prompt), you might want to run `make pack` to
ensure that the `blkfs` file is in sync with the contents of the `blk/` folder.
If that doesn't work, there's also the nuclear option of `git reset --hard`
and `git clean -fxd`.
If that still doesn't work, it might be because the current commit you're on
is broken, but that is rather rare: the repo on Github is plugged on Travis
and it checks that everything is smooth.
For real hardware emulation (which helps developing drivers), see the `hw`
folder.
[libz80]: https://github.com/ggambetta/libz80
[rlwrap]: https://linux.die.net/man/1/rlwrap