diff options
| -rw-r--r-- | README.txt | 48 |
1 files changed, 43 insertions, 5 deletions
diff --git a/README.txt b/README.txt index 8657dc6..e77c57f 100644 --- a/README.txt +++ b/README.txt @@ -199,19 +199,57 @@ 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. + In particular, the authoritative documentation about what basic words exist +and how to use them is language/static/core.e. If you read nothing else, you +should read that file. As of this writing, core.e has 665 lines of comments +and only 538 lines of actual code; Irenes promise this isn't just an excuse to +not write documentation. After you've read core.e, you'll know a lot of basic +words that can be used as commands within Evocation. + + Evocation takes the view that putting doucmentation and code next to each +other is strictly more useful than separating them. First, separate +documentation would be more prone to getting out of date. Second, seeing the +implementations alongside the explanations clarifies both. Often there's a +long explanation of something with a trivial implementation, and seeing both +together teaches you that, yes, this is magick, but it isn't beyond your +ability to understand - whereas seeing just the explanation would send the +opposite message. It's empowering, if you let it be. + + If you find something in the code 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. + + Thus motivated, we will now explain the overall structure of Evocation's +source code, and point out what all the major pieces are. 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 bulk of the actual code is divided among three locations: +language/static/, language/dynamic/, and compilation/. One way to think about +the code's overall structure is that first "static" is loaded, then "dynamic", +then finally "compilation". The code in "dynamic" is built out of the pieces +provided in "static", and then the code in "compilation" is built out of the +pieces provided in the other two. If you read the code in this order, every +piece you encounter, with very few exceptions, will be built out of the pieces +you've already read. + + In reality the compilation process does this all "in advance", rather than +it happening at runtime. That's why the code is able to use Evocation's +syntax, before the words to implement the syntax have been created. That's +also why the handful of very rare forward references are possible. +Nonetheless, there is still a lot of conceptual truth to be had by thinking of +it as a body of code written to run in this one specific order, building on +itself. + + So much for the linear order; now, how about categorizing the code by +subject? + The files that do the work to make Evocation run at all are compilation/execution.e and language/static/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. +both of them slowly. A lot of Evocation is written in Evocation's version of assembly language. The file language/static/amd64.e is the one that implements all the assembly |