Debug output cleanning and ParseAPI manual update
[dyninst.git] / README.dyninst
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_LIBRARY
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.
42
43 3) What's new
44
45 SIGNIFICANT CAPABILITY CHANGES
46 * Dyninst now builds with CMake, produces appropriate package information for other projects, and will automatically download libelf/libdwarf/binutils if it can't find them.
47 * Dyninst now handles binaries built with DEP and ASLR on Windows
48 * Fixes to handler rewriting gcc 4.7+ static binaries and instrumenting gcc 4.8+/DWARF4 binaries.
49 * Proccontrol now provides access to pre- and post-syscall event callbacks.
50 * SymtabAPI now supports access to inlined functions/
51
52 FREQUENTLY ENCOUNTERED/CATASTROPHIC BUGS
53 * Fixed crash bugs when destroying Symtab objects.
54 * Fixed bug where reinstrumentation could cause a mutatee to crash.
55 * Fixed section alignment bugs in rewriter.
56 * Added checks and error returns for when a user has traps disabled, but instrumentation would require them.
57
58 PERFORMANCE/CORRECTNESS IMPROVEMENTS
59
60 * Optimized function call snippets via improved XMM save/restore generation.
61 * Handle a new jump table idiom seen in newer versions of libc.
62 * Fixed bugs where loadlibrary and exec callbacks from ProcControl were not guaranteed to occur with the process in a consistent state.
63 * Assorted proccontrol bug fixes for BG/Q.
64 * Fixed an outstanding signed/unsigned bug in InstructionAPI immediates.
65 * Improved performance and fixed bugs in block-level instrumentation, particularly in shared code
66
67 GENERAL BUG FIXES
68
69 * Fixed springboard bug: we weren't properly handling tail calls with respect to entry instrumentation
70 * Fixed various bugs in stack analysis leading to hangs.
71 * Fixed parsing bug: a jump to a function's own entry point is not a tail call.
72
73 QUALITY IMPROVEMENTS
74 * We now do type checking on parameter and return value snippets where possible.
75 * Properly control symbol visibility on Linux, so that only public Dyninst functions/variables are exposed to users.