blob: 2bdca196aa8fa84a18fb7f908844cbb77f2efec4 [file] [log] [blame]
Nguyen Anh Quynhb8f2af62013-12-25 10:49:59 +08001How To Compile, install & run Capstone for Linux, Mac OSX, *BSD and Windows
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +08002 *-*-*-*-*-*
3
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +08004Capstone requires no prerequisite packages, so it is easy to compile & install.
5
6
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +08007
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +08008(0) Tailor Capstone to your need.
9
Nguyen Anh Quynh48a14ca2014-03-23 08:35:45 +080010 Out of 7 archtitectures supported by Capstone (Arm, Arm64, Mips, PPC, Sparc,
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080011 SystemZ & X86), if you just need several selected archs, choose which ones you
12 want to compile in by editing "config.mk" before going to next steps.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080013
Nguyen Anh Quynh48a14ca2014-03-23 08:35:45 +080014 By default, all 7 architectures are compiled.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080015
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080016 The other way of customize Capstone without having to edit config.mk is to
17 pass the desired options on the commandline to ./make.sh. Currently,
18 Capstone supports 4 options, as followings.
19
20 - CAPSTONE_ARCHS: specify list of architectures to compiled in.
21 - USE_SYS_DYN_MEM: change this if you have your own dynamic memory management.
22 - CAPSTONE_DIET: use this to make the output binaries more compact.
23 - CAPSTONE_X86_REDUCE: another option to make X86 binary smaller.
24
25 To avoid editing config.mk for these customization, can pass their values to
26 make.sh, as followings.
27
28 $ CAPSTONE_ARCH="arm aarch64 x86" CAPSTONE_DIET=yes CAPSTONE_X86_REDUCE=yes ./make.sh
29
30 NOTE: on commandline, put these values in front of ./make.sh, not after it.
31
32 See default values of above options in config.mk
33 For each option, refer to docs/README for more details.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080034
35
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +080036
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080037(1) Compile from source
38
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080039 On *nix (such as MacOSX, Linux, *BSD, Solaris):
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080040
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +080041 - To compile for current platform, run:
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080042
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080043 $ ./make.sh
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080044
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080045 - On 64-bit OS, run the command below to cross-compile Capstone for 32-bit binary:
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080046
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080047 $ ./make.sh nix32
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080048
49
50
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080051(2) Install Capstone on *nix
52
53 To install Capstone, run:
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080054
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080055 $ sudo ./make.sh install
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080056
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080057 For FreeBSD/OpenBSD, where sudo is unavailable, run:
Nguyen Anh Quynhf74bebf2013-12-09 13:53:11 +080058
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080059 $ su; ./make.sh install
Nguyen Anh Quynhf74bebf2013-12-09 13:53:11 +080060
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080061 Users are then required to enter root password to copy Capstone into machine
62 system directories.
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080063
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +080064 Afterwards, run ./tests/test* to see the tests disassembling sample code.
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080065
66
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +080067 NOTE: The core framework installed by "./make.sh install" consist of
68 following files:
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080069
Patroklos Argyroudisa6503fe2013-11-27 14:25:34 +020070 /usr/include/capstone/capstone.h
71 /usr/include/capstone/x86.h
72 /usr/include/capstone/arm.h
73 /usr/include/capstone/arm64.h
74 /usr/include/capstone/mips.h
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080075 /usr/include/capstone/ppc.h
Nguyen Anh Quynh05e27132014-03-10 11:58:57 +080076 /usr/include/capstone/sparc.h
Nguyen Anh Quynh48a14ca2014-03-23 08:35:45 +080077 /usr/include/capstone/systemz.h
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080078 /usr/lib/libcapstone.so (for Linux/*nix), or /usr/lib/libcapstone.dylib (OSX)
Nguyen Anh Quynh04271222013-12-09 11:12:47 +080079 /usr/lib/libcapstone.a
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080080
81
82
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +080083(3) Cross-compile for Windows from *nix
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080084
85 To cross-compile for Windows, Linux & gcc-mingw-w64-i686 (and also gcc-mingw-w64-x86-64
86 for 64-bit binaries) are required.
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080087
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +080088 - To cross-compile Windows 32-bit binary, simply run:
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080089
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080090 $ ./make.sh cross-win32
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080091
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +080092 - To cross-compile Windows 64-bit binary, run:
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080093
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080094 $ ./make.sh cross-win64
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080095
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +080096 Resulted files libcapstone.dll, libcapstone.dll.a & tests/test*.exe can then
97 be used on Windows machine.
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080098
99
100
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +0800101(4) Cross-compile for iOS from Mac OSX.
Nguyen Anh Quynh2eecc6c2014-04-01 10:22:54 +0800102
103 To cross-compile for iOS (iPhone/iPad/iPod), Mac OSX with XCode installed is required.
104
105 - To cross-compile for ArmV7 (iPod 4, iPad 1/2/3, iPhone4, iPhone4S), run:
106 $ ./make.sh ios_armv7
107
108 - To cross-compile for ArmV7s (iPad 4, iPhone 5C, iPad mini), run:
109 $ ./make.sh ios_armv7s
110
111 - To cross-compile for Arm64 (iPhone 5S, iPad mini Retina, iPad Air), run:
112 $ ./make.sh ios_arm64
113
114 - To cross-compile for all iDevices (armv7 + armv7s + arm64), run:
115 $ ./make.sh ios
116
117 Resulted files libcapstone.dylib, libcapstone.a & tests/test* can then
118 be used on iOS devices.
119
120
121
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +0800122(5) Cross-compile for Android
123
124 To cross-compile for Android (smartphone/tablet), Android NDK is required.
125
126 $ ./make.sh cross-android
127
128 Resulted files libcapstone.so, libcapstone.a & tests/test* can then
129 be used on Android devices.
130
131
132
133(6) Compile on Windows with Cygwin
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800134
135 To compile under Cygwin gcc-mingw-w64-i686 or x86_64-w64-mingw32 run:
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000136
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800137 - To compile Windows 32-bit binary under Cygwin, run:
138
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800139 $ ./make.sh cygwin-mingw32
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000140
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800141 - To compile Windows 64-bit binary under Cygwin, run:
142
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800143 $ ./make.sh cygwin-mingw64
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000144
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +0800145 Resulted files libcapstone.dll, libcapstone.dll.a & tests/test*.exe can then
146 be used on Windows machine.
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000147
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +0800148
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +0800149
150(7) By default, "cc" (default C compiler on the system) is used as compiler.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800151
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800152 - To use "clang" compiler instead, run the command below:
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800153
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800154 $ ./make.sh clang
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800155
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +0800156 - To use "gcc" compiler instead, run:
Oliver Pinter6e2c0752014-01-16 12:16:21 +0100157
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800158 $ ./make.sh gcc
Oliver Pinter6e2c0752014-01-16 12:16:21 +0100159
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800160
161
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800162(8) To uninstall Capstone, run the command below:
Nguyen Anh Quynh919875b2014-04-14 14:00:12 +0800163
164 $ sudo ./make.sh uninstall
165
166
167
168(9) Language bindings
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800169
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +0800170 So far, Python, Ocaml & Java are supported by bindings in the main code.
171 Look for the bindings under directory bindings/, and refer to README file
172 of corresponding languages.
173
174 Community also provide bindings for C#, Go, Ruby & Vala. Links to these can
175 be found at address http://capstone-engine.org/download.html