capstone/BUILDING.md

Building Capstone

This guide describes how to build Capstone with CMake.

Build commands

Unix

cmake -B build -DCMAKE_BUILD_TYPE=Release # For debug build change "Release" to "Debug"
cmake --build build
cmake --install build --prefix "<install-prefix>"

Windows

cmake.exe -B build
cmake.exe --build build --config Release # For debug build change "Release" to "Debug"
cmake.exe --install build

Tailor Capstone to your needs.

Enable and disable options in the "configure" step (first cmake command from above). Options are added with -D<OPTION>=ON/OFF or -D<OPTION>=1/0

Exclude architecture modules

You can build Capstone with only the architectures you need. By default all are enabled.

• CAPSTONE_ARCHITECTURE_DEFAULT: Whether all architectures are enabled by default.
• CAPSTONE_ARM_SUPPORT: Support ARM.
• CAPSTONE_AARCH64_SUPPORT: Support AARCH64.
• CAPSTONE_ALPHA_SUPPORT: Support Alpha.
• CAPSTONE_HPPA_SUPPORT: Support HPPA.
• CAPSTONE_LOONGARCH_SUPPORT: Support LoongArch.
• CAPSTONE_M680X_SUPPORT: Support M680X.
• CAPSTONE_M68K_SUPPORT: Support M68K.
• CAPSTONE_MIPS_SUPPORT: Support Mips.
• CAPSTONE_MOS65XX_SUPPORT: Support MOS65XX.
• CAPSTONE_PPC_SUPPORT: Support PPC.
• CAPSTONE_SPARC_SUPPORT: Support Sparc.
• CAPSTONE_SYSTEMZ_SUPPORT: Support SystemZ.
• CAPSTONE_XCORE_SUPPORT: Support XCore.
• CAPSTONE_TRICORE_SUPPORT: Support TriCore.
• CAPSTONE_X86_SUPPORT: Support X86.
• CAPSTONE_TMS320C64X_SUPPORT: Support TMS320C64X.
• CAPSTONE_M680X_SUPPORT: Support M680X.
• CAPSTONE_EVM_SUPPORT: Support EVM.
• CAPSTONE_WASM_SUPPORT: Support Web Assembly.
• CAPSTONE_BPF_SUPPORT: Support BPF.
• CAPSTONE_RISCV_SUPPORT: Support RISCV.

Module registration

If you're building a static library that you intend to link into multiple consumers, and they have differing architecture requirements, you may want -DCAPSTONE_USE_ARCH_REGISTRATION=1.

In your consumer code you can call cs_arch_register_*() to register the specific module for initialization.

In this way you only pay footprint size for the architectures you're actually using in each consumer, without having to compile Capstone multiple times.

Additional options

Capstone allows some more customization via the following options:

• BUILD_SHARED_LIBS: Build shared libraries.
• CAPSTONE_BUILD_CSTOOL: Enable/disable build of cstool. Default is enabled if build runs from the repository root.
• CAPSTONE_USE_SYS_DYN_MEM: change this to OFF to use your own dynamic memory management.
• CAPSTONE_BUILD_MACOS_THIN: MacOS only. Disables universal2 build. So you only get the binary for you processor architecture.
• CAPSTONE_BUILD_DIET: change this to ON to make the binaries more compact.
• CAPSTONE_X86_REDUCE: change this to ON to make X86 binary smaller.
• CAPSTONE_X86_ATT_DISABLE: change this to ON to disable AT&T syntax on x86.

By default, Capstone use system dynamic memory management, and both DIET and X86_REDUCE modes are disabled. To use your own memory allocations, turn ON both DIET & X86_REDUCE, run "cmake" with: -DCAPSTONE_USE_SYS_DYN_MEM=0, -DCAPSTONE_BUILD_DIET=1, -DCAPSTONE_X86_REDUCE=1

Developer specific options

• CAPSTONE_DEBUG: Change this to ON to enable extra debug assertions. Automatically enabled with Debug build.
• CAPSTONE_BUILD_CSTEST: Build cstest in suite/cstest/. Note: cstest requires libyaml on your system. It attempts to build it from source otherwise.
• CMAKE_EXPORT_COMPILE_COMMANDS: To export compile_commands.json for clangd and other language servers.
• ENABLE_ASAN: Compiles Capstone with the address sanitizer.
• ENABLE_COVERAGE: Generate coverage files.
• CAPSTONE_BUILD_LEGACY_TESTS: Build some legacy integration tests.