Right now, the BPatch_deref and BPatch_regExpr do not specify the size.
[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_ROOT_DIR```: base directory of your elfutils installation
58
59 ```TBB_ROOT_DIR```: base directory of your TBB installation
60
61 ```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.
62
63 ```CMAKE_INSTALL_PREFIX```: like PREFIX for autotools-based systems. Where to install things.
64
65 ```USE_OpenMP```: whether or not use OpenMP for parallel parsing. Default to be ```ON```
66
67 ```ENABLE_STATIC_LIBS```: also build dyninst in static libraries. Default to be ```NO```. Set to ```YES``` to build static libraries. 
68
69 CMake's default generator on Linux is normally "Unix Makefiles", and
70 on Windows, it will normally produce project files for the most recent
71 version of Visual Studio on your system. Other generators should work
72 but are not tested. After the CMake step concludes, you will have
73 appropriate Makefiles or equivalent and can build Dyninst.
74
75 If you are cross-compiling Dyninst, including builds for
76 various Cray and Intel MIC systems, you will either need a toolchain
77 file that specifies how to properly cross-compile, or you will need to
78 manually define the appropriate compiler, library locations, include
79 locations, and the CROSS_COMPILING flag so that the build system will
80 properly evaluate what can be built and linked in your environment.
81
82 #### Building and installing
83 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.
84 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.
85
86 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.
87
88 If you wish to import
89 Dyninst into your own CMake projects, the export information is in
90 `CMAKE_INSTALL_PREFIX/INSTALL_CMAKE_DIR`. PDF documentation is included
91 and installed to `CMAKE_INSTALL_PREFIX/INSTALL_DOC_DIR`. If you update
92 the LaTeX source documents for any manuals, "make doc" will rebuild
93 them. Components may be built and installed individually: "make
94 $COMPONENT" and "make $COMPONENT-install" respectively; this will
95 appropriately respect inter-component dependencies.
96
97 ### FAQs of building Dyninst
98
99 1. Q: What should I do if the build failed and showed
100
101 ```"/lib64/libdw.so.1: version `ELFUTILS_0.173' not found```
102
103 or
104
105 ```error: 'dwarf_next_lines' was not declared in this scope```
106
107 A: Dyninst now depends on elfutils-0.173 or later. If you are seeing the above errors, it means the elfutils installed on your system is older than 0.173. We recommend that you set ```ElfUtils_ROOT_DIR``` to empty, which will trigger the build system to automatically download the correct version of elfutils. Or you can upgrade your elfutils with your system package manager.
108
109 2. Q: Where are the dependency libraries downloaded by Dyninst?
110
111 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 install Dyninst in ```/home/user/dyninst/install```, then the library and header files for elfutils, TBB, and boost which were built from source are in ```/home/user/dyninst/lib``` and ```/home/user/dyninst/include```, respectively.
112
113 3. Q: My system has pre-installed Boost, but the build failed due to that cannot find boost libraries.
114
115 A: Dyninst requires at least Boost-1.61. If your system version is newer, but still not found, then point ```Boost_ROOT_DIR``` to the base of your system's Boost install.
116
117 ## Known Issues
118
119 * Windows 64-bit mode is not yet supported
120
121 * Windows rewriter mode is not yet supported
122
123 * Exceptions in relocated code will not be caught
124
125 * Linux rewriter mode for 32-bit, statically linked binaries does not support binaries with .plt, .rel, or .rela
126 sections.
127
128 * Callbacks at thread or process exit that stop the process will deadlock when a SIGSEGV occurs on a thread other than
129 the main thread of a process
130
131 * Stackwalker is fragile on Windows
132
133 * Parsing a binary with no functions (typically a single object file) will crash at CodeObject destruction time.