Skip to content

Latest commit

 

History

History
102 lines (76 loc) · 4.32 KB

BUILDING.md

File metadata and controls

102 lines (76 loc) · 4.32 KB
Raw

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:

  • CAPSTONE_BUILD_SHARED_LIBS: Build shared libraries.
  • CAPSTONE_BUILD_STATIC_LIBS: Build static libraries (ON by default).
  • CAPSTONE_BUILD_STATIC_MSVC_RUNTIME: (Windows only) - Build with static MSVC runtime. Always set if CAPSTONE_BUILD_SHARED_LIBS=ON.
  • 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.

Building cstest

cstest is build together with Capstone by adding the flag -DCAPSTONE_BUILD_CSTEST.

The build requires libyaml. It is a fairly common package and should be provided by your package manager.

Note: Currently cstest us only supported on Linux.

If you run another operation system, please install cstest_py. See bindings/python/BUILDING.md for instructions.