Share via

OACR.ini

  • Article

OACR.ini is the primary configuration file. The OACR.ini file contains the global settings and project-specific settings. You need to change these settings if you want to add or customize your own OACR projects or want to change some of the default configuration settings The location of the Oacr.ini file is in the WinDDK\version\bin\*arch\*OACR directory.

The Oacruser.ini is an optional file that you can use to customize an OACR configuration. Entries in the Oacruser.ini override the corresponding entries in Oacr.ini, except for those entries that use the addition assignment operator (+=). When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

You can also use the oacr set commands to override the some of the default configuration settings. For more information, see the Microsoft Auto Code Review (OACR) Commands.

The Oacr.ini file contains the following sections:

  • [settings] -
    Contains the global settings that apply to all projects.

  • [defaults]
    Contains the default settings that apply to projects that do not override the defaults.

  • [defaults:flavor]
    Contains the default settings that apply to a particular build flavor of projects, for example, x86, that do not override the defaults.

  • [project] and [<project:flavor] -
    Contains the project and build flavor specific settings.

  • [WarningNumbers]
    Specifies the sets of warning numbers that are used for filtering.

  • [Files]
    Specifies the sets of files that are used for filtering.

  • [ViewerFilters]
    Specifies the filter definitions for the PREfast viewer.

  • [ViewerFilterPresets]
    Specifies the filter preset definitions for the PREfast viewer.

[settings] section

The [settings] section contains global settings that apply to all projects. The following settings are supported:

  • AutoConfig
    Enables or disables auto configuration mode. This mode provides simplified build integration.

    Valid values: 0, 1

    Default: 0 (disabled)

    Example: AutoConfig=1

  • OACRToolsRoot
    Points to the root directory of the OACR tools tree on the local machine. The value can contain environment variables, enclosed in percent signs (%).

    Note   This setting is required. It can be set to an empty string, in which case the location of the Oacr.ini file is used as the value. This works, if all files of the OACR distribution are left in their original position within the OACR tree.

    Valid values: Existing location with OACR tools tree, or empty string

    Default: none

    Example: OACRToolsRoot=%OTOOLS%\bin\x86\oacr\

  • OACRBuildRoot
    Points to the root directory for the files on the local computer that are generated by OACR. The value can contain environment variables, enclosed in percent signs (%).

    Note   This setting is required. It can be set to an empty string, in which case a subdirectory build of OACRToolsRoot is used.

    Valid values: Valid location with write access (directory is created if it does not exist), or an empty string

    Default: none

    Example: OACRBuildRoot=%BUILDROOT%\oacr\

  • UserIniLocation
    Points to the location of the Oacruser.ini file, a file that can be used to customize the OACR default configuration. If UserIniLocation is set to a non-empty value, the Oacruser.ini file is searched in the specified directory only. Otherwise, the Oacruser.ini file must be in the same location as OACR.ini, for which the default search strategy is used. The value can contain environment variables, enclosed in percent signs (%). The default value in the Oacr.ini file is: Default: UserIniLocation=%BASEDIR%\config\

    Example: UserIniLocation=%BASEDIR%\config\

  • Label
    Label for the OACR instance described by the Oacr.ini file. To help distinguish between multiple OACR instances, the label is displayed in the tooltip and in the About.. dialog box for the OACR Monitor. . The value can contain environment variables, enclosed in percent sign (%).

    Valid values: Any string

    Default: %BASEDIR%

    Example: label=%BASEDIR%

  • DefaultProject
    Name of the default project. The name of the default project is used by all commands that take a project as an argument, if no project name is specified.

    Valid values: Any project name that is defined in Oacr.ini.

    Default: root

    Example: DefaultProject=root

  • DefaultFilterPreset
    Default filter preset for the PREfast viewer. The viewer is started with this preset, unless a preset is specified on the command line.

    Valid values: Any filter preset defined in the [ViewerFilterPreset] section

    Default: none (for example, all defects visible in the viewer)

    Example: DefaultFilterPreset=level1

  • BuildSleepTime
    To minimize the impact on build performance, OACR detects the build activity on the computer by looking for build related processes (see BuildTools setting). While build activity is detected, the daemon process is suspended. BuildSleepTime is the time interval (in seconds) during which there must be no (detected) build activity, before the daemon process is enabled.

    Note   Setting the build sleep time to 0 turns off build activity detection, that is, the daemon process is not suspended during builds.

    Valid values: 0..900

    Default: 40

    Example: BuildSleepTime=120

  • SnoozeTime
    Snooze mode temporarily suspends the daemon process. This can be useful during tight edit/build/debug cycles to prevent reduced machine performance by the daemon process kicking it at a bad time. SnoozeTime is the time interval (in minutes) during which the daemon process is suspended after it is put into snooze mode through the Snooze command in the taskbar applet.

    Valid values: 0 to 900

    Default: 60

    Example: SnoozeTime=30

  • BuildTools
    The list of executables that are considered build tools by the build activity detection. Running instances of these executables suspend the daemon process.

    Valid values: a semicolon (;) delimited list of executables (without path).

    Note   This setting supports addition assignment operator (+=) to add to the built-in default.

    Default: nmake.exe;build.exe;cl.exe;link.exe;lib.exe;bscmake.exe;midl.exe;rc.exe;mktyplib.exe

    Example: BuildTools+=mkword.exe;xbuild.exe

  • BuildEvent
    The name of a Win32 named event that indicates build activity. The value can contain environment variables, enclosed in percent signs (%). The existence of the event suspends the daemon process.

    Valid values: Any valid name of a Win32 event object

    Note   If the name contains a backslash (\) or semicolon (:), these characters are substituted by a period (.).

    Default: none

    Example: BuildEvent=timebuild.%SDXROOT%

  • DaemonPriority
    Priority of the daemon process.

    Note   The settings are mapped to the corresponding Win32 process priority class.

    Valid values: idle, below_normal, normal

    Default: below_normal

    Example: DaemonPriority=idle

  • DaemonDiskIdle
    Minimum percentage of disk idle that background check runs try to maintain

    Note   Setting the value to 0 turns off disk activity monitoring. Also be aware that OACR is only throttling its own activity. OACR is not able to maintain the minimum disk idle target value if other processes are generating sufficient disk activity to bring the idle percentage below the target value.

    Valid values: 0 .. 100

    Default: 50

    Example: DaemonDiskIdle=30

  • DaemonMenu
    Shows or hides the Daemon menu and other power user menu items in the taskbar applet.

    Valid values: 0, 1

    Default: 0 (i.e. menu hidden)

    Example: DaemonMenu=1

  • MonitorAutoStart
    Automatically starts the OACR monitor when the OACR build tool interceptors (oacrcl, oacrcsc, and so on.) are called for files that belong to a project for which OACR is enabled.

    Valid values: 0, 1

    Default: 1 (the OACR monitor is started automatically)

    Example: MonitorAutoStart=0

  • NumProcDaemon
    The number of child processes to be used for daemon mode check that runs when the screen saver is not active.

    Note  In automatic mode, the number of processes is dynamically adjusted based on disk load. The value 0 disables daemon mode checking, except for times when the screen saver is active. Zero is only valid if the screen saver is enabled on the machine.

    Valid values: automatic, 0 to 16

    Default: 1

    Example: NumProcDaemon=automatic

  • NumProcDaemonScreenSaver
    The number of child processes to be used for daemon mode check runs when the screen saver is active.

    Note   In automatic mode, the number of processes is dynamically adjusted based on disk load.

    Valid values: automatic, 1 to16

    Default: automatic

    Example: NumProcDaemonScreenSaver=2

  • NumProcBatch
    The number of child processes to be used for batch mode check runs.

    Note   In automatic mode, the number of processes equals the number of processors (cores) that the computer has.

    Valid values: automatic, 1 to 16

    Default: automatic

    Example: NumProcBatch=2

[defaults] section

The [defaults] section contains default settings that apply to all projects. The following settings are supported:

  • OACR
    This is the master setting that enables OACR for a project.

    Valid values: 0, 1

    Default: 0 (disabled)

    Example: OACR=1

  • DefaultFlavor
    The default build flavor. If you set a default flavor, you can call OACR without specifying a flavor. For example, you could use oacr list myproject instead of oacr list myproject debug.

    Valid values: Any build flavor that is defined for projects in Oacr.ini file.

    Default: none

    Example: DefaultFlavor=debug

  • Priority
    Specifies the project priority. Determines the sequence in which pending queues are run by the daemon process.

    Valid values: low, normal, high

    Default: normal

    Example: Priority=high

  • Platform
    Specifies the target platform for static analysis tools that are target-platform specific.

    Valid values: x86, amd64, ia64

    Default: x86

    Example: Platform=amd64

  • AutoFlavors
    Specifies the set of build flavors that are automatically generated for each project, even if the respective build flavor sections are not present for the project. This helps to keep the Oacr.ini file smaller because only the sections that override default values need to be specified.

    Valid values: A list of build flavor names. The names must be delimited with semicolons (;).

    Default: none

    Example: AutoFlavors=debug;ship

  • FilesToCheck
    Determines which of the files that are being compiled are checked.

    Valid values: all, edit, pch

    Use all for all files that are compiled.

    Use edit for writeable files (that is, files that are checked out or generated) that are compiled.

    Use pch only for precompiled headers (that is, checking for other files can be turned on without full build).

    Default: all

    Example: FilesToCheck=edit

  • CheckEditProjectsOnly
    Allows OACR to only run on projects that have files checked out.

    Valid values: 0, 1

    Default: 0 (check projects without checked out files)

    Example: CheckEditProjectsOnly=1

  • CheckWhen
    Determines when OACR checks files.

    Valid values: compile, batch, and daemon.

    compile - checks when a file is compiled.

    batch - a file is added to the queue when it is compiled and is checked in a batch run (started manually by using the oacr check command).

    daemon - a file is added to the queue when it is compiled and checked in to the low priority daemon process.

    You can override the CheckWhen setting by using the oacr set command. For example, the command oacr set compile

    Default: daemon

    Example: CheckWhen=compile

  • AutoClean
    Simplifies build integration by making the oacr clean command unnecessary. The drawback is a slight performance penalty.

    Valid values: 0, 1

    Default: 0 (no automatic clean)

    Example: AutoClean=1

  • QueueAutoSave
    Automatically saves the queue of files to be checked before starting a check run in daemon or batch mode. A saved queue allows OACR to recheck files in a project without rebuilding the project, The difference between QueueAutoSave and a manually run oacr savequeue command is that QueueAutoSave merges the files in the current queue into the files that are already in the saved queue. This happens at the same time that the oacr savequeue command overwrites the saved queue. Furthermore, in daemon mode it is difficult to manually save the queue by using the oacr savequeue command. In contrast, the QueueAutoSave configuration setting works well in daemon mode. You can delete a saved queue by using the oacr clean project /wipe command (the /wipe option is required).

    Valid values: 0, 1

    Default: 0 (the queue is not automatically saved)

    Example: QueueAutoSave=1

  • CodeScanners
    Set of enabled code scanners. The code scanner supported at this time is PREfast,

    Valid values: ';' delimited list of code scanner names.

    Default: PREfast

    Example: CodeScanners=PREfast

  • PREfastModules
    Set of enabled PREfast defect modules.

    Valid values: a list of defect module names, separated by semicolons (;)

    Default: windowsprefast;fpa;drivers;

    Example: PREfastModules= windowsprefast;fpa;drivers;

  • PREfastOptions
    Specifies additional options for PREfast.

    This setting supports the addition assignment operator '+='.

    Valid values:

    /INCREASEHEAP=size -- Default: 0

    /STACKHOGTHRESHOLD=size -- Default: 16384

    /MAXPATHS=size -- Default: 16

    /NEW_FAILURE=(never | null | throw) -- Default: never

    /MAXMEMORY=size

    /CMDPREFIX=string -- Default: empty

    /CMDPOSTFIX=string -- Default: empty

    /COMPRESSPCH[=(0|1)] -- Default: 0

    You can specify more than one option. To do this, use semicolons (;) to separate the options.

    Default: PREfastOptions=/MAXPATHS=32

    Example: PREfastOptions=/NEWFAILURE=throw;/STACKHOGTHRESHOLD=32768

    The /INCREASEHEAP option increases the memory allocation for PREfast. It is the equivalent of the /Zm compiler option. The value is the percent of the default.

    The /STACKHIGTHRESHOLD option specifies the stack size limit for warning 6262 that warns about excessive stack usage.

    The /MAXPATHS option limits the number of code paths that PREfast analyzes per function.

    The /NEW_FAILURE option specifies the failure behavior of the new operator. The options are never fails, returns null, or throws exception.

    The /MAXMEMORY option sets a memory limit for the analysis.

    The /CMDPREFIX and /CMDPOSTFIX options are inserting the specified string at the beginning or the end of the command line that is passed to PREfast parser. This can be used to pass arbitrary options to the PREfast parser.

    The /COMPRESSPCH option enables compression for precompiled headers (.pch files). This compression helps to conserve disk space for machines that are configured to check all files.

    Note   This setting supports the addition assignment operator (+=).When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

  • ScannerTimeout
    The maximum time allowed, in seconds, for the code scanner process to run. If a scanner process does not finish within the allocated time, the process is terminated, and a core warning (SCAN_FAILURE_TIMEOUT or SCAN_FAILURE_PCH_TIMEOUT) is logged.

    Valid values: 0 to 86400

    Default: 1800

    Example: ScannerTimeout=1800

  • ExcludeSourceFiles
    Specifies the files that OACR will not check, based on the full pathname of the source file. For redirected source files (see the RedirectSourceFiles setting), the full pathname of the redirection target is used.

    Note   This setting supports the addition assignment operator (+=).When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

    Valid values: same as RedirectSourceFiles

    Default: \\obj(?:dbg|chk|fre|d)?\\

    Example: ExcludeSourceFiles=\\obj(?:dbg|chk|fre|d)?\\

  • ExcludeOutputFiles
    Specifies the files that OACR will not check, based on the full pathname of the output file of the respective build tool. The files against which this filter is applied depends on the build tool that drives a code scanner. For example, PREfast is driven by the C/C++ compiler, so the filter is applied against the name of the .obj files that are generated by Cl.exe.

    Note   The ExcludeOutputFiles setting can be used for a file that is compiled multiple times (perhaps with different options). By excluding all but one of the generated object files, the source file is only checked one time (with the options used for that particular compile run).

    Note  This setting supports the addition assignment operator (+=).When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

    Valid values: same as RedirectSourceFiles

    Default: empty (no files excluded)

    Example: ExcludeOutputFiles=%BUILDROOT%\\ofc\.*\\(ofc|ofcmso|ofcmsomm)\\

  • CheckAlwaysSourceFiles
    Files must always be checked, based on the full pathname of the source file. For redirected source files (see the RedirectSourceFiles setting), the full pathname of the redirection target is used. The files described in this setting are checked regardless of their read-only state (see FilesToCheck setting) and the edit state of the project (see CheckEditProjectsOnly setting). However, the exclude filters (ExcludeSourceFiles and ExcludeObjectFiles settings) have higher precedence.

    Note   This setting supports the addition assignment operator (+=).When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

    Valid values: same as RedirectSourceFiles

    Default: empty

    Example: CheckAlwaysSourceFiles=%OFC%\\cdl\\

  • RedirectSourceFiles
    Files to be searched for source file redirection, based on the full path of the source file. The redirection is used to get the read-only mode from another file. This allows the use of generated files that are writeable (FilesToCheck=edit), by redirecting to the source file checked into the project. The redirection is specified either by using a #line directive (preferred for C/C++ source files), or a comment of the form

    The comment form allows the use of redirection to non C/C++ source files.

    This setting supports the addition assignment operator '+='.

    Valid values:

    A semicolon (;) delimited list of regular expressions and sets defined in the [Files] section (specified as <name>).

    The <all> set is a predefined set that means all files.

    Elements in the list can be negated with a leading logical negation operator (!).The first element must not be negated.

    Regular expressions can contain environment variables (specified as '%ENVVAR%').

    The list is evaluated left to right (elements can override elements further to the left).

    Default: empty (that is. no redirection)

    Example: RedirectSourceFiles=<built>

  • WarningLocations
    Warnings to be logged, based on the full pathname of the file that is referred to by the warning.

    Note   The WarningLocations setting filters against the location of the warning, while the ExcludeSourceFiles setting filters against the compilation unit. For warnings in .c or .cpp files, the location of the warning and the compilation unit are the same. However, for warnings in header files, the warning location is the header file, while the compilation unit is the .c or .cpp file that includes the header file. This means that only the WarningLocations setting can be used to filter out warnings in header files (unless the ExcludeSourceFiles filter is set up to exclude all files that include the header file).

    Note   This setting supports the addition assignment operator (+=).When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

    Valid values: same as RedirectSourceFiles

    Default: all

    Example: WarningLocations=^%MSO%\\

  • WarningNumbers
    Warnings to be logged, based on the warning number.

    Note   This setting supports the addition assignment operator (+=).When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

    Valid values:

    A list of warning numbers, delimited by semicolons (;),

    Warning number ranges (specified as from-to),

    Sets defined in the [WarningNumbers] section (specified as name).

    <all> is a predefined set meaning all warning numbers.

    Elements in the list can be negated with a leading exclamation point (!). The first element must not be negated.

    The list is evaluated left to right, that is, elements can override elements further to the left.

    Default: <level0>;<level1>;<level2>;<level3_PFD_samples>

    Example: WarningNumbers=<all>;!<level4>;5414

  • ErrorNumbers
    Specifies the warnings that are to be treated as errors. Errors break the build when the CheckWhen=compile setting is used. Errors also make the checkin test (oacr check project /cit) fail.

    Note   Errors are a subset of the warnings that are specified in WarningNumbers. Issues with warning numbers that are not in the WarningNumbers filter are not logged, and can therefore not be treated as errors.

    Note   This setting supports the addition assignment operator (+=).When the addition assignment operator is used, the values for that entry in the Oacruser.ini file are appended to the value read from the Oacr.ini file.

    Valid values: same as WarningNumbers

    Default: <level0>;<level1>

    Example: ErrorNumbers=<all>;!<level3>

[Project] and build flavor sections

The project and build flavor sections contain project-specific settings. For example, for projects with build flavors that have a debugging or a shipping version, there can be a section for the project that has settings that are shared by all flavors and a section for each build flavor. The following example shows the project-specific settings for a project called proj:

[defaults]
WarningNumbers=<all>
PREfastOptions=/INCREASEHEAP=200

[proj]
WarningLocations=^%PROJ%\\
PREfastOptions+=/STACKHOGTHRESHOLD=32768

[proj:debug]
WarningNumbers=<level0>;<level1>;<level2>

[proj:ship]
WarningNumbers=<level0>

To determine the setting for a particular project and build flavor, the sections are read in the following order:

  • [defaults] section
  • [defaults:<flavor>] section
  • [<project>] section
  • [<project>:<flavor>] section

If an entry uses the assignment operator (=), the value that was found previously is replaced. If an entry uses the addition assignment operator (+=), the value is appended to the value that was found previously. In the previous example, the ship flavor of the proj project uses WarningNumbers=<level0> and PREfastOptions=/INCREASEHEAP=200; /STACKHOGTHRESHOLD=32768.

In a project section, the same settings that are allowed in the [defaults] section are allowed.

In a build flavor section, the same settings that are allowed in the [defaults] section are allowed, except for DefaultFlavor and ProjectRoot.

[Files] section

The [Files] section contains sets of files that are used for filtering.

There are no entries with predefined names in this section.

You can add entries with names that you define yourself. You can use the entries in the RedirectSourceFiles, ExcludeSourceFiles, ExcludeObjectFiles, and WarningLocations settings in project and build flavor settings. These entries can also be used for filtering in various OACR commands by using the /warnings and /errors options.

Entries in this section can be a delimited list of regular expressions or sets of files that you have defined in this section and specified by <name>. Regular expressions can contain environment variables (specified as %ENVVAR%).

Example: atl=^.*\\(atl|atl30)\\

[ViewerFilters] section

The [ViewerFilters] section contains filter definitions for the PREfast viewer. The PREfast viewer uses a different filter engine and filter description mechanism than OACR. The entries in this section allow you to use the OACR style filters in the PREfast viewer. For information about filtering in the PREfast viewer, see Using a Preset Filter.

Note  

  • The viewer filters define the warnings to be filtered out, not the warnings to be seen in the viewer.

  • Filtering can also be done in OACR before calling the PREfast viewer, by using the /warnings and /errors option with the oacr view command

There are no entries that have predefined names in this section.

You can add entries with names that you define, as needed. The entries that you define here appear in the warning list in the PREfast viewer.

The entries that you add in this section have the following syntax:

Description string :  [ regular expressions |  <sets> from [files] setting ] | [warning # | warning # ranges | <sets> from [WarningNumbers] setting ]

Each entry has a description string, followed by a colon (:), and then a list of values that are separated by semicolons (;). The values can contain the following:

  • Regular expressions (against full pathnames of warning location files) or sets that you have defined in the [files] section and specified by name. Regular expressions can contain environment variables (specified as %ENVVAR%).

  • Warning numbers, warning number ranges, and sets from the [WarningNumbers] section.

Examples:

m3=Milestone 3 exit criteria:<m3>

util_operfmon=perfmon subproject of util:^%UTIL%\\zlib\\

level0=PREfast compile errors:<level0>

level1=OACR - Minbar zero hits:<level1>

level2=OACR - Minbar nonzero hits:<level2>

level3=OACR - Should fix:<level3>

level4=OACR - Off by default:<level4>

testcode=Windows Test Code ( contact tqi ):<testcode>

winpft=winpft:<winpft>

[ViewerFilterPresets] section

The [ViewerFilterPresets] section contains filter preset definitions for the PREfast viewer.

Note   The viewer filters define the warnings to be filtered out, not the warnings to be seen in the viewer. Therefore, inverting the filter by using the logical negation operator (!) is often needed to get the expected result. Unfortunately, this is only supported for warning number filters, and not for warning location filters.

There are no entries that have predefined names in this section.

You can add entries with names that you define, as needed. The entries that you define here appear in the Presets list in the PREfast viewer.

The entries that you add in this section have the following syntax:

Each entry has a description string, followed by a colon (:), followed by a semicolon (;) separated list of warning numbers, warning number ranges, or entries from the [ViewerFilters] section (for example, <level1). For warning number filters, the whole preset can be negated with a leading logical negation operator and semicolon (!;), or just (!), if there is only one element.

Examples:

m3=Milestone 3 exit criteria: !<m3>

level0=compile errors:!<level0>

level1=OACR level 1 (Minbar zero hits):!<level1>

level2=OACR level 2 (Minbar nonzero hits):!<level2>

level3=OACR level 3 (should fix):!<level3>

level4=OACR level 4 (off by default):!<level4>

testcode=Windows Test Code ( contact tqi ):!<testcode>

winpft=winpft:!<winpft>

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011