<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html><head>
<title>Customizing CodeScanner Rules</title>
<link rel="StyleSheet" href="../book.css" type="text/css"/>
<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
</head>
<body>
<div class="Head1">
<h2>Customizing CodeScanner Rules</h2>
</div>
<p> The CodeScanner command line tool currently accepts an XML configuration file, which controls scanning behavior, like the file types to ignore and which rules to apply. Using the elements contained here makes it possible to customize the scanning rules to include new rules unique to your development environment.</p>
<p>This page describes the format of CodeScanner config file (<span class="code">codescannerconfig.xml</span>), which is used for the following purposes: </p>
<ul>
<li>Controls scanning behavior of the CodeScanner command line tool</li>
<li> Importing/exporting rules and file types from CodeScanner preference pages in Carbide.c++ IDE </li>
</ul>
<h2>CODESCANNERCONFIG.XML File</h2>
<p>The CodeScanner config file is an XML formatted file created by CodeScanner when a scan is performed or when the CodeScaner preference settings are <a href="pref_codescanner_01.htm">exported</a>. The file contains the following elements: </p>
<ul>
<li><a href="#ARG_Element">Arguments</a> element – specifies the arguments to be passed to CodeScanner</li>
<li><a href="#SRC_Element">Sources</a> element – specifies the file types to be ignored by CodeScanner</li>
<li><a href="#SCRIPT_Element">Scripts</a> element – specifies the rules to be applied by CodeScanner</li>
<li><a href="#SEV_Element">Severities</a> element – specifies the severity levels of rules to be applied by CodeScanner</li>
<li><a href="#CAT_Element">Categories</a> element – specifies the categories of rules to be applied by CodeScanner</li>
<li><a href="#RULE_Element">CustomRules</a> element – specifies user defined rules to be applied by CodeScanner</li>
</ul>
<h4><a name="ARG_Element" id="ARG_Element"></a>Arguments Element</h4>
<p>Each Arguments element contains one or more of the following arguments: </p>
<ul>
<li><b>Input</b> element (<span class="code"><input></span>, <span class="code"></input></span>) – Specify an additional directory or file to scan. </li>
<li><b>Outputformat</b> element (<span class="code"><outputformat></span>, <span class="code"></outputformat></span>) – Specify the output format(s) of the results generated by CodeScanner. Currently the following output formats are supported:
<ul>
<li>html – generate HTML report</li>
<li> xml – generate an XML report</li>
<li> std – generate messages in standard console output</li>
</ul>
</li>
<li><b>LXR</b> element (<span class="code"><lxr></span>, <span class="code"></lxr></span>) – Specify the URL to an LXR site. When this argument is present, CodeScanner generates links to the specified LXR site instead of the local file system. </li>
<li><b>LXR version</b> element (<span class="code"><lxrversion></span>, <span class="code"></lxrversion></span>) – Specify the LXR version when generating links to an LXR site. </li>
<li><b>Timestampedoutput</b> element (<span class="code"><timestampedoutput></span>, <span class="code"></timestampedoutput></span>) – Specify whether to generate results in a time-stamped output directory. Supported values are on and off. </li>
</ul>
<p>An example of an Arguments element: </p>
<p class="listing"><arguments><br />
<input>C:\Symbian\9.2\Epoc32\include</input><br />
<input>C:\CodeScanner_Tests\includes</input> <br />
<lxr>http://s60lxr/source/</lxr> <br />
<lxrversion>S60_3_2_200736</lxrversion><br />
<outputformat>html|std</outputformat> <br />
<timestampedoutput>on</timestampedoutput> <br />
</arguments> </p>
<h4><a name="SRC_Element" id="ARG_Element2"></a>Sources Element</h4>
<p>Each Sources element can contain one or more Excludes elements. </p>
<ul>
<li><b>Excludes</b> element (<span class="code"><excludes></span>, <span class="code"></excludes></span>) – Each Excludes element contains a string, which is a regular expression that specifies a file type to be ignored by CodeScanner. </li>
</ul>
<p>An example of a Sources element: </p>
<p class="listing"><sources> <br />
<exclude>.*\.avi</exclude> <br />
<exclude>.*\.bmp</exclude> <br />
<exclude>.*\.jpg</exclude> <br />
<exclude>.*\\test\\.*</exclude> <br />
</sources> </p>
<h4><a name="SCRIPT_Element" id="ARG_Element3"></a>Scripts Element</h4>
<p>Each Scripts element can contain one or more Script elements, each of which corresponds to a CodeScanner script (each script applies a CodeScanner rule): </p>
<ul>
<li><b>Script</b> element The name of each Script element matches the name of the corresponding rule, e.g. baseconstruct, forbiddenwords, magicnumbers. Each Script element has the following attributes:
<ul>
<li>enable (boolean) – specifies whether a script is enabled by CodeScanner</li>
<li>severity (string) – specifies the severity level of a script</li>
<li>category (string) – specifies the category of a script</li>
</ul>In addition, certain script elements also have special child element or attribute:
</li>
<ul>
<li><b>wordsRE</b> element (<span class="code"><wordsRE></span>, <span class="code"></wordsRE></span>) – Specify the child element of the forbiddenwords script element. The wordsRE element contains a string, which is a regular expression that specifies the forbidden words detected by the forbiddenwords script.</li>
<li><b>length</b> attribute – Attribute of the longlines script element. The length attribute is a string that specifies the maximum length of a line of code, beyond which the longlines script flags as a problem. </li>
<li><b>LFunctionIgnoreRE</b> element (<span class="code"><LFunctionIgnoreRE></span>, <span class="code"></LFunctionIgnoreRE></span>) – Specify the child element of the LFunctionCantLeave script element. The LFunctionIgnoreRE element contains a string, which is a regular expression that specifies the L-functions to be ignored by the LFunctionCantLeave script when checking for L-functions inside cannot leave. </li>
<li><b>cclassIgnoreRE</b> element (<span class="code"><cclassIgnoreRE></span>, <span class="code"></cclassIgnoreRE></span>) – Specify the child element of the missingcclass script element. The cclassIgnoreRE element contains a string, which is a regular expression that specifies the classes to be ignored by the missingcclass script when checking for C classes not inheriting from other C classes.</li>
<li><b>openIgnoreRE</b> element (<span class="code"><openIgnoreRE></span>, <span class="code"></openIgnoreRE></span>) – Specify the child element of this open script element. The openIgnoreRE element contains a string, which is a regular expression that specifies the classes or objects to be ignored by the open script when checking for ignored return type from Open(). </li>
<li><b>worryRE</b> element (<span class="code"><worryRE></span>, <span class="code"></ worryRE></span>) – Child element of the worryingcomments script element. The worryRE element contains a string, which is a regular expression that specifies the worrying comments detected by the worryingcomments script. </li>
</ul>
</ul>
<p>Complete list of currently supported Script elements with default attributes: </p>
<p class="listing"><scripts><br />
<br />
<accessArrayElementWithoutCheck category="codereview" enable="true" severity="low"/><br />
<accessArrayElementWithoutCheck2 category="codereview" enable="true" severity="low"/> <br />
<activestart category="codereview" enable="true" severity="low"/> <br />
<activestop category="codereview" enable="true" severity="low"/> <br />
<arraypassing category="performance" enable="true" severity="medium"/> <br />
<arrayptrcleanup category="codereview" enable="true" severity="low"/> <br />
<assertdebuginvariant category="codingstandards" enable="true" severity="low"/><br />
<br />
<baddefines category="codingstandards" enable="true" severity="low"/> <br />
<baseconstruct category="codereview" enable="true" severity="low"/><br />
<br />
<callActiveObjectWithoutCheckingOrStopping category="codereview" enable="true" severity="low"/> <changenotification category="codereview" enable="true" severity="low"/> <br />
<cleanup category="codingstandards" enable="true" severity="low"/> <br />
<commentcode category="codereview" enable="true" severity="low"/> <br />
<connect category="canpanic" enable="true" severity="high"/> <br />
<ConnectAndDontCloseMemberVariable category="functionality" enable="true" severity="medium"/> <constnames category="codingstandards" enable="true" severity="low"/> <br />
<consttdescptr category="codingstandards" enable="true" severity="low"/> <br />
<controlornull category="canpanic" enable="true" severity="high"/> <br>
<crepository category="other" enable="true" severity="low"/><br />
<ctltargettype category="functionality" enable="true" severity="medium"/> <br />
<customizableicons category="other" enable="true" severity="low"><br>
<iconsRE>iconA.bmp|iconB.svg|iconC</iconsRE> <br>
</customizableicons><br>
<br />
<debugrom category="performance" enable="true" severity="medium"/> <br />
<declarename category="codingstandards" enable="true" severity="low"/> <br />
<deleteMemberVariable category="canpanic" enable="true" severity="high"/> <br />
<destructor category="canpanic" enable="true" severity="high"/> <br />
<doubleSemiColon category="codereview" enable="true" severity="low"/> <br />
<driveletters category="codingstandards" enable="true" severity="low"/> <br />
<br />
<eikbuttons category="localisation" enable="true" severity="medium"/> <br />
<eikonenvstatic category="performance" enable="true" severity="medium"/> <br />
<enummembers category="codingstandards" enable="true" severity="low"/> <br />
<enumnames category="codingstandards" enable="true" severity="low"/> <br />
<exportinline category="functionality" enable="true" severity="medium"/> <br />
<exportpurevirtual category="functionality" enable="true" severity="medium"/> <br />
<br />
<flags category="other" enable="true" severity="low"/><br>
<foff category="codereview" enable="true" severity="low"/> <br />
<forbiddenwords category="codingstandards" enable="true" severity="low"> <br />
<wordsRE>Epoc|Nokia Mobile Phones|NMP|(^|\s)S60</wordsRE> <br />
</forbiddenwords><br />
<forgottoputptroncleanupstack category="codereview" enable="true" severity="low"/> <br />
<friend category="codereview" enable="true" severity="low"/> <br />
<br />
<goto category="codingstandards" enable="true" severity="low"/> <br />
<br />
<ifassignments category="codingstandards" enable="true" severity="low"/> <br />
<ifpreprocessor category="codingstandards" enable="true" severity="low"/> <br />
<inheritanceorder category="canpanic" enable="true" severity="high"/> <br />
<intleaves category="codereview" enable="true" severity="low"/> <br />
<br />
<jmp category="codingstandards" enable="true" severity="low"/> <br />
<br />
<leave category="canpanic" enable="true" severity="high"/> <br />
<LeaveNoError category="functionality" enable="true" severity="medium"/> <br />
<leavingoperators category="codereview" enable="true" severity="low"/> <br />
<LFunctionCantLeave category="codereview" enable="true" severity="low"> <LFunctionIgnoreRE>RunL</LFunctionIgnoreRE> </LFunctionCantLeave> <br />
<longlines category="codingstandards" enable="true" length="160" severity="low"/> <br />
<br />
<magicnumbers category="codingstandards" enable="true" severity="low"/> <br />
<mclassdestructor category="codingstandards" enable="true" severity="low"/> <br />
<memberlc category="canpanic" enable="true" severity="high"/> <br />
<membervariablecallld category="codingstandards" enable="true" severity="low"/> <br />
<missingcancel category="codingstandards" enable="true" severity="low"/> <br />
<missingcclass category="canpanic" enable="true" severity="high"> <cclassIgnoreRE>CBase</cclassIgnoreRE> <br />
</missingcclass> <br />
<mmpsourcepath category="codingstandards" enable="true" severity="low"/> <br />
<multilangrsc category="codereview" enable="true" severity="low"/> <br />
<multipledeclarations category="codingstandards" enable="true" severity="low"/> <br />
<multipleinheritance category="functionality" enable="true" severity="medium"/> <br />
<mydocs category="functionality" enable="true" severity="medium"/> <br />
<br />
<namespace category="codingstandards" enable="true" severity="low"/> <br />
<newlreferences category="codingstandards" enable="true" severity="low"/> <br />
<noleavetrap category="codereview" enable="true" severity="low"/> <br />
<nonconsthbufc category="codingstandards" enable="true" severity="low"/> <br />
<nonconsttdesc category="codingstandards" enable="true" severity="low"/> <br />
<nonleavenew category="codereview" enable="true" severity="low"/> <br />
<nonunicodeskins category="codereview" enable="true" severity="low"/> <br />
<null category="codingstandards" enable="true" severity="low"/> <br />
<br />
<open category="canpanic" enable="true" severity="high"> <openIgnoreRE>RDesReadStream|RDesWriteStream</openIgnoreRE><br />
</open> <br />
<br />
<pointertoarrays category="performance" enable="true" severity="medium"/> <br />
<pragmadisable category="codingstandards" enable="true" severity="low"/> <br />
<pragmamessage category="codingstandards" enable="true" severity="low"/> <br />
<pragmaother category="codereview" enable="true" severity="low"/> <br />
<privateinheritance category="codingstandards" enable="true" severity="low"/> <br />
<pushaddrvar category="canpanic" enable="true" severity="high"/> <br />
<pushmember category="canpanic" enable="true" severity="high"/> <br />
<br />
<readresource category="canpanic" enable="true" severity="high"/> <br />
<resourcenotoncleanupstack category="codereview" enable="true" severity="low"/> <br />
<resourcesonheap category="codingstandards" enable="true" severity="low"/> <returndescriptoroutofscope category="canpanic" enable="true" severity="high"/> <br />
<rfs category="codereview" enable="true" severity="low"/> <br />
<rssnames category="codereview" enable="true" severity="low"/> <br />
<br />
<stringliterals category="codingstandards" enable="true" severity="low"/> <br />
<stringsinresourcefiles category="codereview" enable="true" severity="low"/> <br />
<struct category="codingstandards" enable="true" severity="low"/> <br />
<br />
<tcclasses category="functionality" enable="true" severity="medium"/> <br />
<tclassdestructor category="codingstandards" enable="true" severity="low"/> <br />
<todocomments category="codereview" enable="true" severity="low"/> <br />
<trapcleanup category="panic" enable="true" severity="high"/> <br />
<trapeleave category="performance" enable="true" severity="medium"/> <br />
<traprunl category="codingstandards" enable="true" severity="low"/> <br />
<trspassing category="functionality" enable="true" severity="medium"/> <br />
<br />
<uids category="codereview" enable="true" severity="low"/> <br />
<uncompressedaif category="performance" enable="true" severity="medium"/> <br />
<uncompressedbmp category="performance" enable="true" severity="medium"/> <br />
<unicodesource category="codereview" enable="true" severity="low"/> <br />
<userafter category="performance" enable="true" severity="medium"/> <br />
<userfree category="codereview" enable="true" severity="low"/> <br />
<userWaitForRequest category="codereview" enable="true" severity="low"/> <br />
<br />
<variablenames category="codingstandards" enable="true" severity="low"/> <br />
<voidparameter category="codingstandards" enable="true" severity="low"/> <br />
<br />
<worryingcomments category="codereview" enable="true" severity="low"> <worryRE>\!|\?|[Zz]{3}|kludge|workaround|\scrap|hack</worryRE> <br />
</worryingcomments><br />
<br />
<span class="listing"></scripts> </span></p>
<h4><a name="SEV_Element" id="ARG_Element4"></a>Severities Element</h4>
<p>Each Severities element can contain one or more Severity elements, each of which corresponds to a severity level: </p>
<ul>
<li><b>Severity</b> element The name of each Severity element matches the name of the corresponding severity level. Each Severity element has the following attribute:
<ul>
<li>enable (boolean) – Specifies whether scripts of a particular severity level are enabled by CodeScanner.</li>
</ul>
</li>
</ul>
<p> Complete list of currently supported Severity elements: </p>
<p class="listing"><severities><br />
<high enable=”true”/> <br />
<medium enable=”true”/> <br />
<low enable=”false”/><br />
</severities> </p>
<h4><a name="CAT_Element" id="ARG_Element5"></a>Categories Element </h4>
<p>Each Categories element can contain one or more Category elements, each of which corresponds to a category of CodeScanner scripts: </p>
<ul>
<li><b>Category</b> element The name of each Category element matches the name of the corresponding script category. Each Category element has the following attribute:
<ul>
<li>enable (boolean) – Specifies whether scripts of a particular category are enabled by CodeScanner. </li>
</ul>
</li>
</ul>
<p>Complete list of currently supported Category elements: </p>
<p class="listing"><categories> <br />
<legal enable="true"/><br />
<panic enable=”true”><br />
<canpanic enable="true"/> <br />
<functionality enable=”true”/><br />
<localisation enable="true"/><br />
<performance enable=”true”><br />
<codingstandards enable="true"/><br />
<documentation enable=”false”/><br />
<codereview enable=”false”/><br />
<other enable="true"/> <br />
</categories></p>
<h4><a name="RULE_Element" id="ARG_Element6"></a>Customrules Element </h4>
<p>Each custom rules element can contain one or more custom rule elements, each of which defines a custom rule to be applied by CodeScanner during scanning operation: </p>
<ul>
<li><b>Custom</b> rule element (<span class="code"><customrule></span>, <span class="code"></customrule></span>) </li>
</ul>
<p>Each custom rule element contains the following elements: </p>
<ul>
<li><b>Name</b> element (<span class="code"><name></span>, <span class="code"></name></span>) – The name element specifies the name used by CodeScanner internally to identify a custom rule. A custom rule element can only have one name element.</li>
<li> <b>Keyword</b> element (<span class="code"><keyword></span>, <span class="code"></keyword></span>) – A keyword element specifies a keyword to use when applying a custom rule. A custom rule element can have multiple keyword elements. <br />
<br />
A keyword element also has the following attribute:
<ul>
<li>type(string) – specifies the type of a keyword. Here is a list of currently supported keyword types:
<ul>
<li>baseclass (name of the base class from the declaration of a sub-class) </li>
<li>call (name of a called method) </li>
<li>class (name used in the declaration/definition of a class) </li>
<li>comment (keyword from a comment) </li>
<li>generic (keyword used in generic search, i.e. look for anything that matches the keyword) </li>
<li>local (name used in the definition of a local variable)</li>
<li>macro (name used in the definition of a macro) </li>
<li>member (name used in the definition of a data member)</li>
<li> method (name used in the declaration/definition of a method) </li>
<li>parameter (name of a resource statement parameter) </li>
</ul>
</li>
</ul>
</li>
<li><b>File type</b> element (<span class="code"><filetype></span>, <span class="code"></filetype></span>) – A file type element specifies a file extension type to scan when applying a custom rule. A custom rule element can have multiple file type elements. This element is required.</li>
<li><b>Severity</b> element (<span class="code"><severity></span>, <span class="code"></severity></span>) – A severity element specifies the severity level of a custom rule: high, medium or low. A custom rule element can have only one severity element.</li>
<li><b>Title</b> element (<span class="code"><title></span>,<span class="code"> </title></span>) – A title element specifies a title message associated with a custom rule. This is used as the title of HTML report or stdout warning/error message generated when applying a custom rule. A custom rule element can have only one title element.</li>
<li><b>Description</b> element (<span class="code"><description></span>, <span class="code"></description></span>) – A description element specifies a detailed description of a custom rule. This is used when generating HTML reports or warning/error messages for stdout when applying a custom rule. A custom rule element can have zero or one description element.</li>
<li><b>Link</b> element (<span class="code"><link></span>, <span class="code"></link></span>) – A link element specifies any external link associated with a custom rule. This is used when generating HTML reports or warning/error messages for stdout when applying a custom rule. A custom rule element can have zero or one link element. </li>
</ul>
<p>An example of CustomRules element: </p>
<p class="listing"><customrules><br />
<customrule><br />
<name>myOwnRule</name><br />
<keyword type=”class”>CMyOwnClass</keyword><br />
<filetype>h</filetype><br />
<severity>low</severity><br />
<title>My own little CodeScanner rule</title><br />
<description>Locate the definition of CMyOwnClass::MyFunction()</description><br />
<link>http://www.myownsite.nokia.com</link><br />
</customrule><br />
</customrules></p>
<div id="footer">Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. <br />License: <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a></div>
</body>
</html>