1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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
|