Dyninst staging area @ L.E.R Code
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
LER0ever 4e009f34bc Merge branch 'master' of https://github.com/dyninst/dyninst 1 week ago
cmake Bump the version number to 10.0.0 1 month ago
common Fix 64-bit sign/unsigned comparison, multi, and division on power 1 week ago
dataflowAPI Update latex based manuals 1 month ago
dwarf Separate debug info file issue fixed. 2 months ago
dynC_API builds clean under icc 1 year ago
dyninstAPI Merge branch 'master' of https://github.com/dyninst/dyninst 1 week ago
dyninstAPI_RT Correct LDR/STR instructions for SIMD&FP Saving all FP registers in BaseTramp Remove #if for DYNINST_snippetBreakpoint 1 month ago
elf Merge branch 'master' into new-parallel-parsing. Also make changes to 3 months ago
examples Merge pull request #513 from jmellorcrummey/fix-openmp-link 1 week ago
external Add initial code for power 32 semantics and symbolic expansion for power 64 1 year ago
instructionAPI Update latex based manuals 1 month ago
parseAPI Update latex based manuals 1 month ago
parseThat as needed, add -fopenmp flag when linking executables 1 week ago
patchAPI ParseAPI fixes: test1_1 create now passes 9 months ago
proccontrol Fix wrong handling for PTRACE_EVENT_EXIT in proccontrol. Currently, each time we see PTRACE_EVENT_EXIT, we assume the mutatee exited normally. However, this is a wrong assumption. Based on the man page of PTRACE: 2 weeks ago
scripts Initial cmake fixes 3 years ago
stackwalk Merge branch 'master' into new-parallel-parsing 1 month ago
symlite Determine the architecture of an ELF by looking at the file header instead of the compiled architecture 2 years ago
symtabAPI Update latex based manuals 1 month ago
syscalls new file: .syntastic_cpp_config 3 years ago
valueAdded Purge AIX support 4 years ago
.github_changelog_generator Clean up change log 1 month ago
.gitignore update debug code 20181205 1 week ago
.gitmodules Merge John's changes and update test suite. 10 months ago
.syntastic_cpp_config new file: .syntastic_cpp_config 3 years ago
.travis.yml Use elfutils-dev package for travis, so that we don't have to build from scratch--CLang can't manage it out of the box. 1 year ago
CHANGELOG.md Clean up change log 1 month ago
CMakeLists.txt Merge branch 'master' of https://github.com/dyninst/dyninst 1 week ago
COPYRIGHT Update version strings to 8.1.1; retire DepGraphAPI 5 years ago
DyninstConfigVersion.cmake CMake integration for Windows. 5 years ago
LICENSE.md Update and rename LGPL to LICENSE.md 1 year ago
README.md Update README.md 4 weeks ago
appveyor.yml Add cache entry for boost to appveyor config 1 year ago

README.md

Dyninst

Branch states

Branch Status Notes
master stable See below
aarch32 experimental Contact Ray Chen (rchen at cs dot umd dot edu)

Notes

  • Known issues should have open issues associated with them.
  • ARMv8 (64 bit) support for dynamic instrumentation is experimental and incomplete. For more details about current supported functionality refer to Dyninst Support for the ARMv8 (64 bit).

Build DyninstAPI and its subcomponents

Install with Spack

spack install dyninst

Build from source (the short version)

  1. Configure Dyninst with CMake

ccmake /path/to/dyninst/source

  1. Build and install Dyninst in parallel

make install -jN

If this short version does not work for you, please refer to the long version and the FAQs below.

Build from source (the long version)

Configuration

Dyninst is built via CMake. We require CMake 3.0.0 as a minimum on all systems. CMake will automatically search for dependencies and download them when not found. The main dependencies of Dyninst include:

  1. elfutils, 0.173 minimum, https://sourceware.org/elfutils/

  2. Boost, 1.61.0 or later recommended, https://www.boost.org/

  3. The Intel Thread Building Blocks (TBB), 2018 U6 or later recommended, https://www.threadingbuildingblocks.org/

  4. OpenMP, optional for parallel code parsing. Note that Dyninst will not automatically download or install OpenMP

We recommend performing an interactive configuration with “ccmake /path/to/dyninst/source” first, in order to see which options are relevant for your system. You may also perform a batch configuration with “cmake /path/to/dyninst/source”. Options are passed to CMake with -DVAR=VALUE. Common options include:

PATH_BOOST: base directory of your boost installation

LIBELF_INCLUDE_DIR: the location of elf.h and libelf.h

LIBELF_LIBRARIES: full path of libelf.so

LIBDWARF_INCLUDE_DIR: location of libdw.h

LIBDWARF_LIBRARIES: full path of libdw.so

TBB_INCLUDE_DIRS: the direcory of the include files of TBB

TBB_tbb_LIBRARY_DEBUG: full path of libtbb_debug.so

TBB_tbb_LIBRARY_RELEASE: full path of libtbb.so

CMAKE_BUILD_TYPE: may be set to Debug, Release, or RelWithDebInfo for unoptimized, optimized, and optimized with debug information builds respectively. Note that RelWithDebInfo is the default.

CMAKE_INSTALL_PREFIX: like PREFIX for autotools-based systems. Where to install things.

USE_OpenMP: whether or not use OpenMP for parallel parsing. Default to be ON

ENABLE_STATIC_LIBS: also build dyninst in static libraries. Default to be NO. Set to YES to build static libraries.

CMake’s default generator on Linux is normally “Unix Makefiles”, and on Windows, it will normally produce project files for the most recent version of Visual Studio on your system. Other generators should work but are not tested. After the CMake step concludes, you will have appropriate Makefiles or equivalent and can build Dyninst.

If you are cross-compiling Dyninst, including builds for various Cray and Intel MIC systems, you will either need a toolchain file that specifies how to properly cross-compile, or you will need to manually define the appropriate compiler, library locations, include locations, and the CROSS_COMPILING flag so that the build system will properly evaluate what can be built and linked in your environment.

Building and installing

CMake allows Dyninst to be built out-of-source; simply invoke CMake in your desired build location. In-source builds are still fully supported as well. Each component of Dyninst may be built independently: cd $component; make. Standard make options will work; we fully support parallel compilation for make -jN. Setting VERBOSE=1 will replace the beautified CMake output with raw commands and their output, which can be useful for troubleshooting.

On Windows, you will need the Debug Information Access (DIA) SDK, which should be available with an MSDN subscription, in order to build Dyninst; you will not need libelf, libdwarf, binutils, or the GCC demangler. Dyninst is still built via CMake, and the NMake and Visual Studio project file generators should both work. We have not tested building Dyninst on Windows with gcc, and we do not expect this to work presently.

If you wish to import Dyninst into your own CMake projects, the export information is in CMAKE_INSTALL_PREFIX/INSTALL_CMAKE_DIR. PDF documentation is included and installed to CMAKE_INSTALL_PREFIX/INSTALL_DOC_DIR. If you update the LaTeX source documents for any manuals, “make doc” will rebuild them. Components may be built and installed individually: “make $COMPONENT” and “make $COMPONENT-install” respectively; this will appropriately respect inter-component dependencies.

FAQs of building Dyninst

  1. Q: What should I do if the build failed and showed

"/lib64/libdw.so.1: version `ELFUTILS_0.173' not found

or

error: 'dwarf_next_lines' was not declared in this scope

A: Dyninst now depends on elfutils-0.173 or later. If you are seeing above errors, it means the elfutils installed on your system is older than 0.173. We recommend that you set LIBELF_INCLUDE_DIR, LIBELF_LIBRARIES, LIBDWARF_INCLUDE_DIR, and LIBDWARF_LIBRARIES to empty, which will trigger the CMake to automatically download the correct version of elfutils. Or you can upgrade your elfutils with your system package manager.

  1. Q: Where are the dependency libraries downloaded by Dyninst?

A: After installation, Dyninst should copy all dependencies to the install location. In case where the dependencies are not copied, they can be found in the directory where you build Dyninst. For example, suppose you configure and build Dyninst at: /home/user/dyninst/build

Then elfutils, TBB, boost can be found at /home/user/dyninst/build/elfutils/, /home/user/dyninst/build/tbb/, /home/user/dyninst/build/boost/, respectively.

  1. Q: My system has pre-installed Boost, but the build failed due to that cannot find boost libraries.

A: Boost’s library naming convention is a little confusing. You probably have the non-multi-threading version installed. So your boost libraries will look like “libboost_system.so”. Dyninst links against the multi-threading version of boost, so it will needs “libboost_system-mt.so”. Note the “-mt” in the library name. There are two ways to work around:

(1) Set PATH_BOOST to empy which will trigger Dyninst to automaticall build Boost

(2) Create symbolic links from non-multi-threading ones to multi-threading ones (https://stackoverflow.com/questions/3031768/boost-thread-linking-boost-thread-vs-boost-thread-mt)

Known Issues

  • Windows 64-bit mode is not yet supported

  • Windows rewriter mode is not yet supported

  • Exceptions in relocated code will not be caught

  • Linux rewriter mode for 32-bit, statically linked binaries does not support binaries with .plt, .rel, or .rela sections.

  • Callbacks at thread or process exit that stop the process will deadlock when a SIGSEGV occurs on a thread other than the main thread of a process

  • Stackwalker is fragile on Windows

  • Parsing a binary with no functions (typically a single object file) will crash at CodeObject destruction time.