From 96b9c1bf8db5786c577a38ecdbfc0d110660e17b Mon Sep 17 00:00:00 2001
From: Eduard Urbach <eduard@urbach.dev>
Date: Sat, 5 Jul 2025 15:30:13 +0200
Subject: [PATCH] Updated documentation

---
 docs/readme.md | 63 +++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 8 deletions(-)

diff --git a/docs/readme.md b/docs/readme.md
index b916b66..35c4f30 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -1,8 +1,6 @@
 # q
 
-A programming language that quickly compiles to machine code.
-
-## Goals
+A programming language including compiler, assembler and linker with the following goals:
 
 - Fast compilation
 - High performance
@@ -10,45 +8,94 @@ A programming language that quickly compiles to machine code.
 
 ## Installation
 
+Build:
+
 ```shell
 git clone https://git.urbach.dev/cli/q
 cd q
 go build
 ```
 
+Symlink:
+
+```shell
+ln -s $PWD/q ~/.local/bin/q
+```
+
 ## Usage
 
+Build:
+
 ```shell
 q build examples/hello
+```
+
+Run:
+
+```shell
 ./examples/hello/hello
 ```
 
 ## Tests
 
+To run all tests:
+
 ```shell
 go run gotest.tools/gotestsum@latest
 ```
 
+Every package must pass its unit tests.
+
+The code coverage should ideally be around 80-100% for each package.
+
+Integration tests that test the output of the produced executables are located in the dedicated `tests` directory.
+
 ## Platforms
 
-You can cross-compile executables for Linux, Mac and Windows using arm64 or x86-64.
+### Matrix
+
+|         | arm64  | x86-64 |
+| ------- | ------ | ------ |
+| Linux   | ✔️     | ✔️     |
+| Mac     | ✔️*    | ✔️     |
+| Windows | ✔️*    | ✔️     |
+
+Those marked with a star are supported in theory but there are no developer machines to test them.
+
+### Cross compilation
+
+Compilation for a different target is supported out of the box:
 
 ```shell
 q build examples/hello --os linux
 q build examples/hello --os mac
 q build examples/hello --os windows
+```
+
+```shell
 q build examples/hello --arch x86
 q build examples/hello --arch arm
 ```
 
-| CPU    | Linux | Mac | Windows |
-| ------ | ----- | --- | ------- |
-| arm64  | ✔️    | ❔  | ❔      |
-| x86-64 | ✔️    | ✔️  | ✔️      |
+## Security
+
+### PIE
+
+All executables are built as Position Independent Executables (PIE) supporting a dynamic base address.
+
+### Memory pages
+
+Code and data are separated into different memory pages and loaded with different access permissions.
+
+|        | Read | Execute | Write |
+| ------ | ---- | ------- | ----- |
+| Code   | ✔️   | ✔️      | ❌    |
+| Data   | ✔️   | ❌      | ❌    |
 
 ## Status
 
 `q` is under heavy development and not ready for production yet.
+
 Feel free to [get in touch](https://urbach.dev/contact) if you are interested in helping out.
 
 ## License