Andrew Dutcher | 77888ab | 2016-10-21 03:39:22 -0700 | [diff] [blame] | 1 | 0. This documentation explains how to install the Python bindings for Capstone |
| 2 | from source. If you want to install it from a PyPi package (recommended if |
| 3 | you are on Windows), see README.txt. |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 4 | |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 5 | 1. To install Capstone and the Python bindings on *nix, run the command below: |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 6 | |
| 7 | $ sudo make install |
| 8 | |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 9 | To install Capstone for Python 3, run the command below: |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 10 | (Note: this requires python3 installed in your machine) |
| 11 | |
| 12 | $ sudo make install3 |
| 13 | |
Andrew Dutcher | f4aed60 | 2016-10-19 13:56:50 -0700 | [diff] [blame] | 14 | To control the install destination, set the DESTDIR environment variable. |
| 15 | |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 16 | 2. For better Python performance, install cython-based binding with: |
| 17 | |
| 18 | $ sudo make install_cython |
| 19 | |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 20 | Note that this requires Cython installed first. To install Cython, see |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 21 | below. |
| 22 | |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 23 | 3. To install Cython, you have to ensure that the header files |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 24 | and the static library for Python are installed beforehand. |
| 25 | |
| 26 | E.g. on Ubuntu, do: |
| 27 | |
| 28 | $ sudo apt-get install python-dev |
| 29 | |
| 30 | Depending on if you already have pip or easy_install installed, install |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 31 | Cython with either: |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 32 | |
| 33 | $ sudo pip install cython |
| 34 | or: |
| 35 | $ sudo easy_install cython |
| 36 | |
| 37 | NOTE: Depending on your distribution you might also be able to |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 38 | install the required Cython version using your repository. |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 39 | |
| 40 | E.g. on Ubuntu, do: |
| 41 | |
| 42 | $ sudo apt-get install cython |
| 43 | |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 44 | However, our cython-based binding requires Cython version 0.19 or newer, |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 45 | but sometimes distributions only provide older version. Make sure to |
| 46 | verify the current installed version before going into section 2 above. |
| 47 | |
Nguyen Anh Quynh | b4b97a0 | 2016-10-30 16:19:10 +0800 | [diff] [blame^] | 48 | E.g, on Ubuntu, you can verify the current Cython version with: |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 49 | |
| 50 | $ apt-cache policy cython |
| 51 | |
| 52 | Which should at least print version 0.19 |
| 53 | |
Andrew Dutcher | 77888ab | 2016-10-21 03:39:22 -0700 | [diff] [blame] | 54 | 4. This directory contains some test code to show how to use the Capstone API. |
Andrew Dutcher | 8292844 | 2016-10-19 00:50:38 -0700 | [diff] [blame] | 55 | |
| 56 | - test_basic.py |
| 57 | This code shows the most simple form of API where we only want to get basic |
| 58 | information out of disassembled instruction, such as address, mnemonic and |
| 59 | operand string. |
| 60 | |
| 61 | - test_lite.py |
| 62 | Similarly to test_basic.py, but this code shows how to use disasm_lite(), a lighter |
| 63 | method to disassemble binary. Unlike disasm() API (used by test_basic.py), which returns |
| 64 | CsInsn objects, this API just returns tuples of (address, size, mnemonic, op_str). |
| 65 | |
| 66 | The main reason for using this API is better performance: disasm_lite() is at least |
| 67 | 20% faster than disasm(). Memory usage is also less. So if you just need basic |
| 68 | information out of disassembler, use disasm_lite() instead of disasm(). |
| 69 | |
| 70 | - test_detail.py: |
| 71 | This code shows how to access to architecture-neutral information in disassembled |
| 72 | instructions, such as implicit registers read/written, or groups of instructions |
| 73 | that this instruction belong to. |
| 74 | |
| 75 | - test_<arch>.py |
| 76 | These code show how to access architecture-specific information for each |
| 77 | architecture. |