Compile & install Capstone

There are several methods to compile and install Capstone.

1. From source code

Find the source in Download section and follow the instructions in the README file.

The issue with this approach is that at the moment, Windows targets are only possible via Cygwin/MingW cross-compilation. We are working to support Microsoft Visual Studio in the next versions.


2. From repositories

This section explains how to install Capstone on *nix platforms from some software repositories.

2.1 Debian/Ubuntu Linux - core engine

NOTE: At the moment only version 2.1.2 is available in Ubuntu/Debian repositories. Version 3.0.4 will be provided later.

Capstone is available in Ubuntu & Debian Linux (testing/sid flavours). Binary package of the core of Capstone can be installed with:

$ sudo apt-get install libcapstone3

To write your own tools with Capstone, install the development package with:

$ sudo apt-get install libcapstone-dev

2.2 Mac OSX - core engine

$ sudo port install capstone

Note that Macport installs libraries into its own directory, so you need to tell applications where to find them, for example with:

$ export DYLD_LIBRARY_PATH=/opt/local/lib/:$DYLD_LIBRARY_PATH
$ brew install capstone

Note that Homebrew installs libraries into its own directory, so you need to tell applications where to find them, for example with:

$ export DYLD_LIBRARY_PATH=/usr/local/opt/capstone/lib/:$DYLD_LIBRARY_PATH

2.3 FreeBSD - core engine

NOTE: At the moment only version 2.1.2 is available in FreeBSD. Version 3.0.4 will be provided later.

Binary package of the core of Capstone can be installed with:

# pkg install capstone

Or you can also compile & install from source with:

# cd /usr/ports/devel/capstone; make install

2.4 OpenBSD - core engine

NOTE: At the moment version 3.0 is available in OpenBSD. Version 3.0.4 is only provided in OpenBSD-current branch.

Capstone is available in OpenBSD from version 5.5. Binary package of the core of Capstone can be installed with:

$ sudo pkg_add capstone

Or you can also compile & install from source with:

$ cd /usr/ports/devel/capstone; sudo make install

2.5 NetBSD - core engine

Binary package of the core of Capstone can be installed with:

$ sudo pkg_add capstone

2.6 Python binding

There are several ways to install Python binding.

2.6.1 Install from source code

The Python binding depends on the core, so make sure to install the core before you can use this binding.

On *nix platforms, do:

$ cd bindings/python
$ sudo make install

On Windows, do:

cd bindings/python
python setup.py install
2.6.2 Install from PyPi package

Our PyPi package include the source code of the core inside, and it will automatically build and install the core library into the same directory with Python module, so if you install from PyPi, there is no need to install the core beforehand.

On *nix platforms (confirmed on Mac OSX, iOS, Android, Linux, *BSD & Solaris), Python binding can be installed using pip, as follows.

$ sudo pip install capstone

On Windows, you need to install CMake and Microsoft Visual Studio in order to compile the core. Run the following command from Visual Studio developer commandline prompt

$ pip install capstone

Alternatively, download PyPi package, unzip it, then run the following command from Visual Studio developer commandline prompt.

python setup.py install
2.6.3 Install from PyPi package - for Windows only

Method above (2.6.2) requires CMake and Visual Studio to compile the core on Windows. In case you cannot or do not want to compile code, use another PyPi capstone-windows package which already has the core prebuilt inside.

On Windows, run the following command from Commandline prompt

$ pip install capstone-windows

Alternatively, download PyPi package, unzip it, then run the following command from Commandline prompt.

python setup.py install

3. Precompiled binaries

At the moment precompiled binaries for Windows, Ubuntu, FedoraCore, Python binding & Java are available in our Download section.

If you only want to write your tool in Python, all you need is the Python installer, which includes full Capstone module. The Windows core engine is not necessary because it is already embedded inside the Python module.

For any other bindings, firstly you still need to install the Windows core engine, which includes the static/dynamic libraries and also the headers (*.h) for C programming.

Java binding is availabe in JAR package in Download.


Programming

After installation, find in tutorials below how to write your reverse & analysis tools based on Capstone using your favorite programming languages.


Miscellaneous

This section introduces several ways to customize Capstone engine at compile time & clarify the features of our framework.

This Blackhat USA 2014 slides (PDF) describes technical details of Capstone.

This documentation explains how to build a more compact engine with only selected architectures. A smaller library is useful when we want to embed Capstone in special environments such as firmware or OS kernel driver.

To make an even smaller engine, version 2.1 presents a diet mode, in which non-critical data is removed. Combined with the method of building only selected architectures above, Capstone binary size can be reduced up to 50% in some cases, make it easier than ever for embedding purpose.

Embedding Capstone requires a special engine, built by special methods. This documentation introduces necessary steps to compile the engine & program your code towards this target.

This introduces the compile-time option named X86-reduce to make X86 engine of Capstone to be ~60% smaller, to just around 100KB.

This introduces the SKIPDATA mode to let Capstone keeps disassembling even when it encounters broken instruction, which is most likely data mixed inside the input.

This explains how to use the API csdisasmiter to quickly iterates all the instructions in the input buffer using a memory cache provided by user.

A part of Capstone is built with LLVM code. However, Capstone is not just LLVM, but superior because it is designed & implemented towards disassembling for security purpose.