diff options
Diffstat (limited to 'docs/getting-started.md')
| -rw-r--r-- | docs/getting-started.md | 44 |
1 files changed, 22 insertions, 22 deletions
diff --git a/docs/getting-started.md b/docs/getting-started.md index 6f90618..6781c0f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,22 +1,22 @@ -# Getting started +# getting started -## Build the compiler +## build the compiler -hdass builds with [Meson](https://mesonbuild.com/): +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 +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 +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 @@ -24,9 +24,9 @@ docker compose up -d docker compose exec hdass bash ``` -## A first program (x86-64) +## a first program (x86-64) -Put this in `hello.hdass`: +put this in `hello.hdass`: ```hdass [entry: main] @@ -51,7 +51,7 @@ proc main } ``` -Transpile, assemble, link and run: +transpile, assemble, link and run: ```bash ./build/hdass hello.hdass -o hello.asm @@ -60,15 +60,15 @@ ld -e main hello.o -o hello ./hello ``` -It prints `Hello, hdass!`. `[entry: main]` exports `main` and drops its `ret`, so +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 +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 +## 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 +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: @@ -86,7 +86,7 @@ proc main } ``` -Build it for AArch64 and run it under qemu: +build it for aarch64 and run it under qemu: ```bash ./build/hdass -t arm64 exit.hdass -o exit.s @@ -95,13 +95,13 @@ 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. +`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 +## next -- The whole language: [language reference](language.md). -- What runs where and why programs still carry per-architecture ABI details: +- 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 +- more programs to read: [examples/](../examples/) and [examples/arm64/](../examples/arm64/), each runnable with the steps above. |