stackwalker: added translation function for abstract
[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.
31
32 2) Building and installation
33
34 To build Dyninst and all its components, "make && make install" from
35 the top-level directory of the source tree. To build and install a
36 single component and its dependencies, do the same thing from that
37 component's subdirectory. Libraries will be installed into
38 CMAKE_INSTALL_PREFIX/INSTALL_LIB_DIR, and headers will be installed
39 into CMAKE_INSTALL_PREFIX/INSTALL_INCLUDE_DIR. If you wish to import
40 Dyninst into your own CMake projects, the export information is in
41 CMAKE_INSTALL_PREFIX/INSTALL_CMAKE_DIR. PDF documentation is included
42 and installed to CMAKE_INSTALL_PREFIX/INSTALL_DOC_DIR. If you update
43 the LaTeX source documents for any manuals, "make doc" will rebuild
44 them. Components may be built and installed individually: "make
45 $COMPONENT" and "make $COMPONENT-install" respectively; this will
46 appropriately respect inter-component dependencies.
47
48 3) What's new
49
50 SIGNIFICANT CAPABILITY CHANGES
51
52 * Dyninst now allows modification of the stack frames of
53   functions. See the manual for details.
54
55 * SD-Dyninst is now integrated into the Dyninst main line. See the
56   manual for details.
57
58 * Machine learning based gap parsing rules are now integrated into
59   Dyninst, and no longer need to be compiler-specific. Gap parsing
60   should find significantly more function entry points, particularly
61   when run on code generated by non-GNU compilers.
62
63 * SymtabAPI now provides information about inlined functions. See the
64   manual for details.
65
66 * SymtabAPI (in read-only mode), ProcControl, and Stackwalker (in
67   3rd-party mode) now work on ARM64 Linux.
68
69 * Loops are now represented in ParseAPI and PatchAPI, as well as at
70   the BPatch level. The loop interface has been extended to represent
71   irreducible loops correctly; see the manual for details.
72
73 PERFORMANCE/CORRECTNESS IMPROVEMENTS
74
75 * Indirect control flow is now analyzed by a principled, slicing-based
76   approach and its accuracy is substantially improved.
77
78 * SymtabAPI and ParseAPI should consume much less memory for
79   representing symbols, symbol indexes, line information, block
80   extents, and function extents. There will be a small CPU penalty
81   when opening files under SymtabAPI in exchange for this.
82
83 GENERAL BUG FIXES
84
85 * Fixes in ProcControl's exit handling code.
86