blob: 184f0eff3148f55806251281fc983ad077d36085 [file] [log] [blame]
Nguyen Anh Quynh61882e52014-05-18 00:39:49 +08001This documentation explains how to compile, install & run Capstone on MacOSX,
2Linux, *BSD & Solaris. We also show steps to cross-compile for Microsoft Windows.
3
4To natively compile for Windows using Microsoft Visual Studio, see COMPILE_MSVC.TXT.
5
Nguyen Anh Quynhf1c3acb2014-05-28 22:39:23 +08006To compile using CMake, see COMPILE_CMAKE.TXT.
7
Nguyen Anh Quynhcc351002014-10-06 22:19:10 +08008To compile using XCode on MacOSX, see xcode/README.md.
9
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080010 *-*-*-*-*-*
11
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080012Capstone requires no prerequisite packages, so it is easy to compile & install.
13
14
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080015
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080016(0) Tailor Capstone to your need.
17
Nguyen Anh Quynhf1c3acb2014-05-28 22:39:23 +080018 Out of 8 archtitectures supported by Capstone (Arm, Arm64, Mips, PPC, Sparc,
19 SystemZ, XCore & X86), if you just need several selected archs, choose which
20 ones you want to compile in by editing "config.mk" before going to next steps.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080021
Nguyen Anh Quynhf1c3acb2014-05-28 22:39:23 +080022 By default, all 8 architectures are compiled.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080023
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080024 The other way of customize Capstone without having to edit config.mk is to
25 pass the desired options on the commandline to ./make.sh. Currently,
baguette86e84502014-08-17 20:59:05 +020026 Capstone supports 5 options, as followings.
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080027
28 - CAPSTONE_ARCHS: specify list of architectures to compiled in.
Nguyen Anh Quynhe31327d2014-04-29 14:25:15 +080029 - CAPSTONE_USE_SYS_DYN_MEM: change this if you have your own dynamic memory management.
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080030 - CAPSTONE_DIET: use this to make the output binaries more compact.
31 - CAPSTONE_X86_REDUCE: another option to make X86 binary smaller.
Nguyen Anh Quynh66382942014-08-20 14:02:14 +080032 - CAPSTONE_X86_ATT_DISABLE: disables AT&T syntax on x86.
Nguyen Anh Quynhf85f9812014-11-13 14:58:45 +080033 - CAPSTONE_STATIC: build static library.
34 - CAPSTONE_SHARED: build dynamic (shared) library.
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080035
Nguyen Anh Quynhf85f9812014-11-13 14:58:45 +080036 By default, Capstone uses system dynamic memory management, both DIET and X86_REDUCE
37 modes are disable, and builds all the static & shared libraries.
Nguyen Anh Quynh01f48392014-05-15 11:06:43 +080038
Nguyen Anh Quynhf85f9812014-11-13 14:58:45 +080039 To avoid editing config.mk for these customization, we can pass their values to
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080040 make.sh, as followings.
41
Nguyen Anh Quynhe31327d2014-04-29 14:25:15 +080042 $ CAPSTONE_ARCHS="arm aarch64 x86" CAPSTONE_USE_SYS_DYN_MEM=no CAPSTONE_DIET=yes CAPSTONE_X86_REDUCE=yes ./make.sh
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080043
44 NOTE: on commandline, put these values in front of ./make.sh, not after it.
45
Nguyen Anh Quynh18759b32014-04-29 14:00:16 +080046 For each option, refer to docs/README for more details.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080047
48
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +080049
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080050(1) Compile from source
51
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080052 On *nix (such as MacOSX, Linux, *BSD, Solaris):
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080053
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +080054 - To compile for current platform, run:
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080055
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080056 $ ./make.sh
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080057
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080058 - On 64-bit OS, run the command below to cross-compile Capstone for 32-bit binary:
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080059
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080060 $ ./make.sh nix32
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080061
62
63
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080064(2) Install Capstone on *nix
65
66 To install Capstone, run:
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080067
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080068 $ sudo ./make.sh install
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080069
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080070 For FreeBSD/OpenBSD, where sudo is unavailable, run:
Nguyen Anh Quynhf74bebf2013-12-09 13:53:11 +080071
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +080072 $ su; ./make.sh install
Nguyen Anh Quynhf74bebf2013-12-09 13:53:11 +080073
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080074 Users are then required to enter root password to copy Capstone into machine
75 system directories.
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080076
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +080077 Afterwards, run ./tests/test* to see the tests disassembling sample code.
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080078
79
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +080080 NOTE: The core framework installed by "./make.sh install" consist of
81 following files:
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080082
Patroklos Argyroudisa6503fe2013-11-27 14:25:34 +020083 /usr/include/capstone/capstone.h
84 /usr/include/capstone/x86.h
85 /usr/include/capstone/arm.h
86 /usr/include/capstone/arm64.h
87 /usr/include/capstone/mips.h
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +080088 /usr/include/capstone/ppc.h
Nguyen Anh Quynh05e27132014-03-10 11:58:57 +080089 /usr/include/capstone/sparc.h
Nguyen Anh Quynh48a14ca2014-03-23 08:35:45 +080090 /usr/include/capstone/systemz.h
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080091 /usr/lib/libcapstone.so (for Linux/*nix), or /usr/lib/libcapstone.dylib (OSX)
Nguyen Anh Quynh04271222013-12-09 11:12:47 +080092 /usr/lib/libcapstone.a
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +080093
94
95
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +080096(3) Cross-compile for Windows from *nix
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +080097
98 To cross-compile for Windows, Linux & gcc-mingw-w64-i686 (and also gcc-mingw-w64-x86-64
99 for 64-bit binaries) are required.
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800100
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +0800101 - To cross-compile Windows 32-bit binary, simply run:
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800102
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800103 $ ./make.sh cross-win32
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800104
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +0800105 - To cross-compile Windows 64-bit binary, run:
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800106
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800107 $ ./make.sh cross-win64
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800108
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +0800109 Resulted files libcapstone.dll, libcapstone.dll.a & tests/test*.exe can then
110 be used on Windows machine.
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800111
112
113
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +0800114(4) Cross-compile for iOS from Mac OSX.
Nguyen Anh Quynh2eecc6c2014-04-01 10:22:54 +0800115
116 To cross-compile for iOS (iPhone/iPad/iPod), Mac OSX with XCode installed is required.
117
118 - To cross-compile for ArmV7 (iPod 4, iPad 1/2/3, iPhone4, iPhone4S), run:
119 $ ./make.sh ios_armv7
120
121 - To cross-compile for ArmV7s (iPad 4, iPhone 5C, iPad mini), run:
122 $ ./make.sh ios_armv7s
123
124 - To cross-compile for Arm64 (iPhone 5S, iPad mini Retina, iPad Air), run:
125 $ ./make.sh ios_arm64
126
127 - To cross-compile for all iDevices (armv7 + armv7s + arm64), run:
128 $ ./make.sh ios
129
130 Resulted files libcapstone.dylib, libcapstone.a & tests/test* can then
131 be used on iOS devices.
132
133
134
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +0800135(5) Cross-compile for Android
136
137 To cross-compile for Android (smartphone/tablet), Android NDK is required.
138
139 $ ./make.sh cross-android
140
141 Resulted files libcapstone.so, libcapstone.a & tests/test* can then
142 be used on Android devices.
143
144
145
146(6) Compile on Windows with Cygwin
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800147
148 To compile under Cygwin gcc-mingw-w64-i686 or x86_64-w64-mingw32 run:
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000149
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800150 - To compile Windows 32-bit binary under Cygwin, run:
151
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800152 $ ./make.sh cygwin-mingw32
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000153
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800154 - To compile Windows 64-bit binary under Cygwin, run:
155
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800156 $ ./make.sh cygwin-mingw64
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000157
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +0800158 Resulted files libcapstone.dll, libcapstone.dll.a & tests/test*.exe can then
159 be used on Windows machine.
Daniel Godas-Lopezcf05e112013-11-28 18:23:39 +0000160
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +0800161
Nguyen Anh Quynhf08ed972014-04-07 22:13:56 +0800162
163(7) By default, "cc" (default C compiler on the system) is used as compiler.
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800164
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800165 - To use "clang" compiler instead, run the command below:
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800166
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800167 $ ./make.sh clang
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800168
Nguyen Anh Quynhfe5e7f32014-01-17 14:56:03 +0800169 - To use "gcc" compiler instead, run:
Oliver Pinter6e2c0752014-01-16 12:16:21 +0100170
Nguyen Anh Quynhdba00f82014-01-17 14:20:54 +0800171 $ ./make.sh gcc
Oliver Pinter6e2c0752014-01-16 12:16:21 +0100172
Nguyen Anh Quynh26ee41a2013-11-27 12:11:31 +0800173
174
Nguyen Anh Quynhde6dd292014-04-14 14:40:25 +0800175(8) To uninstall Capstone, run the command below:
Nguyen Anh Quynh919875b2014-04-14 14:00:12 +0800176
177 $ sudo ./make.sh uninstall
178
179
180
181(9) Language bindings
Nguyen Anh Quynha6a11532013-12-24 17:03:45 +0800182
Nguyen Anh Quynh9919e3b2014-01-22 10:17:17 +0800183 So far, Python, Ocaml & Java are supported by bindings in the main code.
184 Look for the bindings under directory bindings/, and refer to README file
185 of corresponding languages.
186
Nguyen Anh Quynh736762d2014-11-14 15:22:05 +0800187 Community also provide bindings for C#, Go, Ruby, NodeJS, C++ & Vala. Links to
188 these can be found at address http://capstone-engine.org/download.html