Xbyak: generating x86 instructions from C++ at run time

Emitting machine code from C++ without leaving the language

Xbyak is a header-only C++ library for dynamic assembly of x86 and x64 instructions, written with mnemonics rather than byte arrays. The name comes from a Japanese word for creation, and the pronunciation is roughly kai-byak. Version 7.42 is the current one in the README, published on a repository whose last push was on 2026-09-17, and there are no tagged GitHub releases, so the changelog lives in `doc/changelog.md` instead.

The design goal is stated plainly: Intel and MASM-like syntax, so that a line of assembly in a manual reads the same way in your C++. What that buys you is the ability to build code whose contents depend on runtime information. A JIT compiler, a self-modifying code path, a fuzzer generating instruction sequences, or a switch that has to emit a different encoding per CPU model are all cases where an assembler you call from C++ is the natural fit.

The cost is that you are no longer writing Java or Kotlin, and no longer benefiting from a compiler's understanding of your program. Xbyak gives you precise control and takes away every safety net above the instruction.

Adding it is a copy of headers

There is no package manager story here, which is normal for a header-only C++ library of this age. The repository tree is short and readable: `xbyak/` holds the headers, `sample/` holds about two dozen programs, `test/` holds the tests, `gen/` holds the tooling that regenerates the mnemonic header, and `doc/` holds `install.md`, `usage.md` and `changelog.md`. Build files come in three flavours, with `CMakeLists.txt`, `meson.build` and `Android.bp` alongside a plain `Makefile`.

The `Makefile` at the root does the interesting parts. Building the samples is the default target, testing delegates into `test/`, and installation copies headers into an include directory under a configurable prefix.

make
make test
make install

In practice most projects skip the install step entirely and vendor the headers, or include them by relative path. The prefix defaults to `/usr/local` and the destination is `$(PREFIX)/include/xbyak`.

Supported compilers are described as almost any C++03 or later compiler for x86 and x64, naming Visual Studio, g++, clang++, the Intel C++ compiler, and g++ under mingw or cygwin. Supported systems are Windows from Xp through 11 in both bitnesses, Linux in both bitnesses, and macOS on Intel CPUs.

The operator name trap when calling and_() and or_()

One detail in the README is worth reading twice, because it is the first thing that will bite you. Mnemonics that collide with C++ keywords or alternative tokens are exposed with a trailing underscore, so the logical and and or instructions are called `and_()` and `or_()` rather than `and()` and `or()`. The README notes the alternative: if you would rather have the clean names, compile with the flag that disables operator names.

-fno-operator-names

Either way works, and which one you pick is mostly a question about how much you mind the underscore. Worth knowing before you paste a snippet from somewhere else and get a wall of compiler errors that look nothing like an assembler problem.

The same README lists a few behaviour changes that could bite on upgrade. Address offsets are now checked strictly against a signed 32-bit integer, so something like `ptr[(void*)0xffffffff]` is an error where it previously compiled, and the escape hatch `XBYAK_OLD_DISP_CHECK` exists for old code. `push(byte, imm)` and `push(word, imm)` now force the immediate to 8 or 16 bits, which the project labels a deliberate break of backward compatibility. On Windows, `xbyak.h` no longer includes `winsock2.h` for you.

The sample directory carries the documentation

The README is a project page rather than a manual, and the samples pick up the slack. There are around two dozen of them and their names describe the use cases directly: `bf.cpp`, `toyvm.cpp` and `jmp_table.cpp` for virtual machines and dispatch, `memfunc.cpp`, `memfd.cpp` and `protect-re.cpp` for executable memory, `cpuid/` and `cputopology.cpp` for feature detection, `profiler.cpp` for timing, `stackframe.cpp`, `zero_upper.cpp` and `ccmp.cpp` for the specific instruction hazards you hit when you take over a C++ process's instruction stream.

Two naming conventions deserve explanation. The `.bf` files are brainfuck source: `echo.bf`, `fizzbuzz.bf`, `hello.bf`. They are there because compiling a short program from text into machine code at run time is the clearest possible demonstration of what the library does, and because a small program makes it obvious when your encoding is wrong.

`sample/readme.md` exists alongside them, and `sample/CMakeLists.txt` and `sample/Makefile` show how the examples build. If you are evaluating this library, reading three of these files will teach you more than the README will.

Keeping pace with AVX10.2, APX and ACE

The most useful signal about the project's health is how recently its instruction coverage was extended. The README lists full support for AVX-512, AVX10.2, APX, AMX and ACE, with ACE described as the AI Compute Extensions specification. Recent news items include support for ACE 1.15, AVX10.2 detection, AESKLE, WIDE_KL and KEYLOCKER, RAO-INT for APX, VNNI instructions such as `vpdpbusd` with VEX encoding, and the WAITPKG instructions `tpause`, `umonitor` and `umwait`.

Two of those are practical rather than academic. AVX10 detection matters because you cannot emit an instruction your CPU will trap on. And `MmapAllocator` support for memfd with user-defined strings, demonstrated in `sample/memfd.cpp`, is the kind of detail that shows the author is building on real platforms rather than to a specification.

One memory-related default is worth knowing about on Unix. `XBYAK_USE_MMAP_ALLOCATOR` is defined on Linux and macOS unless `XBYAK_DONT_USE_MMAP_ALLOCATOR` is set, which is how the library gets writable executable memory without asking you to configure anything. There is also an exception-less mode documented in the README.

The x86 boundary and the projects that cross it

Two things are worth being blunt about. First, this library is x86 and x64 only, and on macOS the supported platform list names Intel CPUs rather than Apple Silicon. Second, there is no facade across architectures here.

What exists instead are sibling repositories. `fujitsu/xbyak_aarch64` covers AArch64 and `herumi/xbyak_riscv` covers RISC-V, both following the same interface idea. That arrangement tells you something about how the author thinks: Xbyak is a family of assemblers with one API shape, not a portable layer. If you are writing something that has to run on ARM, you are choosing between those repositories, an assembler backend such as Keystone, or a completely different approach, and the choice is architectural rather than incremental.

Licensing is BSD-3-Clause with the copyright text in a `COPYRIGHT` file, which is permissive enough for commercial and embedded use and keeps the obligation to a notice. The author is listed as Mitsunari Shigeo, and the project is maintained rather than archived, with sponsors accepted through GitHub Sponsors.

Editorial conclusion

Xbyak is the tool to reach for when the machine code cannot be known at compile time, which covers just-in-time compilers, binary patchers, opcode experiments, CPU dispatch tables and small virtual machines. It is header-only, so adopting it costs a copy of the headers rather than a link step, and the instruction coverage in version 7.42 extends to AVX-512, AVX10.2, APX, AMX and ACE. Two limits decide it. It is x86 and x64 only, and on macOS the README lists Intel CPUs, so Apple Silicon users look at the `Xbyak_aarch64` and `Xbyak_riscv` repositories instead. Read `sample/bf.cpp` and `sample/jmp_table.cpp` first, because the samples are more instructive than the short README, and check `doc/usage.md` for the mode that fits your target before writing anything.

Frequently asked questions

Official sources

1. herumi/xbyak on GitHub
2. Issues
3. License: BSD-3-Clause
4. README