hachem.wtf
aboutsummaryrefslogtreecommitdiff
path: root/README.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 /README.md
parent62636576bce8e8121a3d70f63547fae40a52f697 (diff)
chore: documentationHEADmain
Diffstat (limited to 'README.md')
-rw-r--r--README.md45
1 files changed, 9 insertions, 36 deletions
diff --git a/README.md b/README.md
index 419c6e5..1f7d161 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
# hdass
-hachem's dumb assembly super-set, pronounced "hd ass", or "headass"...depends on how you feel that day.
+hachem's dumb assembly super-set, pronounced "hd ass", or "headass" depending on your mood.
-the entire point of this project is to provide a middle ground between c and assembly. if we think about why we still write assembly today, it's usually because we need direct control over what the cpu is doing. we want control over the exact instructions being executed, the memory, the stack and everything else that higher-level programming languages normally abstract away. the thing is, not every program written in assembly actually needs that control. sometimes you want to write something close to the machine without having to manuall deal with every tiny detail yourself. you still want registers, explicit control over memory and a good understanding of what your program is doing, but you don't necessarily need to manually express everything as individual assembly instructions.
+the entire point of this project is to provide a middle ground between c and assembly because if we think about why we still write assembly today, it's usually because we need direct control over what the cpu is doing. we want control over the exact instructions being executed, the memory, the stack and everything else that higher level programming languages like c normally abstract away. the thing is, not every program written in assembly actually needs allat. sometimes you want to write something close to the machine without having to manuall deal with every tiny detail yourself. this is where this piece of shit comes in.
-this is where this piece of shit comes in. it's not quite high-level enough to be a c-like language, but it's also not low-level enough to be as annoying to write as raw assembly. the goal is to sit somewhere in between, keeping the parts of assembly that make it useful while making the parts that don't need to be painful a little nicer to work with. hdass transpiles into multiple flavours of assembly, currently nasm and fasm (masm is planned), rather than directly producing machine code. the idea is to provide a single language for writing low-level programs while allowing the backend to translate code into the assembler syntax you want to target. you're still ultimately producing assembly, and you're never particularly far away from the code that gets assembled. the goal isn't to hide the machine from you or turn assembly into c. there are already plenty of high-level languages that do that. hdass just fills the gap between the two, where you might want some more convenience whilst writing assembly without taking away the reason you wanted to work close to the machine in the first place.
+it's not quite high level enough to be a c like language, but it's also not low level enough to be as annoying to write as raw assembly. the goal is to sit somewhere in between, keeping the parts of assembly that make it useful while making the parts that don't need to be painful less of unlubricated dildo levels of pain. hdass transpiles into multiple flavours of assembly, currently nasm and fasm (masm is planned unfortunately), rather than directly producing machine code. the idea is to provide a single language for writing low level programs while allowing the backend to translate code into the assembler syntax you want to target, totally not because i didn't want to make an assembler manually. you're still ultimately producing assembly, and you're never particularly far away from the code that gets assembled.
## examples
here's a simple "hello, world!" world program written using hdass' syntax:
@@ -31,34 +31,24 @@ proc main
}
```
-the program still directly controls the registers used for the system calls. nothing is hiding what the program is doing. more examples can be found in [examples/](examples/).
+more shit can be found in [examples/](examples/).
-## documentation
-the docs live in [docs/](docs/):
-
-- [getting started](docs/getting-started.md) — build the compiler, write and run a first program on x86-64 and aarch64.
-- [language reference](docs/language.md) — directives, declarations, statements, control flow, memory, floats, raw instructions and extensions.
-- [targets](docs/targets.md) — architectures and assemblers, what each supports, and the per-architecture syscall abis.
-- [internals](docs/internals.md) — the compiler pipeline and how to add a backend or architecture.
+## docs
+> some day lmao
## building
-the build is driven by [meson](https://mesonbuild.com/). configure a build directory and compile the compiler:
+the build is with by meson:
```bash
meson setup build
meson compile -C build
```
-this produces the `hdass` binary at `build/hdass`. the default build turns on the address and undefined-behaviour sanitizers; for an optimised build without them, configure a separate directory:
+this produces the `hdass` binary at `build/hdass`. the default build turns on the address and undefined-behaviour sanitizers, for an optimised build without them, configure a separate directory:
```bash
meson setup build-release --buildtype=release -Db_sanitize=none
meson compile -C build-release
```
-to run the unit tests:
-```bash
-meson test -C build
-```
-if [cppcheck](https://cppcheck.sourceforge.io/) is installed, `ninja -C build cppcheck` runs static analysis over the sources.
-hdass emits x86-64 assembly, so to actually assemble and run its output you need an x86-64 linux toolchain. the bundled docker environment provides a consistent one on any host, including apple silicon, where the amd64 image runs under emulation. the image is a debian base with `nasm`, `fasm`, `ld` (binutils), a c toolchain and meson/ninja preinstalled.
+hdass emits x86-64 assembly, so to actually assemble and run its output you need an x86-64 linux toolchain. since it's a pain in the ass to actually use, i bundled a docker environment.
start the container (this builds the image the first time):
```bash
@@ -79,23 +69,6 @@ ld -e main hello.o -o hello
./hello
```
-hdass targets nasm by default; pass `-t fasm` to emit fasm instead, which assembles in a single step:
-```bash
-./build-linux/hdass -t fasm examples/hello_world.hdass -o hello.asm
-fasm hello.asm hello.o
-ld -e main hello.o -o hello
-```
-
-to transpile, assemble, link and run every program in [examples/](examples/) and check its output, use the end-to-end test script (also from inside the container):
-```bash
-meson setup build-linux && meson compile -C build-linux && ./scripts/test_examples.sh
-```
-
-or, from the host, run the whole suite (unit tests plus the example tests) in one shot, bringing the container up if needed:
-```bash
-./scripts/docker_test.sh
-```
-
to build, assemble, link and run a single program in the container:
```bash
./scripts/run.sh examples/circle.hdass