Share via

Microsoft Auto Code Review (OACR) Commands

  • Article

Microsoft Auto Code Review (OACR) provides a set of commands that you can use to configure, control, and troubleshoot OACR operation. OACR is integrated into the WDK Build environment so you can enter the OACR commands directly into a Build environment window. While the OACR Monitor is the most convenient way to use the code review features, the OACR command options are useful if you prefer the command line, or to troubleshoot or help set up your environment and projects.

oacr [command ][option] | [/? | help | help command]

  • oacr bucketdiff warningLog1 warningLog2
    The oacr bucketdiff command finds the difference between two warning logs. The parameters warningLog1 and warningLog2 specify the names of the warning log files to compare. You can also use the name of a project, if you use the name of the actual warning log file as the other parameter.

    The oacr bucketdiff command compares two warning logs. The oacr diff and oacr bucketdiff commands use different compare algorithms:

    • The oacr diff command compares the warnings directly and differentiates based on warning attributes (file, function, line, warning number, and so on). The oacr diff command reports individual warnings that are different.

    • The oacr bucketdiff command groups the warnings into buckets, and compares the warning counts for the buckets. A bucket is identified by file, function, and warning number. This command reports buckets that have different warning counts.

    The oacr bucketdiff command is more resilient to source code changes than the oacr diff command, because it only counts the warnings within a function, without trying to match them. However, there are still code changes that result in false positives, for example, when you rename a function or move it to another file. Furthermore, the oacr bucketdiff command does not identify the actual warnings that have been introduced or removed. It just identifies the function in which the change has occurred.

    The /warnings and /errors options apply filters to the warning log. For more information, see Using the /warnings and /errors Options in OACR Commands and Specifying Warning Logs in OACR Commands.

    The /increase option limits the output to buckets for which the warning count has increased.

    The /decrease option limits the output to buckets for which the warning count has decreased.

    The /raw option produces output in tab delimited format.

    The /count option reports the sum of all bucket warning count differences. The sum is also returned through the return code.

    For an alternate way to compare warning logs, see the oacr diff command later in this topic.

  • oacr check project
    The oacr check command checks the scheduled files in a batch run.

    The /numproc option specifies the number of child processes to use. By default, the number of processors in the system is used.

    The /keepqueue option keeps the files in the queue after they have been checked. This allows you to repeat the run without building first. Also see the oacr savequeue command if you are interested in using queues.

    The /ignorebuildtime option checks the files that have been touched after they were added to the queue during the build. Usually, these files are not checked, because they have not yet been built after the last modification.

    The /files option applies filters to the files in the queue.

    For more information, see Using the /warnings and /errors Options in OACR Commands.

    The /batch option ignores pending daemon mode queues and only uses queues that would not be checked automatically in the background eventually.

  • oacr checkini [/strict]
    The oacr checkini [/strict] command checks the OACR configuration files and reports problems. The /strict option enables additional checks for inconsistencies. The command examines the Oacr.ini and Oacruser.ini files.

  • oacr checkinstallation [/strict]
    The oacr checkinstallation [/strict] command reports problems with the installation of OACR, such as, version conflicts, missing files, or obsolete files.

  • oacr checkintest project [ /continue ] [ /details ] [ /query ]
    The oacr checkintest command checks project for error-level defects.The oacr checkintest runs a check-in test on the project. This test determines whether there are any error-level defects. Files that are in the pending queue are checked as necessary. If the project is configured in OACR.ini to only run on files that are checked out (that is, files that can be written to), only errors in those files are considered, even if there are local customizations (in the OACRuser.ini or oacr set commands).

  • oacr clean project [ /wipe ] [ /files filter ] [ /warnings filter ] [ /useenv ] [ /ignoreunknown ]
    The oacr clean command deletes project-specific OACR files.

    Use the oacr clean command before you start a full build of a project.

    The /wipe option deletes additional files that should typically not be deleted before a full build, for example, a saved queue and precompiled header information that allows recovery from missing .pch files.

    The /files option only deletes state of source files that match the filter.

    The /warnings option only deletes state of source files with warnings that match the filter. For more information about filters, see Using the /warnings and /errors Options in OACR Commands.

    The /all option also cleans global log files.

    The /useenv option uses the current configuration in the environment.

    The /ignoreunknown option suppresses a warning for an unknown project name.

    For information about how to specify a project, type oacr help project.

  • oacr config [ project ] [ /ignoreunknown ]
    The oacr config command configures OACR for a project.

    Use the oacr config command before you start a build of a project. The oacr config command sets the active project for subsequent builds.

    The /ignoreunknown option suppresses a warning for an unknown project name.

    The oacr config command does not support all or last projects.

    For information about how to specify a project, see Specifying Projects in OACR Commands.

  • oacr convertqueue project [ /daemon | /batch ]
    The oacr convertqueue command toggles a queue between Batch and BatchOrDaemon mode. A queue is the list of files that are scheduled to be checked.

    A queue in Batch mode can only be run with the check command. In Batch mode, it is not run by the daemon process. A queue in BatchOrDaemon mode can be run either way. The mode of a queue is determined from the project configuration when the queue is created.

    The /daemon option sets the queue to BatchOrDaemon mode.

    The /batch option sets the queue is set to Batch mode.

    When no option is specified, the queue mode is set so that the queue toggles between BatchOrDaemon and Batch modes.

  • oacr count warningLog [ /warnings filter | /errors filter ] [ /nozero ] [ /nosubprojects ] [ /noremovedups ]
    The oacr count counts warnings in warning logs.

    The /warnings and /errors options apply filters to the warning log. For more information about filters and warning logs, see Using the /warnings and /errors Options in OACR Commands and Specifying Warning Logs in OACR Commands.

    The /nozero option suppresses output for projects with a zero count.

    The /nosubprojects option combines the counts of subprojects into a single count. OACR does not provide a general mechanism to define subprojects. In this context an underscore (_) character in the project name is considered a subproject name separator (for example, misc_foo, misc_bar).

    The /noremovedups option suppresses the removal of duplicate warnings. This makes the command significantly faster for large warning logs. Be aware, however, that the warning count total might include duplicate warnings.

    The command also returns the number of warnings in its return code.

  • oacr diff warningLog warningLog [ /warnings filter | /errors filter ] [ /reverse ] [ /both ] [ /list [ /source ] ] [ /view [ /filterpreset preset ] ] [ /showstats [ /nofiles ] [ /nolevels ] [ /raw ] ] [ /title ] [ /export outFile [ **;**outFile ] ]
    The oacr diff command finds the difference between two warning logs.

    One of the logs must be specified as a file. The other one can be specified as a file or a project name.

    When no options are specified, the oacr diff command shows the warning counts for both logs, and the number of warnings that appear in the first but not in the second log (log1-log2). Additionally, the command shows the warnings that appear in the second but not the first log (log2-log1).

    The /warnings and**/errors** options apply filters to the warning log. . For more information about filters and warning logs, see Using the /warnings and /errors Options in OACR Commands and Specifying Warning Logs in OACR Commands.

    When you use the /reverse option, the /list, /view, /showstats, and /export option work on log2-log1. By default, the options work on log1-log2.

    When you use the /both option, the /list, /showstats, and /export options run their command twice, first for log1-log2, then for log2-log1. If you use the /both option, the /export option requires two output files, separated by a semicolon (;).

    The /list option runs the list command on the warnings in one log, but not the other.

    The /view option runs the view command on the warnings in one log but not the other.

    The /showstats option runs the oacr showstats command on the warnings in one log but not the other.

    The /export option runs the export command on the warnings in one log but not the other. Two output files need to be specified, if the /both option is used. For more information, see the oacr export command.

  • oacr env
    The oacr env command can be used to create a batch file that sets up the environment for the current project configuration. This is useful in build environments with repeat functionality, to ensure that the repeat build uses the same configuration as the original build.

  • oacr export warningLog outFile
    The oacr export command creates a file with the warning information in a format that can be used by a number of other commands, or that can be archived, or distributed. The output file can be used as input for warning log commands. The /warnings and /errors options apply filters to the warning log. For more information, see Using the /warnings and /errors Options in OACR Commands and Specifying Warning Logs in OACR Commands

    The /source option adds the source code lines with the warnings to the exported warning log.

    The /normalizepath option uses project root and path substitution information to generate machine independent path names. This allows you to compare warning logs that are generated on different machines with different enlistment roots.

  • oacr invalidate project
    The oacr invalidate command invalidates the warning log of a project. This removes stale warnings from compilation units that had their OACR state deleted manually. An example of this would be a build environment that deletes some OACR files (for example, the .xml files that OACR places next to each .obj file) without telling OACR about it (for example, through a oacr clean call). After calling oacr invalidate for a project, OACR refreshes its cached state before using it again.

    The /useenv option uses the current configuration in the environment.

    The /ignoreunknown option suppresses a warning for an unknown project name.

    The /autocleanroot option runs a clean command on the project, if the current directory is the same as the project root.

    The /autocleanwarnings option deletes warnings from compilation units that have missing or outdated .obj files or missing warning log files (*.xml).

    The /autocleanqueue option deletes compilation units in a pending queue, if the source file or .obj file is missing.

  • oacr log [ /errors ] [ /warnings ] [ /notes ] [ /asserts ] [ /count ]oacr log project
    The oacr log command shows summary of OACR activity, such as when the OACR monitor was started or stopped, or when configuration files were loaded.

    When you specify a project name, the check run log of that project is shown. This is the output that is generated during check runs in Batch or Daemon mode.

    Without a project name, the summary log is shown. The output can be filtered with the following options:

    /errors: Show errors only

    /warnings: Show warnings only

    /notes: Show notes only

    /asserts: Show assertions only

The options can be combined to show log entries of multiple types.

The /count option reports the sum of errors, warnings, notes, and asserts listed. The sum is also returned through the return code.

oacr list warningLog [ /warnings filter | /errors filter ] [ /source ] [ /raw ]

The oacr list lists a warning log.

The /warnings and /errors options apply filters to the warning log.

The /source option lists the source code lines with the warnings.

The /raw option produces output in tab delimited format.

For more information, see Using the /warnings and /errors Options in OACR Commands and Specifying Warning Logs in OACR Commands.

oacr listcompunits project [ /warnings filter ]

The oacr listcompunits command lists compilation units for the warning log.

This command lists the full path names of the compilation units that are generating the specified warnings. This is useful for warnings in header files, because the warning location (for example, the .h file) and the compilation unit (for example, the .cpp file) are not the same file.

The /warnings option apply filters to the warning log. The following example shows the command output for the WDKSamples:x86fre project. In this instance, the Driver.c file generated the warnings.

C:\WinDDK\7600\>oacr listcompunits WDKSamples:x86fre

Compilation units
-----------------

Project: WDKSamples:x86fre

c:\winddk\7600\tools\pfd\samples\fail_drivers\fail_driver1\driver.c

oacr lock command { argument }

The oacr lock command synchronizes build and daemon processes for individual files.

Use the oacr lock command to protect all files from being opened by the daemon process during the execution of the specified command and argument..

If a build tries to get write access to a generated file while the daemon process has the file open, this command will prevent a broken build. No synchronization is needed for files that are not generated by the build.

oacr lockfile file command { argument }

The oacr lockfile command synchronizes build and daemon processes for an individual file.

Use the oacr lockfile command to protect the specified file from being opened by the daemon process during the execution of the specified command and argument..

If a build tries to get write access to a generated file while the daemon process has the file open, this command will prevent a broken build. No synchronization is needed for files that are not generated by the build.

oacr monitor

The oacr monitor command starts the OACR Monitor.

The OACR monitor is started automatically by a build when a queue that can be run by the daemon is created. You can use the oacr monitor command to start the monitor manually.

oacr recheck project [/numproc num] [ /keepqueue ] [ /ignorebuildtime ] [ /incremental ] [ /files filter ] [ /warnings filter ] [ /modified ] [ /nopch ]

The oacr recheck command runs a check of all scheduled files from the backup copy of a queue. The oacr recheck command runs a oacr restorequeue command, followed by a oacr check command.

oacr restorequeue project [ /daemon | /batch ] [ /files filter ] [ /warnings filter ] [ /modified ] [ /touch ] [ /nopch ]

The oacr restorequeue command restores a project queue from a backup copy. A queue is the list of files that are scheduled to be checked.

A saved queue allows multiple check runs on a project, without multiple builds. Be aware, that editing a source file invalidates its entry in the queue.

Use the /daemon option to set the queue into BatchOrDaemon mode.

Use the /batch option to set the queue into Batch mode.

For information about queue modes, see the oacr convertqueue command earlier in this topic.

The /files and /warnings options apply filters to the files in the queue. For more information about these options, see Using the /warnings and /errors Options in OACR Commands.

The /modified option removes files that have not been touched since the last check that found warnings or errors.

The /touch option sets the compile time for all entries to the current system time, so that the respective source files will be checked, even if they have been modified after being added to the queue.

The /nopch option uses the existing precompiled headers. By default, all precompiled headers that are used by the files in the queue will be regenerated and checked.

Use the oacr savequeue command to save a queue.

oacr running [ /monitor ] [ /daemon ] [ /viewer ] [ /session ] [ /config ]

This command determines which OACR tools are running.

The /monitor option lists the running state of the OACR monitor.

The /daemon option lists the running state of the daemon process.

The /viewer option lists the running state of the viewer.

When no options are specified, the state of all OACR tools is listed.

The oacr running command works on all instances of the viewer running on the system.

By default, this command works on all instances of the monitor and daemon that are using the same executable.

The /session option limits it to the monitor and daemon instances in this terminal server session. The /config option limits it to the monitor and daemon instances that are using the same Oacr.ini file.

This command is primarily intended for scripting. The return code is 1, if at least one of the specified tools is running and 0 otherwise.

oacr savequeue project [/merge ]

The oacr savequeue command creates a backup copy of a project queue.

A queue is the list of files that are scheduled to be checked.

A saved queue allows multiple checks on a project, without builds.

Be aware that editing a source file invalidates its entry in the queue.

The /merge option merges the entries in the queue into an existing saved queue (if any).

Use the oacr restorequeue command to restore a saved queue.

oacr set [ clean ] [ on | off ] [ all | edit | pch ] [ compile | batch | daemon | compile+batch | compile+daemon ] [ open ] [ nocit ] [fullcit ] [ nomodalmsg ] [ useenv ] [ metrics ] [ metricslite ] [ metricsultralite ] [ timings ] [ traceintercepts ] [ fakebuild ] [ pftbugreport ] [ pftsyntaxcheck | pftastsyntaxcheck ] [ noscanlocfilter ] [ noscannumfilter ] [ noscanfilter ] [ nopostlocfilter ] [ nopostnumfilter ] [ nopostfilter ] [ nopftsuppress ] [ togglesuppress ] [ verbose ] [ verbosescan ] [ debug ] [ debugattach ] [ asserts ]

This command overrides the settings from the project configuration file (Oacr.ini, Oacruser.ini)

When you use the oacr set command without arguments, the command shows the current overrides.

The oacr set clean command clears all overrides.

OACR master options:

  • oacr set on Turns OACR on.
  • oacr set off Turns OACR off

OACR options to show or clear override settings:

  • oacr set clean Clears all override settings.
  • oacr set Shows current override settings.

Files to be checked:

  • oacr set all All compiled files.
  • oacr set edit Writeable, compiled files.

When to check files:

  • oacr set compile At compile time.
  • oacr set batch In batch run.
  • oacr set daemon In background process.

Other options:

  • oacr set open Bypass the source depot check and assume that at least one file is checked out.
  • oacr set nomodalmsg Disable modal message boxes in monitor (global option).
  • useenv Preserve previous overrides.

Expert modes:

  • oacr set timings Collect compile and check timings (global option).

  • oacr set traceintercepts Collect data on build tool interception (global option).

  • oacr set pftbugreport Assist in reporting PREfast problems (global option).

  • oacr set nopftsuppress Disable OACR macros to suppress/disable warnings (global option).

  • oacr set verbose Very verbose log output (global option).

  • oacr set verbosescan Verbose code scanner related output (global option).

  • Local settings only affect OACR processes started from the command shell in which the settings were made. Global options affect all OACR processes.

  • Use an exclamation mark as a prefix (!) to reverse the effect of an option. For example, use oacr set !verbose to turn off verbose mode.

oacr showconfig project [ /useenv ] [ /nocustomizations ]

Shows project configuration information.

The /useenv option uses the current configuration in the environment.

The /nocustomizations option ignores local customizations (in the Oacruser.ini file or oacr set commands).

For more information, see Specifying Projects in OACR Commands.

oacr showini [ /projects ] [ /filters ] [ /all ] [ /raw ]

Shows a summary of the Oacr.ini and Oacruser.ini configuration files.

The /projects option shows a list of all project names, and the flavors of each project.

The /filters option shows a list of all warning numbers sets, warning location sets, and viewer filter presets, which can be used for warning filtering.

The /all option is the same as combining /projects and /filters.

The /raw option shows all settings that are sorted by section.

oacr showqueue project [ /details ] [ /raw ]

A queue is the list of files that are scheduled to be checked.

The oacr showqueue command shows a summary of the information in the queue, which includes the files to be checked.

The /details switch shows more detailed information, for example, precompiled headers and the build output files that are associated with source files.

The /raw option suppresses header and footer lines.

For more information, see Specifying Projects in OACR Commands.

oacr showstats warningLog

The oacr showstats command shows the warning log statistics.

The /warnings and /errors options apply filters to the warning log.

The /nofiles option suppresses the list of warning counts by file.

The /nolevels option suppresses the list of warning counts by warning level.

The /raw option produces a list of warning counts by warning number.

The /title option produces a list of warning counts in a format that is suitable for use as bug titles.

The /noremovedups option suppresses the removal of duplicate warnings. This option makes the oacr showstats command significantly faster for large warning logs. Be aware, however, that the warning counts might include duplicate warnings.

By default, the oacr showstats command displays a maximum of 80 characters per line. Use the /wide option if the output lines are longer.

For more information, see Using the /warnings and /errors Options in OACR Commands and Specifying Warning Logs in OACR Commands

oacr status [ project ] [ /nodetails ]

The oacr status command show status information for the specified project. If project is not specified, the command shows the status information on all projects.

The /nodetails option suppresses the warning and file counts.

For more information, see Specifying Projects in OACR Commands

oacr stop [ /monitor ] [ /daemon ] [ /viewer ] [ /all ]

This command stops the specified tool(s).

The /monitor option closes the OACR monitor. This option also stops the OACR daemon process..

The /daemon option stops the OACR daemon process.

The /viewer option closes all instances of the viewer.

If no tools are specified or if you use the /all option, the monitor, the daemon process, and viewer instances are stopped.

This command works on all instances of the viewer that are running on the system. By default, it works on all instances of the monitor and daemon that are using the same executable. The /session option limits it to the monitor and daemon instances in this terminal server session. The /config switch limits it to the monitor and daemon instances that are using the same Oacr.ini file.

oacr status [ project ] [ /nodetails ]

The oacr status command shows status information for the specified project. If project is not specified, the command shows the status information on all projects.

For more information, see Specifying Projects in OACR Commands.

The /nodetails option suppresses the warning and file counts.

oacr version

The oacr version command shows the OACR version information.

oacr view warningLog [ /warnings filters | /errors filter ] [ /filterpreset preset ]

The oacr view command runs the viewer on a warning log.

The /warnings and /errors options apply filters to the warning log. For more information, see Using the /warnings and /errors Options in OACR Commands and Specifying Warning Logs in OACR Commands. For information about the Viewer and using Prefast for Drivers (PFD), see Interpreting the Defect Log.

The /filterpreset option selects the initial preset in the viewer.

Use the oacr showini /filters command to display a list of available filter presets.

oacr wipe

The oacr wipe deletes all OACR state information. The oacr wipe command is more thorough than the oacr clean /all command.

The oacr wipe command only affects the current OACR instance. The OACR state of other instances, that is, in other WDK build environment windows, is not deleted.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011