To use the DynamoRIO API, a tool, or "client" of DynamoRIO, should include the main DynamoRIO header file:
The client's target operating system and architecture must be specified by setting pre-processor defines before including the DynamoRIO header files. The appropriate library must then be linked with. The define choices are:
LINUX, or (coming soon)
Currently we provide a private loader for both Windows and Linux. With private loading, clients use a separate copy of each library from any copy used by the application.
If the private loader is deliberately disabled, for transparency reasons (see Client Transparency), clients should be self-contained and should not share libraries with the application. Without the private loader, 64-bit clients must take care to try and load themselves within reachable range of DynamoRIO's code caches by setting a preferred base address, although this may not always be honored by the system loader.
The DynamoRIO release supplies CMake configuration files to facilitate building clients with the proper compiler and linker flags. CMake is a cross-platform build system that generates Makefiles or other development system project files. A
DynamoRIOConfig.cmake configuration file, along with supporting files, is distributed in the
CMakeLists.txt file, a client should first invoke a
find_package(DynamoRIO) command. This can optionally take a version parameter. This adds DynamoRIO as an imported target. If found, the client should then invoke the
configure_DynamoRIO_client() function in order to configure build settings. Here is an example:
samples/CMakeLists.txt file in the release package serves as another example. The top of
DynamoRIOConfig.cmake contains detailed instructions as well.
When configuring, the
DynamoRIO_DIR CMake variable can be passed in to identify the directory that contains the
DynamoRIOConfig.cmake file. For example:
The compiler needs to be configured prior to invoking cmake. If using gcc with a non-default target platform, the
CXXFLAGS environment variables should be set prior to invoking cmake. For example, to configure a 32-bit client when gcc's default is 64-bit:
CXXFLAGS should be set instead for a C++ client, and both should be set when building both types of clients from the same configuration (e.g.,
To improve clean call performance (see Clean Calls and -opt_cleancall), we recommend high levels of optimization when building a client.
If a client is not using CMake, the appropriate compiler and linker flags can be gleaned from
DynamoRIOConfig.cmake. One method is to invoke CMake to generate a Makefile and then build with
VERBOSE=1. We also summarize here the key flags required for 32-bit clients for
For a 64-bit client with
For 64-bit Linux clients, setting the preferred base takes several steps. Refer to
DynamoRIOConfig.cmake for details.
To make clean call sequences more likely to be optimized, it is recommended to compile the client with optimizations,
-O2 for gcc or
/O2 for cl.