In Zig projects, you may need to write assembly code for performance-critical operations or to implement features that Zig doesn’t support natively. Zig offers two main methods for incorporating assembly into your code: you can either embed assembly directly within your Zig source (inline assembly) or maintain it in separate assembly files and link them into your project. Below, i explain both approaches in detail.

Inline Assembly

Inline assembly is Zig’s built-in method for executing assembly instructions within Zig functions. This approach does not require an additional build step and is relatively easy to write.

Below is an example of a simple function that performs subtraction using inline assembly:

    1  const std: type = @import("std");
    2
    3  /// Subtracts b from a using inline assembly
    4  pub fn subtractInline(a: usize, b: usize) usize {
    5      return asm volatile (
    6          \\ mov %[a], %[result]
    7          \\ sub %[b], %[result]
    8          : [result] "=&r" (-> usize),
    9          : [a] "r" (a),
   10            [b] "r" (b),
   11          : "cc"
   12      );
   13  }
   14
   15  pub fn main() void {
   16      const result: usize = subtractInline(a: 10, b: 4);
   17      std.debug.print(fmt: "10 - 4 = {}\n", args: .{result});
   18  }

• Zig’s inline assembly uses the AT&T syntax.

• volatile communicates to the compiler it should not optimize away as the code might have side effects.

• mov %[a], %[result]moves the input a into output register and sub %[b], %[result] would Subtract input ‘b’ from the output register.

• : [result] "=&r" (-> usize)s constraint string that uses early clobber so the register for this output should not be used for any other operand before assembly is executed.

• This approach is suitable when you want zig’s type checking, comptime integration and performance benefits.

• However, for complex scenarios, separate assembly in its own source file is recommended, for example if you need to write a green thread runtime that would need complicated stackful state management for threads and fast context switch. In such scenarios, you would probably want to use separate assembly files and update build code to link the file and then build it with zig modules to create the executable.

Separate Assembly File/Files

For more complex scenarios, using separate assembly files is recommended. This is ideal if you need to write large assembly routines—for instance, when implementing a green-thread runtime that requires complicated stackful state management and fast context switching.

File: src/add.s

    1      .globl add_numbers      # Export the symbol add_numbers.
    2      .section .text
    3  add_numbers:
    4      mov %rdi, %rax          # Move the first argument (in rdi) into rax.
    5      add %rsi, %rax          # Add the second argument (in rsi) to rax.
    6      ret

• In the code above add_numbers is exported as global symbol

• And standard assembly code to move values into register and perform the add operation and return

File: src/main.zig

      1  extern fn add_numbers(a: usize, b: usize) usize;
      2
      3  pub fn main() !void {
      4      const result = add_numbers(40, 2);
      5      std.debug.print("40 + 2 = {}\n", .{result});
      6  }
      7
      8  const std = @import("std");

Build File: build.zig

1  const std: type = @import("std");
      2
      3  // Although this function looks imperative, note that its job is to
      4  // declaratively construct a build graph that will be executed by an external
      5  // runner.
      6  pub fn build(b: *std.Build) void {
      7      const target: ResolvedTarget = b.standardTargetOptions(.{});
      8      const exe: *Compile = b.addExecutable(.{
      9          .name: []const u8 = "adder",
     10          .root_source_file: ?LazyPath = b.path("src/main.zig"),
     11          .target: ?ResolvedTarget = target,
     12      });
     13      // Link the separate assembly file.
     14      exe.addAssemblyFile(b.path("src/add.s"));
     15      b.installArtifact(exe);
     16  }

• Assembly File (add.s):

  • The file defines a function add_numbers in AT&T syntax. It uses the standard x86-64 calling convention (first argument in %rdi, second in %rsi) to perform addition, with the result returned in %rax.

• Zig File (main.zig):

  • An external function declaration (extern fn) is used to call the assembly routine. This allows you to integrate the assembly code into your Zig program.

• Build Script (build.zig):

  • The build script uses b.addExecutable() to create an executable, adds the assembly file with exe.addAssemblyFile(b.path(“src/add.s”)), and then installs the artifact. This approach gives you full control over your assembly routines while allowing you to maintain them separately from your Zig code

• After running zig build a binary will be generated in the zig-out/bin that can be executed to run the program.

• The advantage of using separate files is we can use advanced assembly features as well like macros, complex directives, etc.

• The disadvantages are that you would have to maintain build code and nuances related to assembly based on different cpu architectures and additional debugging complexity as well.

Github Link