Permalink
Newer
Older
100644 33 lines (27 sloc) 2.25 KB
1
### Warning: This file is currently out-of-date!
2
3
When reading portions of this codebase, there’s a couple of things you should be aware of:
4
5
1. We *really like* using macros to modify how code is passed around. A thorough scan of the `EXTERNALIZE`
6
and `DECLARATIONS`/`IMPLEMENTATION` systems will make reading Paws.c source code a *lot* easier, and a *lot*
7
more fun. It’s worth your time.
8
2. Our ISO C is not your CS teacher’s ISO C, or for that matter, anybody else’s ISO C. It follows a very
9
specific series of style guidelines that dictates everything from the alignment of an indirection asterisk to
10
the number of space characters between return types and functions’ names. While our code is *not* the C
11
you’ve become previously familiar with, it’s *very* clean, beautiful, and readable by comparison. It’s more
12
of a bastard child of Ruby and D, than plain ol’ butt-ugly C.
13
14
That said, without further ado...
15
16
The Sightseer’s Guide to Paws.c
17
===============================
18
The Paws.c codebase tends towards oddity; there’s quite a few interesting nooks and crannies you might discover
19
as you explore. This document will attempt to document your way towards the more unusual or interesting of these.
20
21
- Understanding the small CPP macros utilized absolutely *pervasively* throughout this codebase is essential to
22
being able to understand the codebase itself. I suggest you start with the thorough documentation of the
23
‘externalization’ system in `Source/Core.h`.
24
- Our `thing` annotated-pointer type is very central to the implementation of our object system; you can read
25
more about it in `Source/Types/Types.h`
26
- The API bootstrapping spans almost every file in the codebase. You’ll want to start with the `construct()`
27
function in `Source/Paws.c` and work your way through the various `register_*` functions defined in each
28
individual file.
29
- Our “tests” are written using a neat little test-running tool named `Cest.`; it’s very self-contained and easy
30
to understand. See the source-code in `Vendor/Cest.c`.
31
- Most of our object system depends on the `fork` nuketype (as you probably know if you’re reading this), and the
32
`fork` type depends heavily on our unusual linked-list implementation. See `Source/Types/fork/LL.c`.