Dehydra Function Reference

GCC Command Line

• -fplugin=/path/to/gcc_dehydra.so
• -fplugin-arg-gcc_dehydra=/path/to/your/script.js

Callback Functions

The following functions may be provided by the analysis script and will be called by Dehydra while compiling. See the Dehydra object reference for details on the available object properties.

process_type(type)

Dehydra calls this for each class, struct, enum, union, and typedef declaration. process_type is called after process_function is called for all the member functions.

• type is a type object representing the type that was declared.

process_function(decl, body)

Dehydra calls this for each function definition (declarations without bodies are not included), including both top-level functions, class member functions, and inline class member functions.

• decl is a Variable Type object representing the function being processed
• body is an array of {loc:, statements:array of Variable Types} representing an outline of the function stripped down to variables, function calls and assignments.

process_decl(decl)

process_decl is called for every global variable, function, or template declaration.

• decl is a variable type

input_end()

Called once at the end of the C++ source file before the compiler quits. This is useful for finalizing analyses.

Builtin functions

The following functions are provided by dehydra and may be called by the user:

print(msg)

Print a string to stdout (or stderr if the compiler is piping output). If the current callback is associated with a particular location, the location will be printed first.

• msg is a string to output

To customize the location info printed set this._loc before calling print()

include(file [, namespace])

Include a javascript file into a namespace.

• file is a string representing the file to include
• Optional: namespace is an object to include the file into. The default namespace is this

The directories in sys.include_path are searched for the file, and the current working directory is searched last.

Includes are guarded so a file is only included once and subsequent include calls are ignored. This is accomplished by recording every included file into the _includedArray in the current namespace.

Include Example

include("map.js") // includes map.js into toplevel
var Map = {}
include("map.js", Map) // includes map.js into the Map object

require({version:, strict:, werror:, gczeal:})

require is used to set runtime execution flags. It also returns the current values of these flags. require supports optional named arguments via JavaScript object where each parameter is a property. If a property is not specified then it will not be passed to the runtime.

• version integer: this sets js version similar to version() in JS 1.7.
• strict boolean: Controls JS strict mode
• werror boolean: Turns JS warnings into errors
• gczeal int: This is a write-only parameter to set turn on frequent garbage collection. It is a mainly useful for debugging Dehydra for rooting bugs. gczeal is only enabled when SpiderMonkey and Dehydra are compiled with DEBUG macro defined.

require() Example

require({strict:true, gczeal:2})
if (require().werror) print("werror is set")

warning([code,] msg [, loc])

Print a warning message using the GCC warning mechanism. If -Werror is specified this will cause compilation to fail.

• Optional: code is an integer parameter that allows warnings to be enabled(-Wfoo) and disabled(-Wno-) on the GCC commandline. This parameter is used when the first argument to warning() is an integer. It is not possible to define new warnings in Dehydra, thus one has to figure out a warning code from an existing warning and hijack it for ulterior purposes.
• msg is a string to be presented as a gcc warning
• Optional: loc is the location that should be reported for the warning. If no location is provided, the location is inferred from the last process_type or process_function.

error(msg [, loc])

Print an error message using the GCC error mechanism. This will cause compilation to fail.

• msg is a string to be presented as a gcc error
• Optional: loc is the location that should be reported for the warning. If no location is provided, the location is inferred from the last process_type or process_function.

_print(msg, ...)

The low level function called by print(). It does not print the location.

read_file(filename)

Read a file a return it as a string.

write_file(filename, data)

Write a string to a file.

Builtin Objects

sys

this.sys is a container for miscellaneous properties exposes by Dehydra

• sys.gcc_version is a GCC version string
• sys.include_path exposes the search path used by include(). The default value is the following directories:
  • the directory of the dehydra script being processed
  • the libs directory next to the gcc_dehydra.so plugin
  • User script may add additional directories
• sys.aux_base_name exposes the base filename part of the file being compiled
• sys.frontend exposes the compiler frontend (e.g. "GNU C" or "GNU C++")

arguments

this.arguments is a JavaScript array containing command-line arguments passed to a script.

-fplugin-arg="foo.js a b c" would run foo.js with ["a", "b", "c"] arguments array.

This page was auto-generated because a user created a sub-page to this page.