Hey everyone, low-level programmers and fellow weirdos.
About two months ago, I was tinkering with a real-mode operating system that also had 64-bit support. Assembly was a daily grind: crypto protocols, syscalls, manual memory management. And I got tired of it. Tired of endlessly typing nasm ..., ld ..., babysitting flags, and cleaning up object file garbage.
So I decided to write my own builder. First in Node.js (just for fast prototyping), and now I'm in the middle of a full rewrite in Go. And no, it's not just because Go is trendy – it's because when you write a system tool, it should be fast, native, and not drag around a 100 MB runtime.
What it actually does
You write:
node index.js main.asm
And you get an executable. That's it. The builder does everything:
- Finds all .asm (or .s, .fasm) files recursively.
- Calls the right assembler with the right flags.
- Picks the right linker for your OS (ld for Linux, gcc for Windows, ld for macOS).
- Links with libraries if needed.
- Optionally cleans up object files.
Why it's unique
1. Three assemblers in one bottle
Most builders are locked to one assembler — make with NASM rules, that's it. But here:
NASM (x86 standard):
node index.js program.asm
GAS (GNU Assembler, AT&T syntax):
node index.js --assembler gas program.s
FASM (flat assembler, custom syntax):
node index.js --assembler fasm program.fasm
No switching tools — one builder rules them all. Each assembler has its own flag quirks (NASM needs -f elf64, GAS just as, FASM wants format ELF64 in the source), but I made you forget about that. The --format flag works for NASM; for FASM it's… well, almost works, but you get it.
2. Cross‑platform linking, no headache
You know that on Linux the linker is ld, on Windows it's gcc (via MinGW), and on macOS it's also ld but with different flags? I do. The builder detects your platform and:
- On Linux: adds -dynamic-linker /lib64/ld-linux-x86-64.so.2
- On Windows: calls gcc (because ld can't handle PE formats properly)
- On macOS: uses ld with native defaults
And you just run ./program — no #ifdef in your head.
- Debugging is not a luxury
Ever tried debugging assembly without symbols? I have. It's pain. So there's a --debug flag:
bash
node index.js --debug factorial.asm
gdb ./factorial
(gdb) break main
(gdb) run
It adds -g to the assembler (where supported) and to the linker. For FASM I had to hack it (-d DEBUG=1), but it works. Now you can set breakpoints and watch registers like a civilised person.
What else makes it cool (and why I'm honestly proud)
The code is split into args.js, assembler.js, linker.js, builder.js, logger.js. That's not just fancy talk — you can grab only the linker or only the argument parser for your own project. Or add your own assembler (YASM? FASM? LLVM? — let me know, I'll add it).
Protection from dumb mistakes
Once I accidentally overwrote my source code with the compiled binary because the builder named the output the same as the input. Since then, there's a check: if output == input, it either changes the name or throws an error. No more rm -rf of destiny.
The catch (honest truth)
The builder isn't perfect. Here's what it can't do yet:
- Parallel compilation – builds one file at a time. On a hundred files, it's slow.
- Windows without MinGW – if you have a bare Windows with no gcc, linking fails.
- FASM is still finicky – with --debug it sometimes complains about "illegal instruction" (but I'm fixing it).
- No config file – all flags come from the command line. That's also a plus for simplicity, though.
But for 99% of tasks — building one or two assembly files with or without libc — it works like a charm.
Why I wrote it
I got tired of fragmentation. Assembly is already low‑level — why should the tools around it be complicated? I wanted a "just run it" experience, like gcc main.c. Now I have it. And so do you.
Try it. If you find a bug, please tell me. I'll fix it.
What's next (Go version)
Right now I'm actively developing the new version in Go (separate branch). The core engine is rewritten, argument parsing and assembler invocations work. FASM + --debug is also being fixed (no more "illegal instruction" — I finally understood that FASM doesn't like -d without a value).
Once the Go version catches up with Node.js feature‑wise (in the next few weeks), I'll release 2.0. The Node.js version will stay as an archived prototype, but the main builder will be Go.