izaya/collapseos
1
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update READMEs

Browse Source
This commit is contained in:
Virgil Dupras 2020-05-03 12:51:21 -04:00
parent 5504c796ee
commit 47a9c89f19
2 changed files with 20 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
README.md
View File

@ -27,33 +27,25 @@ github issue][forth-issue].
Documentation is lacking, it's not ready yet, this is a WIP branch. 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 Usage documentation is in-system, so access to documentation requires you to
run Collapse OS in different contexts][jsemul]. run Collapse OS. Fortunately, doing so in an emulator is easy.
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.
See `/emul/README.md` for getting an emulated system running. 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 ## Organisation of this repository
* `forth`: Forth is slowly taking over this project (see issue #4). It comes * `blk`: Collapse OS filesystem's content. That's actually where Collapse OS'
from this folder. source code is located. Everything else is peripheral.
* `recipes`: collection of recipes that assemble parts together on a specific * `recipes`: collection of recipes that assemble Collapse OS on a specific
machine. 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 * `tools`: Tools for working with Collapse OS from "modern" environments. For
example, tools for facilitating data upload to a Collapse OS machine example, tools for facilitating data upload to a Collapse OS machine
through a serial port. 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. * `tests`: Automated test suite for the whole project.
## Status ## Status
@ -63,13 +55,13 @@ for more information.
## Discussion ## 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 [web]: https://collapseos.org
[jsemul]: https://schierlm.github.io/CollapseOS-Web-Emulator/
[discussion]: https://www.reddit.com/r/collapseos [discussion]: https://www.reddit.com/r/collapseos
[listserv]: http://lists.sonic.net/mailman/listinfo/collapseos [listserv]: http://lists.sonic.net/mailman/listinfo/collapseos
[forth-issue]: https://github.com/hsoft/collapseos/issues/4 [forth-issue]: https://github.com/hsoft/collapseos/issues/4

39
emul/README.md
View File

@ -6,7 +6,7 @@ emulator.
## Not real hardware ## Not real hardware
In the few emulated apps described below, we don't try to emulate 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. 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 First, make sure that the `libz80` git submodule is checked out. If not, run
`git submodule init && git submodule update`. `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 Run `./forth` to get the COllapse OS prompt. Type `0 LIST` for help.
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.
## Problems? ## Problems?
If the libz80-wrapped zasm executable works badly (hangs, spew garbage, etc.), 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 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 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 `forth.bin` is modified, try resetting it and then run `make clean all`. Things
`make clean all`. Things should go better afterwards. should go better afterwards.
If that doesn't work, there's also the nuclear option of `git reset --hard` If that doesn't work, there's also the nuclear option of `git reset --hard`
and `git clean -fxd`. 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 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 is broken, but that is rather rare: the repo on Github is plugged on Travis
and it checks that everything is smooth. and it checks that everything is smooth.
[libz80]: https://github.com/ggambetta/libz80