-
Notifications
You must be signed in to change notification settings - Fork 1
Command Line Options
--assembly-name=assembly
Specify the name of the assembly to be instrumented. If not specified, the assembly name will be inferred as the name of the provided assembly, preceding any extension. Thus this flag is is only necessary if the program's executable has an unusual name.
--save-program=filename
Instead of executing the assembly, save it as filename, or InstrumentedProgram.exe if filename is not supplied. This new program can then be executed, and will write its output as normal. This is necessary for class libraries and testing. It's also useful for debugging purposes, to examine the program with all instrumentation calls inserted, or to verify the bytecode.
--save-and-run
When supplied with --save-program or --wpf, will execute the program immediately after rewriting, with the user provided arguments. This is done just as it would be if the program were run in [GettingStarted#Online_Tracing online-mode]. This option has no effect if neither --save-program or --wpf are provided. It should not be used on a class library, since a class library has no !EntryPoint. This flag is false by default
--wpf
Similar to the --save-program argument, except the output program is saved over the input program. This is useful for WPF programs, and any others that requires assembly resources to have specific names. The existing input program will be saved to a new location in the same folder with .bak added at the end of its filename. Will override --save-program if both are supplied. This flag is false be default.
--portable-dll When supplied, specifies the use of a custom metadata host instead of the default one. This flag is only necessary if the source program was built with a system library other than .NET, for example Portable .NET.
This section lists options that affect which program points appear in Celeriac Output.
--ppt-omit-pattern=regexp
Do not produce data trace output for classes/procedures/program points whose names match the given regular expression. This reduces the size of the data trace file and also may make the instrumented program run faster, since it need not output those variables.
For example the following flag:
--ppt-omit-pattern="MyInteger..ctor()"
would tell Celeriac to not output any program points (either entrances or exits) for the MyInteger constructor.
This option works just like --ppt-select-pattern does, except that matching program points are excluded, not included.
Omit takes precedence over select.
--ppt-select-pattern=regexp
Only produce trace output for classes/procedures/program points whose names match the given regular expression. This option may be supplied multiple times, and may be used in conjunction with --ppt-omit-pattern.
When this switch is supplied, filtering occurs in the following way: for each program point, Celeriac checks the fully qualified class name, the method name, and the program point name against each regexp that was supplied. If any of these match, then the program point is included in the instrumentation.
Suppose that method bar is defined only in class C. To trace only bar, you could match the method name by providing the following flag:
--ppt-select-pattern="C.bar"
--sample-start=sample-cnt When this option is supplied, Celeriac will record each program point until that program point has been executed sample-cnt times. Celeriac will then begin sampling. Sampling starts at 10% and decreases by a factor of sample-cnt each time another sample-cnt samples have been recorded. If sample-cnt is 0, then all calls will be recorded. The execution counts are unique to each app domain.
This section lists options that affect which variables appear in Celeriac Output
--arrays-only=true|false
Determines whether variables that implement IList should be treated as arrays for purposes of instrumentaion. This will affect whether the variable's elements are inspected, e.g. a[0], ..., a[n]. True by default.
--linked-lists=true|false
This boolean option (default: true) causes user-defined linked lists to be output as sequences, much like C#’s List’s and arrays are. A user-defined data structure is considered to be a linked list if it has one instance field that is of its own type. Supplying this option will cause Celeriac to fail (by running forever) if any linked list contains a cycle.
--nesting-depth=n
Depth to which to examine structure components (default 2). This parameter determines which variables Celeriac outputs at runtime. A field, parameter, or other instrumented variable (and its elements if it's a list) are considered depth 0, their identities will always be printed. Their children are depth 1, the children's children depth 2, etc. For instance, suppose that a program contained the following data structures and variables:
class A {
int x;
B b;
}
class B {
int y;
int z;
}
A myA;
class Link {
int val;
Link next;
}
Link myList;
If depth=0, only the identities (hashcodes) of myA and myList would be examined; those variables could be determined to be equal or not equal to other variables.
If depth=1, then also MyA.b, myList.next, and the integers myA.x and myList.val would be examined.
If depth=2, then also MyA.b.y, MyA.b.y, myList.next.next, and myList.next.val would be examined.
Variables whose value is undefined are not examined. For instance, if myA is null on a particular execution of a program point, then myA.b is not accessed on that execution regardless of the depth parameter. That variable appears in the .dtrace file, but its value is marked as nonsensical.
--omit-dec-type=regex
Do not include variables whose dec-type matches the regular expression. Expressions will be omitted from each program point in which they appear.
--omit-parent-dec-type=regex
Do not include expressions whose parent's dec-type matches the regular expression. Expressions will be omitted from each program point in which they appear.
--omit-var=regex
Do not include expressions whose name matches the regular expression. Expressions will be omitted from each program point in which they appear.
--purity-file=pure-methods-file
File pure-methods-file lists the pure methods (sometimes called observer methods) in a .NET program. Pure methods have no externally-visible side effects, such as setting variables or producing output. For example, most implementations of the GetHashCode(), ToString(), and Equals() methods are pure, as are automatically generated getters.
For each variable, Celeriac adds to the trace new "fields" that represent invoking each pure method on the variable. (Obviously this mechanism is only useful for methods that return a value: a pure method that returns no value does nothing!)
Here is an example:
class Point {
private int x, y;
public int RadiusSquared() {
return x*x + y*y;
}
}
If RadiusSquared() has been specified as pure, then for each point p, Celeriac will output the variables p.x, p.y, and p.RadiusSquared(). Use of pure methods can improve the Daikon output, since they represent information that the programmer considered important but that is not necessarily stored in a variable.
Invoking a pure method at any time in an application should not change the application's behavior. If a non-pure method is listed in a purity file, then application behavior can change. Celeriac does not verify the purity of methods listed in the purity file.
The purity file lists a set of methods, one per line. The format of each method is given as follows:
[AssemblyQualifiedName];[MethodName]
For example:
PureMethods.A, PureMethods, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null;PureMethod1
Pure methods must either take no parameters, or be static and take a single parameter of the same type as the containing class. Suppose for example the String.IsNullOrEmpty(str) method is marked as pure. Then, for all String objects the IsNullOrEmpty function will be called, with the String object as the parameter.
By convention, pure-methods-file has the suffix .pure.
--std-visibility
When this switch is provided, Celeriac will traverse exactly those fields that are visible from a given program point. For instance, only the public fields of class pack1.B will be included at a program point for class pack2.A whether or not pack1.B is instrumented. By default, Celeriac outputs all fields in instrumented classes (even those that would not be accessible in C# code at the given program point) and outputs no fields from uninstrumented classes (even those that are accessible).
This section describes command-line options for controlling metadata that is output for each variable. The metadata is used by Daikon to suppress non-informative contracts, and to facilitate C# Code Contract formatting.
--comparability=filename
When specified, Celeriac will write (if no filename is provided) or use a comparability file to determine variable comparability during declaration printing. This provides more information in the trace files, which Daikon uses when determining invariants. Specifically, it will limit output invariants to those containing expressions that were actually used together. This helps reduce the number of false invariants Daikon guesses. The --generate-comparability flag can be used to generate a comparability file.
--enum-underlying-values
Instead of printing the string representation of an enum's value, the underlying integral-type value is printed. This enables comparisons between the enumeration values.
--is-enum-flags
When this flag is provided, Celeriac will mark variables that have an enum type. Daikon uses this information to suppress obvious facts about enumerations (e.g., nullness).
--is-readonly-flags
When this flag is provided, Celeriac will mark variables that are read-only. Daikon uses this information to suppress invariants stating that variable has not changed. Note: fields that that marked as readonly in a program may not be readonly for the purposes of Daikon. For reference types, all parent expressions must be read-only. For value types, the type must be immutable, and all parent expressions must be read-only.
--is-property-flags
When this flag is provided, Celeriac will mark properties with the flag is_property. The C# Code Contract format in the Daikon uses this information to correctly format expressions involving properties.
Use of this flag requires still that the properties be specified in a purity file found with the --purity-file argument.
--simple-names
If provided, Celeriac will output unqualified names for declared types (dec-types) and type strings in the trace. This flag is currently enabled for C# (see below).
--source-language=CLR|CSharp|VBasic|FSharp
The name-style to use for declared types (dec-types) and type strings in the trace. CLR (and reflection-style names) is used by default. Note that Daikon has some hard-coded type names such as java.lang.String that have a special meaning. These special names will be output regardless of the source language; the C# format for Daikon converts the Daikon-name back into C#.
This section lists all other Celeriac options - that is, all options that do not control which program points and variables appear in Celeriac's output.
--dtrace-append
Instead of deleting the existing dtrace file, append the results of this run to the end of the existing file, if any.
--force-unix-newline
Always use the UNIX newline character. If not specified the OS default newline character will be used. This is necessary for passing the unit tests if they are run from a Windows machine, because otherwise the line endings in the generated dtrace files wouldn't match the expected test results.
--output-location=filename
Specifies the location for the trace output (.dtrace) file. If this is not specified, then the default value of daikon-output/PROGRAMNAME.dtrace is used
--robust-mode
During program execution output nonsensical as the variable value instead of crashing if there's an exception during variable visiting. May limit the usefulness of resulting Daikon output.
--verbose=true|false
Determines whether to include debugging and progress information in the STDOUT output, false by default.
--vs-flags
For convenience when using the the Visual Studio add-in. Sets comparability, is_readonly_flags, is_enum_flags, std_visibility, and is_property_flags.
--link-object-invariants
Link all expressions to an object invariant PPT for their type (even those not in the assembly). This causes Daikon to hoist common invariants to the object instead of repeating them at each program point that references the type.
This section lists all other the options for Celeriac program analysis. All these options switch Celeriac to offline mode. They all produce produce a file that can be used in the normal running of Celeriac.
--auto-detect-pure
When specified Celeriac will run in offline mode. During rewriting it will detect properties that are pure and construct a purity file containing all such properties. The resulting file will be named !ProgramName_auto.pure.
--emit-nullary-info
When specified Celeriac will write to STDOUT the qualified types and method names for nullary (0-argument) methods reachable from the assembly. This can be useful for builing a purity file.
--purity-prefix-blacklist=file
Must be used with the emit-nullary-info option. Celeriac loads the file at file and processes each line in the file, treating it as a prefix to ignore when computing the list of nullary methods.
--generate-comparability
When specified Celeriac, will run in offline mode and output a file containing comparability information, which can then be used with the comparability flag].