From fdd01588f18ca2e93e139c4e5e46acdfc3bdaafe Mon Sep 17 00:00:00 2001 From: Nguyen Anh Quynh Date: Sat, 30 Apr 2016 09:49:00 +0800 Subject: [PATCH] docs: move COMPILE.TXT to docs/, and split it into separate files for *nix & Windows --- COMPILE.TXT | 303 ---------------------------------------- README.md | 2 +- docs/COMPILE-NIX.md | 169 ++++++++++++++++++++++ docs/COMPILE-WINDOWS.md | 200 ++++++++++++++++++++++++++ docs/COMPILE.md | 10 ++ 5 files changed, 380 insertions(+), 304 deletions(-) delete mode 100644 COMPILE.TXT create mode 100644 docs/COMPILE-NIX.md create mode 100644 docs/COMPILE-WINDOWS.md create mode 100644 docs/COMPILE.md diff --git a/COMPILE.TXT b/COMPILE.TXT deleted file mode 100644 index 2f4a7104..00000000 --- a/COMPILE.TXT +++ /dev/null @@ -1,303 +0,0 @@ -This documentation explains how to compile, install & run Unicorn on MacOSX, -Linux, *BSD & Solaris. We also show steps to cross-compile for Microsoft Windows. - - *-*-*-*-*-* - -[0] Dependencies - -Unicorn requires few dependent packages as follows. - -- For Mac OS X, "pkg-config" and "glib" are needed. - Brew users can install "pkg-config" and "glib" with: - - $ brew install pkg-config glib - -- For Linux, "glib2-dev" is needed. - Ubuntu/Debian users can install this with: - - $ sudo apt-get install libglib2.0-dev - -- For Windows, cross-compile requires Mingw. Mingw-glib2 is needed. - At the moment, it is confirmed that Unicorn can be compiled either on Ubuntu - or Windows. - - - On Ubuntu 14.04 64-bit, do: - - 1. Download DEB packages for Mingw64 from: - - https://launchpad.net/~greg-hellings/+archive/ubuntu/mingw-libs/+build/2924251 - - 2. To cross-compile for Windows 32-bit, install Mingw with (ignore all the warnings): - - $ sudo dpkg -i --force-depends mingw64-x86-glib2_2.31.0_all.deb - - To cross-compile for Windows 64-bit, install Mingw with: - - $ sudo dpkg -i --force-depends mingw64-x64-glib2_2.31.0_all.deb - - - - On Windows, install MinGW via package MSYS2 at https://msys2.github.io/ - - Follow the install instructions and don't forget to update the system packages with: - - $ pacman --needed -Sy bash pacman pacman-mirrors msys2-runtime - - Then close MSYS2, run it again from Start menu and update the rest with: - - $ pacman -Su - - Finally, install required toolchain to build C projects. - - - To compile for Windows 32-bit, run: - $ pacman -S python2 - $ pacman -S make - $ pacman -S pkg-config - $ pacman -S mingw-w64-i686-glib2 - $ pacman -S mingw-w64-i686-toolchain - - - To compile for Windows 64-bit, run: - $ pacman -S python2 - $ pacman -S make - $ pacman -S pkg-config - $ pacman -S mingw-w64-x86_64-glib2 - $ pacman -S mingw-w64-x86_64-toolchain - -- For Cygwin, "make", "gcc-core", "pkg-config", "libpcre-devel", "zlib-devel" - and "libglib2.0-devel" are needed. - - If apt-cyg is available, you can install these with: - - $ apt-cyg install make gcc-core pkg-config libpcre-devel zlib-devel libglib2.0-devel - - - -[1] Tailor Unicorn to your need. - - Out of 6 archtitectures supported by Unicorn (Arm, Arm64, M68K, Mips, Sparc, - & X86), if you just need several selected archs, choose which ones you want - to compile in by editing "config.mk" before going to next steps. - - By default, all 6 architectures are compiled. - - The other way of customize Unicorn without having to edit config.mk is to - pass the desired options on the commandline to ./make.sh. Currently, - Unicorn supports 4 options, as follows. - - - UNICORN_ARCHS: specify list of architectures to compiled in. - - UNICORN_STATIC: build static library. - - UNICORN_SHARED: build dynamic (shared) library. - - UNICORN_QEMU_FLAGS: specify extra flags for qemu's configure script - - To avoid editing config.mk for these customization, we can pass their values to - make.sh, as follows. - - $ UNICORN_ARCHS="arm aarch64 x86" ./make.sh - - NOTE: on commandline, put these values in front of ./make.sh, not after it. - - For each option, refer to docs/README for more details. - - - -[2] Compile and install from source on *nix - - To build Unicorn on *nix (such as MacOSX, Linux, *BSD, Solaris): - - - To compile for current platform, run: - - $ ./make.sh - - - Unicorn requires Python 2.x to compile. If Python 2.x is not the default - Python interpreter, ensure that the appropriate option is set: - - $ UNICORN_QEMU_FLAGS="--python=/path/to/python2" ./make.sh - - - To cross-compile Unicorn on 64-bit OS to target 32-bit binary, run: - - $ ./make.sh nix32 - - After compiling, install Unicorn with: - - $ sudo ./make.sh install - - For FreeBSD/OpenBSD, where sudo is unavailable, run: - - $ su; ./make.sh install - - Users are then required to enter root password to copy Unicorn into machine - system directories. - - Afterwards, run ./samples/sample_all.sh to test the sample emulations. - - - NOTE: The core framework installed by "./make.sh install" consist of - following files: - - /usr/include/unicorn/unicorn.h - /usr/include/unicorn/x86.h - /usr/include/unicorn/arm.h - /usr/include/unicorn/arm64.h - /usr/include/unicorn/mips.h - /usr/include/unicorn/ppc.h - /usr/include/unicorn/sparc.h - /usr/include/unicorn/m68k.h - /usr/lib/libunicorn.so (for Linux/*nix), or /usr/lib/libunicorn.dylib (OSX) - /usr/lib/libunicorn.a - - - -[3] Compile from source on Windows - with MinGW (MSYS2) - - To compile with MinGW, install MSYS2 as instructed in the first section. - Then, build Unicorn with the next steps: - - - To compile Windows 32-bit binary with MinGW, run: - $ ./make.sh cross-win32 - - - To compile Windows 64-bit binary with MinGW, run: - $ ./make.sh cross-win64 - - Resulted files unicorn.dll, unicorn.lib & samples/sample*.exe can then - be used on Windows machine. - - To run sample_x86.exe on Windows 32-bit, you need the following files: - - unicorn.dll - - %MSYS2%\mingw32\bin\libiconv-2.dll - - %MSYS2%\mingw32\bin\libintl-8.dll - - %MSYS2%\mingw32\bin\libglib-2.0-0.dll - - %MSYS2%\mingw32\bin\libgcc_s_dw2-1.dll - - %MSYS2%\mingw32\bin\libwinpthread-1.dll - - To run sample_x86.exe on Windows 64-bit, you need the following files: - - unicorn.dll - - %MSYS2%\mingw64\bin\libiconv-2.dll - - %MSYS2%\mingw64\bin\libintl-8.dll - - %MSYS2%\mingw64\bin\libglib-2.0-0.dll - - %MSYS2%\mingw64\bin\libgcc_s_seh-1.dll - - %MSYS2%\mingw64\bin\libwinpthread-1.dll - - - -[4] Compile and install from source on Cygwin - - To build Unicorn on Cygwin, run: - - $ ./make.sh - - After compiling, install Unicorn with: - - $ ./make.sh install - - Resulted files cygunicorn.dll, libunicorn.dll.a and libunicorn.a can be - used on Cygwin but not native Windows. - - NOTE: The core framework installed by "./make.sh install" consist of - following files: - - /usr/include/unicorn/*.h - /usr/bin/cygunicorn.dll - /usr/lib/libunicorn.dll.a - /usr/lib/libunicorn.a - - - -[5] Cross-compile for Windows from *nix - - To cross-compile for Windows, Linux & gcc-mingw-w64-i686 (and also gcc-mingw-w64-x86-64 - for 64-bit binaries) are required. - - - To cross-compile Windows 32-bit binary, simply run: - - $ ./make.sh cross-win32 - - - To cross-compile Windows 64-bit binary, run: - - $ ./make.sh cross-win64 - - Resulted files unicorn.dll, unicorn.lib & samples/sample*.exe can then - be used on Windows machine. - - To run sample_x86.exe on Windows 32-bit, you need the following files: - - unicorn.dll - - /usr/i686-w64-mingw32/sys-root/mingw/bin/libglib-2.0-0.dll - - /usr/lib/gcc/i686-w64-mingw32/4.8/libgcc_s_sjlj-1.dll - - /usr/i686-w64-mingw32/lib/libwinpthread-1.dll - - To run sample_x86.exe on Windows 64-bit, you need the following files: - - unicorn.dll - - /usr/x86_64-w64-mingw32/sys-root/mingw/bin/libglib-2.0-0.dll - - /usr/lib/gcc/x86_64-w64-mingw32/4.8/libgcc_s_sjlj-1.dll - - /usr/x86_64-w64-mingw32/lib/libwinpthread-1.dll - - Then run either "sample_x86.exe -32" or "sample_x86.exe -64" to test emulators for X86 32-bit or X86 64-bit. - For other architectures, run "sample_xxx.exe" found in the same directory. - - - -[6] Cross-compile for iOS from Mac OSX. - - To cross-compile for iOS (iPhone/iPad/iPod), Mac OSX with XCode installed is required. - - - To cross-compile for ArmV7 (iPod 4, iPad 1/2/3, iPhone4, iPhone4S), run: - $ ./make.sh ios_armv7 - - - To cross-compile for ArmV7s (iPad 4, iPhone 5C, iPad mini), run: - $ ./make.sh ios_armv7s - - - To cross-compile for Arm64 (iPhone 5S, iPad mini Retina, iPad Air), run: - $ ./make.sh ios_arm64 - - - To cross-compile for all iDevices (armv7 + armv7s + arm64), run: - $ ./make.sh ios - - Resulted files libunicorn.dylib, libunicorn.a & tests/test* can then - be used on iOS devices. - - - -[7] Cross-compile for Android - - To cross-compile for Android (smartphone/tablet), Android NDK is required. - NOTE: Only ARM and ARM64 are currently supported. - - $ NDK=/android/android-ndk-r10e ./make.sh cross-android arm - or - $ NDK=/android/android-ndk-r10e ./make.sh cross-android arm64 - - Resulted files libunicorn.so, libunicorn.a & tests/test* can then - be used on Android devices. - - - -[8] By default, "cc" (default C compiler on the system) is used as compiler. - - - To use "clang" compiler instead, run the command below: - - $ ./make.sh clang - - - To use "gcc" compiler instead, run: - - $ ./make.sh gcc - - - -[9] To uninstall Unicorn, run the command below: - - $ sudo ./make.sh uninstall - - - -[10] Language bindings - - Look for the bindings under directory bindings/, and refer to README file - of corresponding languages. - - - -[11] Unit tests - - Automated unit tests use the cmocka unit testing framework (https://cmocka.org/). - It can be installed in most Linux distros using the package manager, e.g. - `sudo yum install libcmocka libcmocka-devel`, or you can easily build and install it from source. - - You can run the tests by running `make test` in the project directory. diff --git a/README.md b/README.md index 5acff9a5..eb061cdd 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ This project is released under the [GPL license](COPYING). Compilation & Docs ------------------ -See [COMPILE.TXT](COMPILE.TXT) file for how to compile and install Unicorn. +See [docs/COMPILE.md](docs/COMPILE.md) file for how to compile and install Unicorn. More documentation is available in [docs/README.md](docs/README.md). diff --git a/docs/COMPILE-NIX.md b/docs/COMPILE-NIX.md new file mode 100644 index 00000000..811ad8a9 --- /dev/null +++ b/docs/COMPILE-NIX.md @@ -0,0 +1,169 @@ +This documentation explains how to compile, install & run Unicorn on MacOSX, +Linux, *BSD, Solaris, Android & iOS. + +To compile for Microsoft Windows, see [COMPILE-WINDOWS.md](COMPILE-WINDOWS.md) + + *-*-*-*-*-* + +[0] Dependencies + +Unicorn requires few dependent packages as follows. + +- For Mac OS X, "pkg-config" and "glib" are needed. + Brew users can install "pkg-config" and "glib" with: + + $ brew install pkg-config glib + +- For Linux, "glib2-dev" is needed. + Ubuntu/Debian users can install this with: + + $ sudo apt-get install libglib2.0-dev + + + +[1] Tailor Unicorn to your need. + + Out of 6 archtitectures supported by Unicorn (Arm, Arm64, M68K, Mips, Sparc, + & X86), if you just need several selected archs, choose which ones you want + to compile in by editing "config.mk" before going to next steps. + + By default, all 6 architectures are compiled. + + The other way of customize Unicorn without having to edit config.mk is to + pass the desired options on the commandline to ./make.sh. Currently, + Unicorn supports 4 options, as follows. + + - UNICORN_ARCHS: specify list of architectures to compiled in. + - UNICORN_STATIC: build static library. + - UNICORN_SHARED: build dynamic (shared) library. + - UNICORN_QEMU_FLAGS: specify extra flags for qemu's configure script + + To avoid editing config.mk for these customization, we can pass their values to + make.sh, as follows. + + $ UNICORN_ARCHS="arm aarch64 x86" ./make.sh + + NOTE: on commandline, put these values in front of ./make.sh, not after it. + + For each option, refer to docs/README for more details. + + + +[2] Compile and install from source on *nix + + To build Unicorn on *nix (such as MacOSX, Linux, *BSD, Solaris): + + - To compile for current platform, run: + + $ ./make.sh + + - Unicorn requires Python 2.x to compile. If Python 2.x is not the default + Python interpreter, ensure that the appropriate option is set: + + $ UNICORN_QEMU_FLAGS="--python=/path/to/python2" ./make.sh + + - To cross-compile Unicorn on 64-bit OS to target 32-bit binary, run: + + $ ./make.sh nix32 + + After compiling, install Unicorn with: + + $ sudo ./make.sh install + + For FreeBSD/OpenBSD, where sudo is unavailable, run: + + $ su; ./make.sh install + + Users are then required to enter root password to copy Unicorn into machine + system directories. + + Afterwards, run ./samples/sample_all.sh to test the sample emulations. + + + NOTE: The core framework installed by "./make.sh install" consist of + following files: + + /usr/include/unicorn/unicorn.h + /usr/include/unicorn/x86.h + /usr/include/unicorn/arm.h + /usr/include/unicorn/arm64.h + /usr/include/unicorn/mips.h + /usr/include/unicorn/ppc.h + /usr/include/unicorn/sparc.h + /usr/include/unicorn/m68k.h + /usr/lib/libunicorn.so (for Linux/*nix), or /usr/lib/libunicorn.dylib (OSX) + /usr/lib/libunicorn.a + + + +[3] Cross-compile for iOS from Mac OSX. + + To cross-compile for iOS (iPhone/iPad/iPod), Mac OSX with XCode installed is required. + + - To cross-compile for ArmV7 (iPod 4, iPad 1/2/3, iPhone4, iPhone4S), run: + + $ ./make.sh ios_armv7 + + - To cross-compile for ArmV7s (iPad 4, iPhone 5C, iPad mini), run: + + $ ./make.sh ios_armv7s + + - To cross-compile for Arm64 (iPhone 5S, iPad mini Retina, iPad Air), run: + + $ ./make.sh ios_arm64 + + - To cross-compile for all iDevices (armv7 + armv7s + arm64), run: + + $ ./make.sh ios + + Resulted files libunicorn.dylib, libunicorn.a & tests/test* can then + be used on iOS devices. + + + +[4] Cross-compile for Android + + To cross-compile for Android (smartphone/tablet), Android NDK is required. + NOTE: Only ARM and ARM64 are currently supported. + + $ NDK=/android/android-ndk-r10e ./make.sh cross-android arm + or + $ NDK=/android/android-ndk-r10e ./make.sh cross-android arm64 + + Resulted files libunicorn.so, libunicorn.a & tests/test* can then + be used on Android devices. + + + +[5] By default, "cc" (default C compiler on the system) is used as compiler. + + - To use "clang" compiler instead, run the command below: + + $ ./make.sh clang + + - To use "gcc" compiler instead, run: + + $ ./make.sh gcc + + + +[6] To uninstall Unicorn, run the command below: + + $ sudo ./make.sh uninstall + + + +[7] Language bindings + + Look for the bindings under directory bindings/, and refer to README file + of corresponding languages. + + + +[8] Unit tests + + Automated unit tests use the cmocka unit testing framework (https://cmocka.org/). + It can be installed in most Linux distros using the package manager, e.g. + `sudo yum install libcmocka libcmocka-devel`, or you can easily build and install it from source. + + You can run the tests by running `make test` in the project directory. diff --git a/docs/COMPILE-WINDOWS.md b/docs/COMPILE-WINDOWS.md new file mode 100644 index 00000000..0a94687f --- /dev/null +++ b/docs/COMPILE-WINDOWS.md @@ -0,0 +1,200 @@ +We also show steps to cross-compile Unicorn for Microsoft Windows. + +To compile for *nix OS, see [COMPILE-NIX.md](COMPILE-NIX.md) + + *-*-*-*-*-* + +[0] Dependencies + + For Windows, cross-compile requires Mingw. Mingw-glib2 is needed. + At the moment, it is confirmed that Unicorn can be compiled either on Ubuntu + or Windows. + + - On Ubuntu 14.04 64-bit, do: + + 1. Download DEB packages for Mingw64 from: + + https://launchpad.net/~greg-hellings/+archive/ubuntu/mingw-libs/+build/2924251 + + 2. To cross-compile for Windows 32-bit, install Mingw with (ignore all the warnings): + + $ sudo dpkg -i --force-depends mingw64-x86-glib2_2.31.0_all.deb + + To cross-compile for Windows 64-bit, install Mingw with: + + $ sudo dpkg -i --force-depends mingw64-x64-glib2_2.31.0_all.deb + + + - On Windows, install MinGW via package MSYS2 at https://msys2.github.io/ + + Follow the install instructions and don't forget to update the system packages with: + + $ pacman --needed -Sy bash pacman pacman-mirrors msys2-runtime + + Then close MSYS2, run it again from Start menu and update the rest with: + + $ pacman -Su + + Finally, install required toolchain to build C projects. + + - To compile for Windows 32-bit, run: + + $ pacman -S python2 + $ pacman -S make + $ pacman -S pkg-config + $ pacman -S mingw-w64-i686-glib2 + $ pacman -S mingw-w64-i686-toolchain + + - To compile for Windows 64-bit, run: + + $ pacman -S python2 + $ pacman -S make + $ pacman -S pkg-config + $ pacman -S mingw-w64-x86_64-glib2 + $ pacman -S mingw-w64-x86_64-toolchain + +- For Cygwin, "make", "gcc-core", "pkg-config", "libpcre-devel", "zlib-devel" + and "libglib2.0-devel" are needed. + + If apt-cyg is available, you can install these with: + + $ apt-cyg install make gcc-core pkg-config libpcre-devel zlib-devel libglib2.0-devel + + + +[1] Tailor Unicorn to your need. + + Out of 6 archtitectures supported by Unicorn (Arm, Arm64, M68K, Mips, Sparc, + & X86), if you just need several selected archs, choose which ones you want + to compile in by editing "config.mk" before going to next steps. + + By default, all 6 architectures are compiled. + + The other way of customize Unicorn without having to edit config.mk is to + pass the desired options on the commandline to ./make.sh. Currently, + Unicorn supports 4 options, as follows. + + - UNICORN_ARCHS: specify list of architectures to compiled in. + - UNICORN_STATIC: build static library. + - UNICORN_SHARED: build dynamic (shared) library. + - UNICORN_QEMU_FLAGS: specify extra flags for qemu's configure script + + To avoid editing config.mk for these customization, we can pass their values to + make.sh, as follows. + + $ UNICORN_ARCHS="arm aarch64 x86" ./make.sh + + NOTE: on commandline, put these values in front of ./make.sh, not after it. + + For each option, refer to docs/README for more details. + + + +[2] Compile from source on Windows - with MinGW (MSYS2) + + To compile with MinGW, install MSYS2 as instructed in the first section. + Then, build Unicorn with the next steps: + + - To compile Windows 32-bit binary with MinGW, run: + + $ ./make.sh cross-win32 + + - To compile Windows 64-bit binary with MinGW, run: + + $ ./make.sh cross-win64 + + Resulted files unicorn.dll, unicorn.lib & samples/sample*.exe can then + be used on Windows machine. + + To run sample_x86.exe on Windows 32-bit, you need the following files: + + unicorn.dll + %MSYS2%\mingw32\bin\libiconv-2.dll + %MSYS2%\mingw32\bin\libintl-8.dll + %MSYS2%\mingw32\bin\libglib-2.0-0.dll + %MSYS2%\mingw32\bin\libgcc_s_dw2-1.dll + %MSYS2%\mingw32\bin\libwinpthread-1.dll + + To run sample_x86.exe on Windows 64-bit, you need the following files: + + unicorn.dll + %MSYS2%\mingw64\bin\libiconv-2.dll + %MSYS2%\mingw64\bin\libintl-8.dll + %MSYS2%\mingw64\bin\libglib-2.0-0.dll + %MSYS2%\mingw64\bin\libgcc_s_seh-1.dll + %MSYS2%\mingw64\bin\libwinpthread-1.dll + + + +[3] Compile and install from source on Cygwin + + To build Unicorn on Cygwin, run: + + $ ./make.sh + + After compiling, install Unicorn with: + + $ ./make.sh install + + Resulted files cygunicorn.dll, libunicorn.dll.a and libunicorn.a can be + used on Cygwin but not native Windows. + + NOTE: The core framework installed by "./make.sh install" consist of + following files: + + /usr/include/unicorn/*.h + /usr/bin/cygunicorn.dll + /usr/lib/libunicorn.dll.a + /usr/lib/libunicorn.a + + + +[4] Cross-compile for Windows from *nix + + To cross-compile for Windows, Linux & gcc-mingw-w64-i686 (and also gcc-mingw-w64-x86-64 + for 64-bit binaries) are required. + + - To cross-compile Windows 32-bit binary, simply run: + + $ ./make.sh cross-win32 + + - To cross-compile Windows 64-bit binary, run: + + $ ./make.sh cross-win64 + + Resulted files unicorn.dll, unicorn.lib & samples/sample*.exe can then + be used on Windows machine. + + To run sample_x86.exe on Windows 32-bit, you need the following files: + + unicorn.dll + /usr/i686-w64-mingw32/sys-root/mingw/bin/libglib-2.0-0.dll + /usr/lib/gcc/i686-w64-mingw32/4.8/libgcc_s_sjlj-1.dll + /usr/i686-w64-mingw32/lib/libwinpthread-1.dll + + To run sample_x86.exe on Windows 64-bit, you need the following files: + + unicorn.dll + /usr/x86_64-w64-mingw32/sys-root/mingw/bin/libglib-2.0-0.dll + /usr/lib/gcc/x86_64-w64-mingw32/4.8/libgcc_s_sjlj-1.dll + /usr/x86_64-w64-mingw32/lib/libwinpthread-1.dll + + Then run either "sample_x86.exe -32" or "sample_x86.exe -64" to test emulators for X86 32-bit or X86 64-bit. + For other architectures, run "sample_xxx.exe" found in the same directory. + + + +[5] Language bindings + + Look for the bindings under directory bindings/, and refer to README file + of corresponding languages. + + + +[6] Unit tests + + Automated unit tests use the cmocka unit testing framework (https://cmocka.org/). + It can be installed in most Linux distros using the package manager, e.g. + `sudo yum install libcmocka libcmocka-devel`, or you can easily build and install it from source. + + You can run the tests by running `make test` in the project directory. diff --git a/docs/COMPILE.md b/docs/COMPILE.md new file mode 100644 index 00000000..2953b9b8 --- /dev/null +++ b/docs/COMPILE.md @@ -0,0 +1,10 @@ +To compile Keystone on Mac OS X, Linux, BSD, Solaris and all kind of nix OS, +see [COMPILE-NIX.md](COMPILE-NIX.md) + +To compile Keystone on Windows, see [COMPILE-WINDOWS.md](COMPILE-WINDOWS.md) + +Then learn more on how to code your own tools with our samples. + + - For C sample code, see code in directory samples/sample*.c + - For Python sample code, see code in directory bindings/python/sample*.py + - For samples of other bindings, look into directories bindings//