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.
## 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

39
emul/README.md
View File

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