Customizing a Microsoft Auto Code Review (OACR) Project
Microsoft Auto Code Review (known by the acronym OACR) integrates PREfast for Drivers (PFD) into the WDK build environment and is available when you install the latest WDK for Windows 7. OACR automatically begins working when you open a build environment window, so you can start using OACR and PFD without any special setup.
|
Side note- the name game
When you expand the acronym OACR it should spell Microsoft Auto Code Review. For some reason, and I won’t mention names, it was inadvertently converted to Windows Auto Code Review in earlier documentation. Go figure. This oversight has been corrected and the expanded name will appear as it should in future documentation. I apologize for any confusion this mix-up might have caused. |
OACR configuration files
OACR uses two configuration files OACR.ini and OACRUser.ini to set preferences and to configure projects. Projects are your build targets, that is, a project is whatever driver or library you are building with the WDK build utility. The names of projects are determined by the directory where you are building and settings in the configuration file, OACR.ini, and by the projects.mk file. The OACRuser.ini file can be used by individuals to override the project settings in the OACR.ini configuration file. The location of the OACRUser.ini file is specified by the UserIniLocation setting in the OACR.ini file. The default setting in the WDK is as follows:
UserIniLocation=%BASEDIR%\config\
If you want to use an OACRUser.ini file, you will need to create the file and the %BASEDIR% \config directory. The file and the directory are not provided when you install the WDK. The %BASEDIR% is the root directory of your WDK installation (for example, C:\WinDDK\7600\).
OACR projects in the WDK
In the WDK, OACR is configured for two projects: WDKsamples and Root. The WDKsamples project settings are used any time you build something under the %BASEDIR% of WDK (for example, C:\WinDDK\7600\). The Root project is the default build project and is used for anything built outside of the WDK directory structure (for example, C:\myproj\src).
Creating a private project using a custom include file
You can add your own projects to the default OACR configuration file, as described in Creating or Modifying an OACR Project. However, if you want to create a private project and you don’t want to add it to the OACR.ini file, you can set up and environment variable and point to an include file. The settings in the include file are then added to OACR.ini. Wait! What about the OACRUser.ini configuration file? Why can’t you use that? Well, the OACRUser.ini file is used to override the project settings in the OACR.ini configuration file and cannot be used to add projects. Here is how you go about creating a private project.
1. Shutdown the OACR Monitor
Right click the OACR Monitor icon in the taskbar and click Close. Or type oacr stop in a build environment window. Close any build environment window you have open. You need to stop OACR and close the windows so that OACR can pick up the changes you will make in the following steps.
2. Set the environment variable OACRUserFIles
Edit the System Properties on your computer and create the OACRUserFIles environment variable. Set the variable to point to a directory where you will create and store your private OACR project configuration file.
set OACRUserFIles=c:\myOACRprojects
3. Add the #include directive to the OACR.ini file
The OACR.ini file is in the %BASEDIR%\version\bin\arch\OACR directory. Add the following line at the end of the file:
#include optional %OACRUserFiles%\oacr.include.ini
The oacr.include.ini file is optional, so OACR does not complain if it doesn’t exist.
4. Create the include file and define your OACR projects
Create the oacr.include.ini file in the %OACRUserFIles% directory. This include file is where you define your private OACR projects. For example, the following settings in the oacr.include.ini file create a project called MyProject.
; project 'myProject': the code under src; relies on %OACRUserFIles%\project.mk
[MyProject]
; WarningLocations=^%BASEDIR%\\src
WarningNumbers=<level0>;<level1>;<level2>;<level3_PFD_samples>;
ErrorNumbers=<level0>;<level1>;
; Use PFD's settings for these
PREfastOptions=/MAXPATHS=256 /STACKHOGTHRESHOLD=1024
%_PREFAST_CYCLOMATIC%=2147483647
%PREFAST_DRIVERS%=0
[MyProject:x86]
[MyProject:x86fre]
[MyProject:x86chk]
[MyProject:amd64]
[MyProject:amd64fre]
[MyProject:amd64chk]
5. Create a project.mk file in the target project directory
Just as with any new OACR project that you add to the OACR.ini file, you need to create a project.mk file and place that in the root directory of your source files. For more information, see Creating or Modifying an OACR Project . The project.mk file for MyProject, would look like this:
_project_=MyProject
6. Restart the OACR Monitor
Open a new build environment window to start OACR. You need to open a new build environment window so that your %OACRUserFIles% environment variable is used. When OACR starts up it reads the oacr.include.ini file and treats its content as if it were part of Oacr.ini.
7. Verify that your OACR project is configured correctly
In a build environment window, use the oacr checkini command to verify that your configuration files are set up correctly. You should see something similar to the following:
c:\WinDDK\7138.0.0>oacr checkini
Configuration : C:\WinDDK\7138.0.0\bin\x86\OACR\oacr.ini
Includes : C:\WinDDK\7138.0.0\bin\oacr_base.ini
C:\MyOACRProjects\oacr.include.ini
Defines : x86
Customizations: C:\WinDDK\7138.0.0\config\oacruser.ini
No problems found
Use the oacr showconfig project command to verify that OACR can successfully read your project settings.
oacr showconfig MyProject
If your project is set up correctly, OACR shows the project configuration.
Note that you can also use the OACR commands oacr stop and oacr monitor to stop and start OACR. These commands are useful if you need to make changes to fix problems in the configuration files.
8. Build your driver or library
After you have verified that your OACR project is setup correctly, you can build your driver or library just as you are accustomed to doing. You only need to open a build environment window and navigate to you build target directory. OACR will use all of your project-specific settings.
What Next?
There is a lot you can do to customize the build environment and your OACR and PFD settings. But the good news is you don’t have to. You can build your driver code just as you always have and still benefit from the integration of OACR in the WDK build environment.
To learn more, read the documentation about Microsoft Auto Code Review (OACR) and PREfast for Drivers (PFD) and check for new information in the monthly updates on MSDN. Also see the Static Driver Tools blog, it provides a wealth of information about using and customizing the static analysis tools, including PFD and Static Driver Verifier. A recent blog posting describes the steps to create a “Static Driver Verifier Prerequisites” filter. For more information, see Make Static Driver Verifier More Efficient: Add a Preset Filter to PFD/OACR Defect Viewer .
-- Dave Hagen [MSFT], Programming Writer
