From 47a9c89f193449566a7a22a10aded07540150e2d Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Sun, 3 May 2020 12:51:21 -0400 Subject: [PATCH] Update READMEs --- README.md | 34 +++++++++++++--------------------- emul/README.md | 39 +++++++-------------------------------- 2 files changed, 20 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index dafd434..48a4baf 100644 --- a/README.md +++ b/README.md @@ -27,33 +27,25 @@ github issue][forth-issue]. Documentation is lacking, it's not ready yet, this is a WIP branch. -## See it in action +## Getting started -Michael Schierl has put together [a set of emulators running in the browser that -run Collapse OS in different contexts][jsemul]. - -Using those while following along with the [User Guide](doc/) is your quickest -path to giving Collapse OS a try. - -## Documentation - -Usage documentation is in-system. Run `0 LIST` for an introduction. You can -also open `blk/000` in a modern text editor. +Usage documentation is in-system, so access to documentation requires you to +run Collapse OS. Fortunately, doing so in an emulator is easy. See `/emul/README.md` for getting an emulated system running. +Then, run `0 LIST` for an introduction, follow instructions from there. + ## Organisation of this repository -* `forth`: Forth is slowly taking over this project (see issue #4). It comes - from this folder. -* `recipes`: collection of recipes that assemble parts together on a specific +* `blk`: Collapse OS filesystem's content. That's actually where Collapse OS' + source code is located. Everything else is peripheral. +* `recipes`: collection of recipes that assemble Collapse OS on a specific machine. -* `blk`: Collapse OS filesystem's content. See `000` for intro. -* `doc`: User guide for when you've successfully installed Collapse OS. * `tools`: Tools for working with Collapse OS from "modern" environments. For example, tools for facilitating data upload to a Collapse OS machine through a serial port. -* `emul`: Emulated applications. +* `emul`: Tools for running Collapse OS in an emulated environment. * `tests`: Automated test suite for the whole project. ## Status @@ -63,13 +55,13 @@ for more information. ## Discussion -For a general discussion of Collapse OS and the ecosystem of technologies and ideas that may develop around it refer to [r/collapseos][discussion] +For a general discussion of Collapse OS and the ecosystem of technologies and +ideas that may develop around it refer to [r/collapseos][discussion] -A more traditional [mailing list][listserv] and IRC (#collapseos on freenode) channels are also maintained. +A more traditional [mailing list][listserv] and IRC (#collapseos on freenode) +channels are also maintained. -[libz80]: https://github.com/ggambetta/libz80 [web]: https://collapseos.org -[jsemul]: https://schierlm.github.io/CollapseOS-Web-Emulator/ [discussion]: https://www.reddit.com/r/collapseos [listserv]: http://lists.sonic.net/mailman/listinfo/collapseos [forth-issue]: https://github.com/hsoft/collapseos/issues/4 diff --git a/emul/README.md b/emul/README.md index 8103a62..44181da 100644 --- a/emul/README.md +++ b/emul/README.md @@ -6,7 +6,7 @@ emulator. ## 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 userspace development. +because the goal here is to facilitate "high level" development. These apps run on imaginary hardware and use many cheats to simplify I/Os. @@ -18,44 +18,17 @@ folder. First, make sure that the `libz80` git submodule is checked out. If not, run `git submodule init && git submodule update`. -After that, you can run `make` and it builds all applications. +After that, you can run `make` and it builds the `forth` interpreter. -## forth - -Collapse OS' Forth interpreter, which is in the process of replacing the -zasm-based project. - -The Forth interpreter is entirely self-hosting, that is, it assembles its -binary with itself. - -There are 3 build stages. - -**Stage 0**: At this stage, all we have are our bootstrap binaries, `boot.bin` -and `z80c.bin`. We concatenate them into `forth0.bin` ans then wrap the -emulator around it which is named `stage1` (because it builds the stage 1) to -have a barebone forth interpreter. - -**Stage 1**: The `stage1` binary allows us to augment `forth0.bin` with -the compiled dictionary of a full Forth interpreter. We feed it with -`$(FORTHSRCS)` and then dump the resulting compiled dict. - -From there, we can create `forth1.bin`, which is wrapped by both the `forth` -and `stage2` executables. `forth` is the interpreter you'll use. - -**Stage 2**: `stage2` is used to resolve the chicken-and-egg problem and use -the power of a full Forth intepreter, including an assembler, to assemble -`z80c.bin`. This is a manual step executed through `make updatebootstrap`. - -Normally, running this step should yield the exact same `boot.bin` and -`z80c.bin` as before, unless of course you've changed the source. +Run `./forth` to get the COllapse OS prompt. Type `0 LIST` for help. ## Problems? If the libz80-wrapped zasm 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 -`boot.bin` or `z80c.bin` are modified, try resetting them and then run -`make clean all`. Things should go better afterwards. +`forth.bin` is modified, try resetting it and then run `make clean all`. Things +should go better afterwards. If that doesn't work, there's also the nuclear option of `git reset --hard` and `git clean -fxd`. @@ -63,3 +36,5 @@ 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. + +[libz80]: https://github.com/ggambetta/libz80