add readme and license

1 files changed, 58 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c2ff956
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# P4Dcc
+
+P4Dcc is a tiny, but self-hosted C compiler. It takes C source code and compiles it to assembly language. For assembling and linking, I use gcc as-is.
+
+This project was started to test the hypothesis: "Could a self-hostable C compiler be built in four days, if the feature set is carefully limited?" - "P4D" stands for the ISO 8601 notation meaning "four days." However, I actually completed the project by the morning of the third day.
+
+The code is written following the instructions at https://www.sigbus.info/compilerbook, and several key design decisions were inspired by the book.
+
+
+## Dependencies
+
+* gcc
+* [just](https://github.com/casey/just), a general-purpose task runner
+
+
+## Build
+
+```
+$ just build
+```
+
+
+## Test
+
+```
+$ just test
+$ just test-all  # test all things, including binary equiality between generations
+```
+
+
+## Design
+
+To meet the four-day goal, many design decisions were made to reduce complexity (ideas directly taken from https://www.sigbus.info/compilerbook are not listed):
+
+* Simplify declaration syntax
+    * No support for `typedef`
+        * Structs always begin with `struct` keyword
+    * No support for array types
+        * No stack-allocated arrays
+        * All arrays are heap-allocated and accessed via pointers
+    * No support for function types
+    * Type information always precede the variable name
+* Most syntax sugar is not implemented
+    * No increment/decrement operators
+    * No compound assignment operators
+    * No `while`
+* Limited preprocessor
+    * Supports only simple `#define` that replaces identifiers with integer literals
+* No global variables
+    * Including `stdin`, `stdout`, and `stderr`
+    * Only function/struct definitions/declarations are allowed at the top level
+* No variable shadowing
+    * All variables are function-scoped
+
+
+## License
+
+See [LICENSE](./LICENSE).