DynamoRIO Option Parser

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

• Setup
• Usage
• Special Types
• Automated HTML

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:

static droption_t<unsigned int> op_x
(DROPTION_SCOPE_CLIENT, "x", 0, 0, 64, "Some param",
 "Longer desc of some param.");

static droption_t<std::string> op_y
(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());
    dr_abort();
}

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());
    dr_abort();
}

A boolean option foo can be negated on the command line using any of the following prefixes:

• -nofoo
• -no_foo
• –nofoo
• –no_foo

Option values are retrieved with get_value:

if (op_x.get_value() > 4) {
}

The value set on the command line can be overridden with the set_value function.

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.