Skip to main content

Visit Mozilla.org

Dehydra Manual

From MDC

Contents

[edit] Static Analysis With Dehydra

In order for static analysis to scale to a large codebases such as Mozilla, a separate compilation + linking approach is needed. In a typical scenario, Dehydra is invoked as a plugin for every GCC invocation. Data is saved for every file and then aggregated with another script to finalize the analysis.

[edit] GCC command-line

  • -fplugin=/path/to/gcc_dehydra.so indicates the path to the GCC plugin to load
  • -fplugin-arg=/path/to/your/script.js indicates JavaScript script to load

[edit] Callback Functions

Data is obtained from GCC through callbacks defined in the script.

Dehydra works by calling functions in your Javascript for elements of the source code file. You are not required to have any of these functions in your script: if a function is not there, Dehydra will know and will not try to call it. Furthermore, if a function is not there, then Dehydra will try to avoid computing parameters for it, speeding up the analysis. Dehydra will call the following functions:

[edit] process_type(t)

Dehydra calls this for each class/struct/enum/union definition. process_type is called after process_function is called for all the member functions. t is a Dehydra Aggregate Type object.

[edit] 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.

[edit] process_var(decl)

process_var is called for every global variable definition.

[edit] input_end()

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

[edit] Builtin functions =

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

[edit] 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()

[edit] 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.

[edit] Include Example 

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

[edit] 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.

[edit] require() Example

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

[edit] 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.

[edit] 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.

[edit] _print(msg, ...)

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

[edit] read_file(filename)

Read a file a return it as a string.

[edit] write_file(filename, data)

Write a string to a file.

[edit] Toplevel Objects

[edit] sys

this.sys is namespace for misc properties exposes by Dehydra

  • version is a GCC version string
  • 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
  • aux_base_name exposes the base filename part of the file being compiled.
Retrieved from "http://developer.mozilla.org/en/docs/Dehydra_Manual"