hachem.wtf
aboutsummaryrefslogtreecommitdiff
path: root/docs/getting-started.md
diff options
context:
space:
mode:
authorhachem <im@hachem.wtf>2026-10-16 19:15:31 +0200
committerhachem <im@hachem.wtf>2026-10-16 19:15:31 +0200
commit7684f3df95eddc3dd6836c4ed8eb8401222ae316 (patch)
treec4ecfa118fdb72c692cb1086f0404c2b18c5753b /docs/getting-started.md
parent62636576bce8e8121a3d70f63547fae40a52f697 (diff)
chore: documentationHEADmain
Diffstat (limited to 'docs/getting-started.md')
-rw-r--r--docs/getting-started.md107
1 files changed, 0 insertions, 107 deletions
diff --git a/docs/getting-started.md b/docs/getting-started.md
deleted file mode 100644
index 6781c0f..0000000
--- a/docs/getting-started.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# getting started
-
-## build the compiler
-
-hdass builds with [meson](https://mesonbuild.com/):
-
-```bash
-meson setup build
-meson compile -C build
-```
-
-that produces `build/hdass`. it has two options you need: `-o <file>` writes the
-output (default stdout), and `-t <target>` picks the assembler and architecture
-(`nasm` by default, `fasm`, or `arm64`). `build/hdass --help` lists the rest.
-
-hdass only *transpiles*: it emits assembly text, which you assemble and link
-yourself. the examples target linux, so you need an x86-64 (and
-for aarch64, an aarch64) linux toolchain. the bundled
-[docker image](../README.md#building) has `nasm`, `fasm`, an aarch64
-cross-assembler and `qemu`; the commands below run inside it:
-
-```bash
-docker compose up -d
-docker compose exec hdass bash
-```
-
-## a first program (x86-64)
-
-put this in `hello.hdass`:
-
-```hdass
-[entry: main]
-
-const SYS_WRITE = 1
-const SYS_EXIT = 60
-const STDOUT = 1
-
-data message = "Hello, hdass!\n"
-
-proc main
-{
- rax = SYS_WRITE // write(STDOUT, message, message.len)
- rdi = STDOUT
- rsi = message
- rdx = message.len
- syscall
-
- rax = SYS_EXIT // exit(0)
- rdi = 0
- syscall
-}
-```
-
-transpile, assemble, link and run:
-
-```bash
-./build/hdass hello.hdass -o hello.asm
-nasm -f elf64 hello.asm -o hello.o
-ld -e main hello.o -o hello
-./hello
-```
-
-it prints `Hello, hdass!`. `[entry: main]` exports `main` and drops its `ret`, so
-the procedure ends the program itself with the exit syscall; `ld -e main` uses it
-as the start symbol. swap `-t fasm` and `fasm hello.asm hello.o` to use fasm
-instead — the machine code is the same.
-
-## running on aarch64
-
-the same source model runs on arm, but the syscall abi differs (numbers and
-argument registers), so this program is aarch64-specific. written with the
-[`logical_registers`](targets.md#the-portable-register-model) extension so the
-registers read the same on both architectures:
-
-```hdass
-[entry: main]
-[enable: logical_registers]
-
-const SYS_EXIT = 93 // AArch64 Linux exit
-
-proc main
-{
- r1 = 42 // x0 = exit code
- r9 = SYS_EXIT // x8 = syscall number
- syscall // svc #0
-}
-```
-
-build it for aarch64 and run it under qemu:
-
-```bash
-./build/hdass -t arm64 exit.hdass -o exit.s
-aarch64-linux-gnu-as exit.s -o exit.o
-aarch64-linux-gnu-ld -e main exit.o -o exit
-qemu-aarch64 ./exit # exits 42
-```
-
-`r1` maps to `x0` and `r9` to `x8`, `syscall` becomes `svc #0`. see
-[targets](targets.md) for the register mapping and the abi tables.
-
-## next
-
-- the whole language: [language reference](language.md).
-- what runs where and why programs still carry per-architecture abi details:
- [targets](targets.md).
-- more programs to read: [examples/](../examples/) and
- [examples/arm64/](../examples/arm64/), each runnable with the steps above.