Guide To Assembly Language Programming In Linux

Writing assembly on Linux isn't that different from writing it anywhere else, but the toolchain choices matter more than you'd expect.

I've been doing this since the late 90s, and I still bump into the same gotchas. The process is straightforward once you stop treating it like rocket science and start treating it like C with extra steps. You need three things installed: GNU assembler (as), the linker (ld), and GCC for when you need to mix C with assembly. On most distributions these come together in a package called binutils and build-essential or gcc-devel depending on your distro. Here's the thing nobody tells beginners: you don't actually need a makefile. For small projects a shell one-liner is faster and less frustrating. My usual workflow for a quick test is something like assembling with as -g -o hello.o hello.s then linking with ld hello.o -o hello and running it. No IDE drama, no build system configuration, just the tools doing exactly what they're supposed to do.

The AT&T syntax that GNU as uses by default is ugly. I switched to Intel syntax years ago and never looked back. Add -Mintel to your as command and your code reads like anything else you've seen in a textbook. It's a preference thing, but fighting the default syntax when you're already struggling with register names and calling conventions is just unnecessary pain.

Getting your first program to run

On x86_64 Linux the syscall interface is completely different from what you'll find in tutorials written for 32-bit or older systems. The old int 0x80 interrupt still works but it goes through a compatibility layer that adds latency and truncates arguments. Use the syscall instruction instead. Here's a minimal write program that prints to stdout and exits cleanly: section .text global _start _start: mov rax, 1 ; sys_write mov rdi, 1 ; stdout mov rsi, msg mov rdx, msglen syscall mov rax, 60 ; sys_exit xor rdi, rdi syscall section .data msg db "hello", 10 msglen equ $ - msg

Assemble and link it with as --64 -Mintel -o hello.o hello.s && ld hello.o -o hello. Run it. You should see hello on your terminal. The first time I wrote this I used mov rax, 1 for sys_write like everyone's tutorial shows, but I'd forgotten that on x86_64 the syscall numbers are in a different header. They're in /usr/include/asm/unistd_64.h on most systems. Looking at that file saved me about four hours of debugging the first time I hit it.

Linking against the C library

When you want to call printf or other libc functions you can't use ld directly. You need GCC to handle the startup files and dynamic linking. Use gcc hello.o -o hello instead of ld. That one change means your program picks up libc, libgcc, and the crt objects automatically. But there's a catch with position-independent code. If you compile with -fPIC and try to use absolute addresses in your assembly, the linker will fail or your program will segfault at runtime. Linux loads libraries at randomized addresses. If you need static addresses in your assembly, link without -fPIC or use lea to resolve addresses at runtime through the GOT. This tripped me up badly on a project where I was embedding assembly routines into a larger C++ program that had -fPIC set globally. The workaround was wrapping my assembly in a separate compilation unit without the flag, then linking everything together.

Debugging assembly on Linux

GDB works fine but the disassembly output is AT&T syntax by default even if you wrote Intel syntax. Type set disassembly-flavor intel in GDB or run it with that variable set beforehand. Without that your trace output will look like gibberish no matter how clean your source was. I also keep a habit of using objdump -d on my object files during development. It shows you exactly what the assembler produced, which is useful when you're not sure whether your instructions got assembled the way you intended. Sometimes the assembler accepts something you think is invalid and emits something unexpected rather than erroring out. For runtime debugging strace is invaluable. Run your program with strace -e trace=write,exit_group ./hello and you'll see exactly which syscalls fire and what arguments they receive. This alone has saved me more times than I can count when a program appeared to hang or produce wrong output.

Common pitfalls that waste time

Stack alignment is the biggest one. The System V AMD64 ABI requires the stack to be 16-byte aligned before a call instruction. If you're writing pure assembly and calling into C code, your rsp needs to be aligned. Push and pop operations throw off the alignment by 8 bytes each. I always make it a rule to align the stack explicitly at function entry with sub rsp, 8 or similar, and restore it before returning. Skipping this causes crashes that are nearly impossible to trace without understanding the ABI contract. Another one: register clobbering between C and assembly. When you call into C from assembly, the compiler assumes certain registers are preserved and others are scratch. rax, rcx, rdx, r8, r9, r10, and r11 are caller-saved. r12 through r15 and rbp are callee-saved. If your assembly function modifies rax without restoring it and the caller expects it to be unchanged, you get silent data corruption. I learned this the hard way when a sorting routine I wrote would occasionally return wrong results depending on what the compiler had cached in rax before the call.

Performance considerations

Assembly on Linux doesn't automatically mean faster code. The compiler today produces code that's often as good as or better than what a human writes for most tasks. The real value is in situations where the compiler can't see through a bottleneck, or where you need deterministic behavior that optimization passes might restructure unpredictably. If you're writing hot loops, profile first. Use perf record and perf report to find where the actual time goes. I've spent hours optimizing assembly routines that perf showed were taking less than 0.1% of total execution time. The optimization was wasted effort. The time was elsewhere, usually in memory allocation patterns or cache misses that assembly alone can't fix. For genuinely performance-critical code paths, AVX and SIMD instructions available on modern x86_64 processors give you significant gains. But again, benchmark with -O3 compiled C code first. Often the compiler's auto-vectorization already does what you'd hand-write, and sometimes does it better by matching the exact microarchitecture you're running on.

Where to go from here

The Linux kernel source tree under arch/x86/ has assembly files you can study. They're production-quality code written by people who know exactly what they're doing. Reading their conventions for calling the kernel API and handling edge cases is probably the best education available. For userland programs, look at musl-libc's assembly implementations. They're cleaner than glibc's and easier to follow because they're smaller and more focused. The musl repo is on GitHub and the assembly directory structure is logical. Writing assembly on Linux is a skill that compounds. The initial friction of learning the syscall interface and ABI rules is real and takes a few weeks of actual practice to internalize. After that, reading other people's assembly and writing your own becomes noticeably easier. The payoff is being able to understand what the compiler actually generates, which changes how you write C and C++ code too.