Imported Upstream version 2.0.1+dfsg
[packages/binwalk.git] / INSTALL.md
1 Before You Start
2 ================
3
4 Binwalk supports Python 2.7 - 3.x. Although binwalk is slightly faster in Python 3, the Python OpenGL bindings are still experimental for Python 3, so Python 2.7 is recommended.
5
6 The following installation procedures assume that you are installing binwalk to be run using Python 2.7. If you want to use binwalk in Python 3, some package
7 names and installation procedures may differ slightly.
8
9 Installation
10 ============
11
12 Installation follows the typical configure/make process (standard development tools such as gcc, make, and Python must be installed in order to build):
13
14     $ ./configure
15     $ make
16     $ sudo make install
17
18 Binwalk's core features will work out of the box without any additional dependencies. However, to take advantage of binwalk's graphing and extraction capabilities, multiple supporting utilities/packages need to be installed.
19
20 To ease "dependency hell", a shell script named `deps.sh` is included which attempts to install all required dependencies for Debian and RedHat based systems:
21
22     $ ./deps.sh
23
24 If you are running a different system, or prefer to install these dependencies manually, see the Dependencies section below.
25
26 Dependencies
27 ============
28
29 The following dependencies are only required for optional binwalk features, such as file extraction and graphing capabilities. Unless otherwise specified, these dependencies are available from most Linux package managers.
30
31 Binwalk uses [pyqtgraph](http://www.pyqtgraph.org) to generate graphs and visualizations, which requires the following: 
32
33     libqt4-opengl 
34     python-opengl 
35     python-qt4 
36     python-qt4-gl 
37     python-numpy 
38     python-scipy
39
40 Binwalk relies on multiple external utilties in order to automatically extract/decompress files and data:
41
42     mtd-utils
43     zlib1g-dev
44     liblzma-dev
45     ncompress
46     gzip
47     bzip2
48     tar
49     arj
50     p7zip
51     cabextract
52     p7zip-full
53     openjdk-6-jdk
54     firmware-mod-kit [https://code.google.com/p/firmware-mod-kit]
55
56 Bundled Software
57 ================
58
59 For convenience, the following libraries are bundled with binwalk and will not conflict with system-wide libraries:
60
61     libmagic
62     libfuzzy
63     pyqtgraph
64
65 Installation of any individual bundled library can be disabled at build time:
66
67     $ ./configure --disable-libmagic --disable-libfuzzy --disable-pyqtgraph
68
69 Alternatively, installation of all bundled libraries can be disabled at build time:
70
71     $ ./configure --disable-bundles
72
73 If a bundled library is disabled, the equivalent library must be installed to a standard system library location (e.g., `/usr/lib`, `/usr/local/lib`, etc) in order for binwalk to function properly.
74
75 **Note:** If the bundled libmagic library is not used, be aware that:
76
77 1. Some versions of libmagic have known bugs that are triggered by binwalk under some circumstances.
78 2. Minor version releases of libmagic may not be backwards compatible with each other and installation of the wrong version of libmagic may cause binwalk to fail to function properly. 
79 3. Conversely, updating libmagic to a version that works with binwalk may cause other utilities that rely on libmagic to fail. 
80
81 Currently, the following libmagic versions are known to work properly with binwalk (other versions may or may not work):
82
83     5.18
84     5.19
85
86
87 Specifying a Python Interpreter
88 ===============================
89
90 The default python interpreter used during install is the system-wide `python` interpreter. A different interpreter (e.g., `python2`, `python3`) can be specified at build time:
91
92     $ ./configure --with-python=python3
93
94
95 Uninstallation
96 ==============
97
98 The following command will remove binwalk from your system. Note that this will *not* remove manually installed packages, or utilities installed via deps.sh:
99
100     $ sudo make uninstall
101