DynamoRIO API
DynamoRIO Option Parser

The droption DynamoRIO Extension provides easy-to-use option declaration and parsing for both clients and standalone programs.

Setup

To use droption with your client simply include this line in your client's CMakeLists.txt file:

use_DynamoRIO_extension(clientname droption)

That will automatically set up the include path. Then include the header file:

#include "droption.h"

To use droption with a non-client, for example with a tool frontend or other standalone application, simply include the droption.h header file.

Usage

Simply declare a global instance of droption_t of the desired option value type for each option you wish to support. Typical value types are bool, integers, or std::string. For example:

(DROPTION_SCOPE_CLIENT, "x", 0, 0, 64, "Some param",
"Longer desc of some param.");
(DROPTION_SCOPE_CLIENT, "y", "", "Another param",
"Longer desc of another param.");
static droption_t<int> op_z
(DROPTION_SCOPE_CLIENT, "foo", 42, "Yet another param",
"Longer desc of yet another param.");

Then, ask for the droption_t instances to be filled in from the passed-in arguments from the user. In a client using dr_client_main(), or from a standalone application, invoke parse_argv():

std::string parse_err;
if (!droption_parser_t::parse_argv(DROPTION_SCOPE_CLIENT, argc, argv, &parse_err)) {
dr_fprintf(STDERR, "Usage error: %s", parse_err.c_str());
}

A standalone application should pass DROPTION_SCOPE_FRONTEND rather than DROPTION_SCOPE_CLIENT.

In a client using the legacy dr_init(), use the dr_parse_options() function:

std::string parse_err;
if (!dr_parse_options(id, &parse_err)) {
dr_fprintf(STDERR, "Usage error: %s", parse_err.c_str());
}

Special Types

droption provides some custom value types for options:

  • bytesize_t: this class provides an integer type that accepts suffixes like 'K', 'M', and 'G' when specifying sizes in units of bytes.
  • twostring_t: built-in support for a pair of strings as values.

Automated HTML

To produced automated documentation with the long-format descriptions, we recommend building a small program that looks something like this:

#include <iostream>
#include "droption.h"
#include "options.h"
int
main(int argc, const char *argv[])
{
std::cout << droption_parser_t::usage_long(DROPTION_SCOPE_ALL,
"- <b>", "</b>\n",
" <br><i>", "</i>\n",
" <br>", "\n")
<< std::endl;
return 0;
}

This program can be built and run at documentation generation time to produce HTML that can then be embedded into Doxygen or other documentation.