diff options
| -rw-r--r-- | README.txt | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..88a7147 --- /dev/null +++ b/README.txt @@ -0,0 +1,88 @@ +~~~~~~~~~~~~~~ +~~ Welcome! ~~~~~~ +~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~ + + The documentation is a work in progress. It doesn't say most of the things +it needs to, yet. + + + ~~~~~~~~~~~~ +~~ Building ~~ + ~~~~~~~~~~~~ + + To get started, first build the flatassembler version: + + $ fasmg quine.asm quine + $ chmod 755 quine + + This is a working Evocation interpreter, but it's incomplete and will become +more so with time. So, next, build Evocation-in-Evocation: + + $ (cat labels.e elf.e transform.e execution.e; echo 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e; echo pyrzqxgl 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e ; echo pyrzqxgl; cat evoke.e) | ./quine > evoke + $ chmod 755 evoke + + Finally, rebuild Evocation-in-Evocation with itself: + + $ (cat labels.e elf.e transform.e execution.e; echo 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e; echo pyrzqxgl 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e ; echo pyrzqxgl; cat evoke.e) | ./evoke > evoke2 + $ chmod 755 evoke2 + + Now keep your evoke binary somewhere safe, and use it to build new versions +as you modify Evocation. + + + ~~~~~~~~~~~~~ +~~ Exploring ~~ + ~~~~~~~~~~~~~ + + You can now try out Evocation. Type to it interactively: + + $ ./evoke + ." Hi, Irenes!" + 6 7 * . newline + bye + + See what it prints! + + Some helpful words to try to get started are list-dictionary and describe. + + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~ Reading Evocation's source code ~~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Even if you're only interested in using Evocation, not in modifying it, we +encourage you to at least skim through the source. If you've looked at it, +even a little, it won't be so scary next time. It's heavily commented and +meant for anyone with a little programming knowledge to be able to read, even +if you've never done systems programming before. + + If you find something in it confusing, please don't be afraid to ask! It's +likely other people are confused too, and sharing your questions helps improve +the documentation and lets others learn by watching. + + The top-level source file whose job is to compile Evocation itself is +evoke.e. It's really short, and worth a quick glance right now. It lists all +the other source files and the order they get loaded in and how they're +processed. + + The files that do the work to make Evocation run at all are execution.e and +core.e. It's worth reading through both of them slowly. After you've read +core.e, you'll know a lot of basic words that can be used as commands within +Evocation. + + A lot of Evocation is written in Evocation's version of assembly language. +The file amd64.e is the one that implements all the assembly instructions. +Writing a real program in assembly also requires resolving labels, which are +a special syntax that gives names to addresses. The behavior of labels is all +implemented in labels.e. + + On the assembly language front, there's also linux.e which contains assembly +words for doing things specific to the Linux operating system, such as reading +input, and there's elf.e which contains words for outputting the special file +headers that let the operating system understand that a file is an executable +program. + + TODO output.e interpret.e dynamic.e flow-control.e execution-support.e + |