103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# Building Capstone
|
|
|
|
This guide describes how to build Capstone with `CMake`.
|
|
|
|
## Build commands
|
|
|
|
**Unix**
|
|
|
|
```bash
|
|
cmake -B build -DCMAKE_BUILD_TYPE=Release # For debug build change "Release" to "Debug"
|
|
cmake --build build
|
|
cmake --install build --prefix "<install-prefix>"
|
|
```
|
|
|
|
**Windows**
|
|
|
|
```bash
|
|
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.
|