Update README.md
[dyninst.git] / README.md
1 # Dyninst
2
3 ## Branch states
4
5 | Branch                                  | Status        | Notes                                              |
6 | --------------------------------------- |:-------------:|:--------------------------------------------------:|
7 | master                                  | stable        | See below                                          |
8 | aarch32                                 | experimental  | Contact Ray Chen (rchen at cs dot umd dot edu)     |
9
10 ## Notes
11
12 * Known issues should have open issues associated with them.
13 * ARMv8 (64 bit) support for dynamic instrumentation is experimental and incomplete.
14   For more details about current supported functionality refer to [Dyninst Support for the ARMv8 (64 bit)](https://github.com/dyninst/dyninst/wiki/DyninstAPI-ARMv8-status).
15
16 ## Build DyninstAPI and its subcomponents
17
18 ### Install with Spack
19
20 ```spack install dyninst```
21
22 ### Build from source (the short version)
23
24 1. Configure Dyninst with CMake
25
26 ```ccmake /path/to/dyninst/source```
27
28 2. Build and install Dyninst in parallel
29
30 ```make install -jN```
31
32 If this short version does not work for you, please refer to the long version and the FAQs below.
33
34 ### Build from source (the long version)
35
36 #### Configuration
37
38 Dyninst is built via CMake. We require CMake 3.0.0 as a minimum on all systems. CMake will automatically
39 search for dependencies and download them when not found. The main dependencies of Dyninst include:
40
41 1. elfutils, 0.173 minimum, https://sourceware.org/elfutils/
42
43 2. Boost, 1.61.0 or later recommended, https://www.boost.org/
44
45 3. The Intel Thread Building Blocks (TBB), 2018 U6 or later recommended, https://www.threadingbuildingblocks.org/
46
47 4. OpenMP, optional for parallel code parsing. Note that Dyninst will not automatically download or install OpenMP
48
49 We recommend performing an interactive
50 configuration with "ccmake /path/to/dyninst/source" first, in order to see which options are
51 relevant for your system. You may also perform a batch configuration
52 with "cmake /path/to/dyninst/source".  Options are passed to CMake with -DVAR=VALUE. Common
53 options include:
54
55 ```PATH_BOOST```: base directory of your boost installation
56
57 ```LIBELF_INCLUDE_DIR```: the location of elf.h and libelf.h
58
59 ```LIBELF_LIBRARIES```: full path of libelf.so
60
61 ```LIBDWARF_INCLUDE_DIR```: location of libdw.h
62
63 ```LIBDWARF_LIBRARIES```: full path of libdw.so
64
65 ```TBB_INCLUDE_DIRS```: the direcory of the include files of TBB
66
67 ```TBB_tbb_LIBRARY_DEBUG```: full path of libtbb_debug.so
68
69 ```TBB_tbb_LIBRARY_RELEASE```: full path of libtbb.so
70
71 ```CMAKE_BUILD_TYPE```: may be set to Debug, Release, or RelWithDebInfo for unoptimized, optimized, and optimized with debug information builds respectively. Note that RelWithDebInfo is the default.
72
73 ```CMAKE_INSTALL_PREFIX```: like PREFIX for autotools-based systems. Where to install things.
74
75 ```USE_OpenMP```: whether or not use OpenMP for parallel parsing. Default to be ```ON```
76
77 ```ENABLE_STATIC_LIBS```: also build dyninst in static libraries. Default to be ```NO```. Set to ```YES``` to build static libraries. 
78
79 CMake's default generator on Linux is normally "Unix Makefiles", and
80 on Windows, it will normally produce project files for the most recent
81 version of Visual Studio on your system. Other generators should work
82 but are not tested. After the CMake step concludes, you will have
83 appropriate Makefiles or equivalent and can build Dyninst.
84
85 If you are cross-compiling Dyninst, including builds for
86 various Cray and Intel MIC systems, you will either need a toolchain
87 file that specifies how to properly cross-compile, or you will need to
88 manually define the appropriate compiler, library locations, include
89 locations, and the CROSS_COMPILING flag so that the build system will
90 properly evaluate what can be built and linked in your environment.
91
92 #### Building and installing
93 CMake allows Dyninst to be built out-of-source; simply invoke CMake in your desired build location. In-source builds are still fully supported as well.
94 Each component of Dyninst may be built independently: cd $component; make. Standard make options will work; we fully support parallel compilation for make -jN. Setting VERBOSE=1 will replace the beautified CMake output with raw commands and their output, which can be useful for troubleshooting.
95
96 On Windows, you will need the Debug Information Access (DIA) SDK, which should be available with an MSDN subscription, in order to build Dyninst; you will not need libelf, libdwarf, binutils, or the GCC demangler. Dyninst is still built via CMake, and the NMake and Visual Studio project file generators should both work. We have not tested building Dyninst on Windows with gcc, and we do not expect this to work presently.
97
98 If you wish to import
99 Dyninst into your own CMake projects, the export information is in
100 `CMAKE_INSTALL_PREFIX/INSTALL_CMAKE_DIR`. PDF documentation is included
101 and installed to `CMAKE_INSTALL_PREFIX/INSTALL_DOC_DIR`. If you update
102 the LaTeX source documents for any manuals, "make doc" will rebuild
103 them. Components may be built and installed individually: "make
104 $COMPONENT" and "make $COMPONENT-install" respectively; this will
105 appropriately respect inter-component dependencies.
106
107 ### FAQs of building Dyninst
108
109 1. Q: What should I do if the build failed and showed
110
111 ```"/lib64/libdw.so.1: version `ELFUTILS_0.173' not found```
112
113 or
114
115 ```error: 'dwarf_next_lines' was not declared in this scope```
116
117 A: Dyninst now depends on elfutils-0.173 or later. If you are seeing above errors, it means the elfutils installed on your system is older than 0.173. We recommend that you set ```LIBELF_INCLUDE_DIR```, ```LIBELF_LIBRARIES```, ```LIBDWARF_INCLUDE_DIR```, and ```LIBDWARF_LIBRARIES``` to empty, which will trigger the CMake to automatically download the correct version of elfutils. Or you can upgrade your elfutils with your system package manager.
118
119 2. Q: Where are the dependency libraries downloaded by Dyninst?
120
121 A: After installation, Dyninst should copy all dependencies to the install location. In case where the dependencies are not copied, they can be found in the directory where you build Dyninst. For example, suppose you configure and build Dyninst at: ```/home/user/dyninst/build```
122
123 Then elfutils, TBB, boost can be found at ```/home/user/dyninst/build/elfutils/```, ```/home/user/dyninst/build/tbb/```, ```/home/user/dyninst/build/boost/```, respectively.
124
125 3. Q: My system has pre-installed Boost, but the build failed due to that cannot find boost libraries.
126
127 A: Boost's library naming convention is a little confusing. You probably have the non-multi-threading version installed. So your boost libraries will look like "libboost_system.so". Dyninst links against the multi-threading version of boost, so it will needs "libboost_system-mt.so". Note the "-mt" in the library name. There are two ways to work around:
128
129 (1) Set ```PATH_BOOST``` to empy which will trigger Dyninst to automaticall build Boost
130
131 (2) Create symbolic links from non-multi-threading ones to multi-threading ones (https://stackoverflow.com/questions/3031768/boost-thread-linking-boost-thread-vs-boost-thread-mt)
132
133 ## Known Issues
134
135 * Windows 64-bit mode is not yet supported
136
137 * Windows rewriter mode is not yet supported
138
139 * Exceptions in relocated code will not be caught
140
141 * Linux rewriter mode for 32-bit, statically linked binaries does not support binaries with .plt, .rel, or .rela
142 sections.
143
144 * Callbacks at thread or process exit that stop the process will deadlock when a SIGSEGV occurs on a thread other than
145 the main thread of a process
146
147 * Stackwalker is fragile on Windows
148
149 * Parsing a binary with no functions (typically a single object file) will crash at CodeObject destruction time.