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