Merge pull request #460 from bwelton/inst_fix
[dyninst.git] / README.md
1 # Dyninst
2
3 ## Branch states
4
5 | Branch                                  | Status        | Notes                                              |
6 | --------------------------------------- |:-------------:|:--------------------------------------------------:|
7 | master                                  | stable        | See below                                          |
8 | arm64                                   | experimental  |                                                    |
9
10 ## Notes
11
12 * Known issues should have open issues associated with them.
13 * ARM64 support in Dataflow/ParseAPI is experimental and incomplete.
14 * PPC64/little endian support in read-level interfaces 
15  (symtab, stackwalker, proccontrol) is experimental.
16 * PPC64/little endian support in write-level interfaces is not implemented.
17
18 All non-API-breaking bug fixes should land here. All non-ABI-breaking
19 bug fixes should also land on v9.2.x.
20
21 ## Build DyninstAPI and its subcomponents
22
23 ### Configuration
24
25 Dyninst is now built via CMake. We recommend performing an interactive
26 configuration with "ccmake ." first, in order to see which options are
27 relevant for your system. You may also perform a batch configuration
28 with "cmake .".  Options are passed to CMake with -DVAR=VALUE. Common
29 options include:
30
31 ```
32 Boost_INCLUDE_DIR 
33 CMAKE_BUILD_TYPE 
34 CMAKE_INSTALL_PREFIX
35 LIBDWARF_INCLUDE_DIR 
36 LIBDWARF_LIBRARIES 
37 LIBELF_INCLUDE_DIR
38 LIBELF_LIBRARIES 
39 IBERTY_LIBRARIES
40 ```
41
42 CMake's default generator on Linux is normally "Unix Makefiles", and
43 on Windows, it will normally produce project files for the most recent
44 version of Visual Studio on your system. Other generators should work
45 but are not tested. After the CMake step concludes, you will have
46 appropriate Makefiles or equivalent and can build Dyninst.
47
48 We require CMake 2.6 as a minimum on all systems, and CMake 2.8.11
49 allows us to automatically download and build libelf/libdwarf/binutils
50 on ELF systems if they are needed. If you do not have a sufficiently
51 recent CMake, you may need to manually specify the location of these
52 dependencies. If you are cross-compiling Dyninst, including builds for
53 various Cray and Intel MIC systems, you will either need a toolchain
54 file that specifies how to properly cross-compile, or you will need to
55 manually define the appropriate compiler, library locations, include
56 locations, and the CROSS_COMPILING flag so that the build system will
57 properly evaluate what can be built and linked in your environment.
58
59 ### Building and installing
60
61 To build Dyninst and all its components, "make && make install" from
62 the top-level directory of the source tree. To build and install a
63 single component and its dependencies, do the same thing from that
64 component's subdirectory. Libraries will be installed into
65 `CMAKE_INSTALL_PREFIX/INSTALL_LIB_DIR`, and headers will be installed
66 into `CMAKE_INSTALL_PREFIX/INSTALL_INCLUDE_DIR`. If you wish to import
67 Dyninst into your own CMake projects, the export information is in
68 `CMAKE_INSTALL_PREFIX/INSTALL_CMAKE_DIR`. PDF documentation is included
69 and installed to `CMAKE_INSTALL_PREFIX/INSTALL_DOC_DIR`. If you update
70 the LaTeX source documents for any manuals, "make doc" will rebuild
71 them. Components may be built and installed individually: "make
72 $COMPONENT" and "make $COMPONENT-install" respectively; this will
73 appropriately respect inter-component dependencies.
74
75 ### What's new
76
77 ## New features
78
79 * ARM64 SIMD support in instructionAPI
80
81 * Support for all x86 instruction sets up to Knight's Landing (AVX, AVX2, AVX512)
82
83 * DataflowAPI now has an official manual
84
85 * Initial ppc64/little endian support in Symtab, InstructionAPI, ProcControl, and Stackwalker. Add
86 -Darch_ppc64_little_endian to your CMake command line when building on little-endian ppc64 systems.
87
88 ## Bug fixes
89
90 * PIE binaries should now be rewritten correctly, even if they have a zero base address
91
92 * Symtab should now correctly file symbols into their associated modules based on the best available DWARF information
93
94 * Many more fixes in x86 instruction decoding
95
96 * Enhancements to jump table analysis
97
98 * PC-relative memory accesses in VEX instructions can now be relocated correctly
99
100 * Various proccontrol bug fixes
101
102 * RTlib's `DYNINSTos_malloc` and `DYNINSTos_free` should now be signal-safe
103
104 * RTlib's tramp guard lock/unlock functions should now avoid making implicit function calls
105 (which are unsafe from tramp guard code)
106
107 * ppc64 bit rot for create/attach modes is fixed
108
109 ## Known Issues
110
111 * ppc64 rewriter mode does not handle any code that does not conform to the "caller sets up TOC" model for intermodule
112 calls
113
114 * Windows 64-bit mode is not yet supported
115
116 * Windows rewriter mode is not yet supported
117
118 * Exceptions in relocated code will not be caught
119
120 * Linux rewriter mode for 32-bit, statically linked binaries does not support binaries with .plt, .rel, or .rela
121 sections.
122
123 * Callbacks at thread or process exit that stop the process will deadlock when a SIGSEGV occurs on a thread other than
124 the main thread of a process
125
126 * InstructionAPI's format() method does not produce AT&T syntax output
127
128 * Stackwalker is fragile on Windows
129
130 * Parsing a binary with no functions (typically a single object file) will crash at CodeObject destruction time.