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