walkero
/
cppcheck
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Merge pull request #27 from gerundt/man-improvements 

Manual improvements
This commit is contained in:
Daniel Marjamäki 2011-07-04 12:10:10 -07:00
parent 982b645ff4 8edf654d24
commit c999f014fe
5 changed files with 130 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
man/cppcheck-design.docbook
View File

@ -94,7 +94,7 @@
analysis can be needed to avoid false warnings. Here is an example that
logically is the same as the previous example:</para>
<para><programlisting>void f1(char *s)
<programlisting>void f1(char *s)
{
s[20] = 0;
}
@ -105,7 +105,9 @@ void f2()
if (x + y == 2) {
f1(a);
}
}</programlisting>Cppcheck will report this message:</para>
}</programlisting>
<para>Cppcheck will report this message:</para>
<programlisting>Array 'a[10]' index 20 out of bounds</programlisting>
@ -116,7 +118,7 @@ void f2()
prove that "x+y==2" can be true when the function is called from "f2". No
error message is reported for this code:</para>
<para><programlisting>void f1(char *s)
<programlisting>void f1(char *s)
{
if (x + y == 2) {
s[20] = 0;
@ -127,7 +129,7 @@ void f2()
{
char a[10];
f1(a);
}</programlisting></para>
}</programlisting>
</section>
<section>

155
man/manual.docbook
View File

@ -106,11 +106,12 @@ Checking path/file2.cpp...
<programlisting>cppcheck src/a src/b</programlisting>
<para>All files under "src/a" and "src/b" are then checked.</para>
<para>All files under <filename class="directory">src/a</filename> and
<filename class="directory">src/b</filename> are then checked.</para>
<para>The second option is to use <literal>-i</literal>, with it you
specify files/paths to ignore. With this command no files in "src/c" are
checked:</para>
<para>The second option is to use <parameter class="command">-i</parameter>,
with it you specify files/paths to ignore. With this command no files in
<filename class="directory">src/c</filename> are checked:</para>
<programlisting>cppcheck -isrc/c src</programlisting>
</section>
@ -174,16 +175,17 @@ Checking path/file2.cpp...
<section>
<title>Enable messages</title>
<para>By default only <literal>error</literal> messages are shown.
Through the <literal>--enable</literal> command more checks can be
enabled.</para>
<para>By default only <parameter class="command">error</parameter> messages
are shown. Through the <parameter class="command">--enable</parameter>
command more checks can be enabled.</para>
<section>
<title>Stylistic issues</title>
<para>With <literal>--enable=style</literal> you enable most
<literal>warning</literal>, <literal>style</literal> and
<literal>performance</literal> messages.</para>
<para>With <parameter class="command">--enable=style</parameter> you
enable most <parameter class="command">warning</parameter>,
<parameter class="command">style</parameter> and
<parameter class="command">performance</parameter> messages.</para>
<para>Here is a simple code example:</para>
@ -197,16 +199,16 @@ Checking path/file2.cpp...
}</programlisting>
<para>There are no bugs in that code so Cppcheck won't report anything
by default. To enable the stylistic messages, use the --enable=style
command:</para>
by default. To enable the stylistic messages, use the
<parameter class="command">--enable=style</parameter> command:</para>
<programlisting>cppcheck --enable=style file3.c</programlisting>
<para>The output from Cppcheck is now:</para>
<para><programlisting>Checking file3.c...
<programlisting>Checking file3.c...
[file3.c:3]: (style) Variable 'i' is assigned a value that is never used
[file3.c:3]: (style) The scope of the variable i can be reduced</programlisting></para>
[file3.c:3]: (style) The scope of the variable i can be reduced</programlisting>
</section>
<section>
@ -223,7 +225,7 @@ Checking path/file2.cpp...
<title>Enable all checks</title>
<para>To enable all checks your can use the
<literal>--enable=all</literal> flag:</para>
<parameter class="command">--enable=all</parameter> flag:</para>
<programlisting>cppcheck --enable=all path</programlisting>
</section>
@ -248,7 +250,7 @@ Checking path/file2.cpp...
</section>
</chapter>
<chapter>
<chapter id="preprocessor-configurations">
<title>Preprocessor configurations</title>
<para>By default Cppcheck will check all preprocessor configurations
@ -256,16 +258,16 @@ Checking path/file2.cpp...
behaviour.</para>
<para>But if you want to manually limit the checking you can do so with
<literal>-D</literal>.</para>
<parameter class="command">-D</parameter>.</para>
<para>Beware that only the macros, which are given here and the macros
defined in source files and known header files are considered. That
excludes all the macros defined in some system header files, which are by
default not examined by cppcheck.</para>
default not examined by Cppcheck.</para>
<para>The usage: if you, for example, want to limit the checking so the
only configuration to check should be "DEBUG=1;__cplusplus" then something
like this can be used:</para>
only configuration to check should be <literal>DEBUG=1;__cplusplus</literal>
then something like this can be used:</para>
<programlisting>cppcheck -DDEBUG=1 -D__cplusplus path</programlisting>
</chapter>
@ -275,7 +277,8 @@ Checking path/file2.cpp...
<para>Cppcheck can generate the output in XML format.</para>
<para>Use the --xml flag when you execute cppcheck:</para>
<para>Use the <parameter class="command">--xml</parameter> flag when you
execute cppcheck:</para>
<programlisting>cppcheck --xml file1.cpp</programlisting>
@ -291,7 +294,7 @@ Checking path/file2.cpp...
<variablelist>
<varlistentry>
<term>file</term>
<term><sgmltag class="attribute">file</sgmltag></term>
<listitem>
<para>filename. Both relative and absolute paths are possible</para>
@ -299,7 +302,7 @@ Checking path/file2.cpp...
</varlistentry>
<varlistentry>
<term>line</term>
<term><sgmltag class="attribute">line</sgmltag></term>
<listitem>
<para>a number</para>
@ -307,7 +310,7 @@ Checking path/file2.cpp...
</varlistentry>
<varlistentry>
<term>id</term>
<term><sgmltag class="attribute">id</sgmltag></term>
<listitem>
<para>id of error. These are always valid symbolnames.</para>
@ -315,17 +318,18 @@ Checking path/file2.cpp...
</varlistentry>
<varlistentry>
<term>severity</term>
<term><sgmltag class="attribute">severity</sgmltag></term>
<listitem>
<para>either <literal>error</literal> or <literal>style</literal>.
<literal>warning</literal> and <literal>performance</literal> are
saved as <literal>style</literal>.</para>
<para>either <sgmltag class="attvalue">error</sgmltag> or
<sgmltag class="attvalue">style</sgmltag>.</para>
<para><literal>warning</literal> and <literal>performance</literal>
are saved as <sgmltag class="attvalue">style</sgmltag>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>msg</term>
<term><sgmltag class="attribute">msg</sgmltag></term>
<listitem>
<para>the error message</para>
@ -340,8 +344,8 @@ Checking path/file2.cpp...
<para>If you want to reformat the output so it looks different you can use
templates.</para>
<para>To get Visual Studio compatible output you can use "--template
vs":</para>
<para>To get Visual Studio compatible output you can use
<parameter class="command">--template vs</parameter>:</para>
<programlisting>cppcheck --template vs gui/test.cpp</programlisting>
@ -351,7 +355,8 @@ Checking path/file2.cpp...
gui/test.cpp(31): error: Memory leak: b
gui/test.cpp(16): error: Mismatching allocation and deallocation: k</programlisting>
<para>To get gcc compatible output you can use "--template gcc":</para>
<para>To get gcc compatible output you can use
<parameter class="command">--template gcc</parameter>:</para>
<programlisting>cppcheck --template gcc gui/test.cpp</programlisting>
@ -371,30 +376,29 @@ gui/test.cpp:16: error: Mismatching allocation and deallocation: k</programlisti
<programlisting>Checking gui/test.cpp...
gui/test.cpp,31,error,memleak,Memory leak: b
gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocation: k</programlisting>
<para></para>
</chapter>
<chapter>
<title>Suppressions</title>
<para>If you want to filter out certain errors you can suppress these.
The <literal>--suppress=</literal> command line option is used to specify
suppressions on the command line. The format is one of:</para>
The <parameter class="command">--suppress=</parameter> command line option
is used to specify suppressions on the command line.
The format is one of:</para>
<programlisting>[error id]:[filename]:[line]
[error id]:[filename2]
[error id]</programlisting>
<para>The <literal>error id</literal> is the id that you want to suppress.
The easiest way to get it is to use the <literal>--xml</literal> command
line flag. Copy and paste the <literal>id</literal> string from the XML
output. This may be * to suppress all warnings (for a specified file or
files).</para>
<para>The <replaceable>error id</replaceable> is the id that you want to suppress.
The easiest way to get it is to use the <parameter class="command">--xml</parameter>
command line flag. Copy and paste the <replaceable>id</replaceable> string from the XML
output. This may be <literal>*</literal> to suppress all warnings (for a
specified file or files).</para>
<para>The <literal>filename</literal> may include the wildcard characters
* or ?, which match any sequence of characters or any single character
respectively.</para>
<para>The <replaceable>filename</replaceable> may include the wildcard characters
<literal>*</literal> or <literal>?</literal>, which match any sequence of
characters or any single character respectively.</para>
<programlisting>cppcheck --suppress=memleak:file1.cpp src/</programlisting>
@ -410,8 +414,6 @@ uninitvar</programlisting>
<para>You can then use the suppressions file:</para>
<programlisting>cppcheck --suppressions suppressions.txt src/</programlisting>
<para></para>
</chapter>
<chapter>
@ -424,18 +426,18 @@ uninitvar</programlisting>
<section>
<title>User-defined allocation/deallocation functions</title>
<para><literal>Cppcheck</literal> understands many common allocation and
<para>Cppcheck understands many common allocation and
deallocation functions. But not all.</para>
<para>Here is example code that might leak memory or resources:</para>
<para><programlisting>void foo(int x)
<programlisting>void foo(int x)
{
void *f = CreateFred();
if (x == 1)
return;
DestroyFred(f);
}</programlisting></para>
}</programlisting>
<para>If you analyse that with Cppcheck it won't find any leaks:</para>
@ -455,14 +457,15 @@ void DestroyFred(void *p)
free(p);
}</programlisting>
<para>When Cppcheck see this it understands that CreateFred will return
allocated memory and that DestroyFred will deallocate memory.</para>
<para>When Cppcheck see this it understands that <function>CreateFred()
</function> will return allocated memory and that <function>DestroyFred()
</function> will deallocate memory.</para>
<para>Now, execute <literal>Cppcheck</literal> this way:</para>
<para>Now, execute <command>cppcheck</command> this way:</para>
<programlisting>cppcheck --append=fred.cpp fred1.cpp</programlisting>
<para>The output from cppcheck is:</para>
<para>The output from <command>cppcheck</command> is:</para>
<programlisting>Checking fred1.cpp...
[fred1.cpp:5]: (error) Memory leak: f</programlisting>
@ -482,11 +485,11 @@ void DestroyFred(void *p)
{
}</programlisting>
<para>By default cppcheck will not detect any problems in that
<para>By default Cppcheck will not detect any problems in that
code.</para>
<para>To enable the exception safety checking you can use
<literal>--enable</literal>:</para>
<parameter class="command">--enable</parameter>:</para>
<programlisting>cppcheck --enable=exceptNew --enable=exceptRealloc fred.cpp</programlisting>
@ -494,8 +497,8 @@ void DestroyFred(void *p)
<programlisting>[fred.cpp:3]: (style) Upon exception there is memory leak: a</programlisting>
<para>If an exception occurs when <literal>b</literal> is allocated,
<literal>a</literal> will leak.</para>
<para>If an exception occurs when <varname>b</varname> is allocated,
<varname>a</varname> will leak.</para>
<para>Here is another example:</para>
@ -523,17 +526,18 @@ int a(int sz)
<para>You can convert the XML output from cppcheck into a HTML report.
You'll need Python and the pygments module
(<uri>http://pygments.org/</uri>) for this to work. In the Cppcheck source
tree there is a folder "htmlreport" that contains a script that transforms
a Cppcheck XML file into HTML output.</para>
(<ulink url="http://pygments.org/">http://pygments.org/</ulink>) for this to
work. In the Cppcheck source tree there is a folder
<filename class="directory">htmlreport</filename> that contains a script
that transforms a Cppcheck XML file into HTML output.</para>
<para>This command generates the help screen:</para>
<para><programlisting>htmlreport/cppcheck-htmlreport -h</programlisting></para>
<programlisting>htmlreport/cppcheck-htmlreport -h</programlisting>
<para>The output screen says:</para>
<para><programlisting>Usage: cppcheck-htmlreport [options]
<programlisting>Usage: cppcheck-htmlreport [options]
Options:
-h, --help show this help message and exit
@ -542,7 +546,7 @@ Options:
--report-dir=REPORT_DIR
The directory where the html report content is written.
--source-dir=SOURCE_DIR
Base directory where source code files can be found.</programlisting></para>
Base directory where source code files can be found.</programlisting>
<para>An example usage:</para>
@ -565,7 +569,7 @@ htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.<
<section>
<title>Check source code</title>
<para>Use the <literal>Check</literal> menu.</para>
<para>Use the <guimenu>Check</guimenu> menu.</para>
</section>
<section>
@ -574,7 +578,7 @@ htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.<
<para>The results are shown in a list.</para>
<para>You can show/hide certain types of messages through the
<literal>View</literal> menu.</para>
<guimenu>View</guimenu> menu.</para>
<para>Results can be saved to an XML file that can later be opened. See
<literal>Save results to file</literal> and <literal>Open
@ -585,10 +589,11 @@ htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.<
<title>Settings</title>
<para>The language can be changed at any time by using the
<literal>Language</literal> menu.</para>
<guimenu>Language</guimenu> menu.</para>
<para>More settings are available in
<literal>Edit</literal>&gt;<literal>Preferences</literal>.</para>
<menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem>
</menuchoice>.</para>
</section>
<section>
@ -612,13 +617,23 @@ htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.<
recommended that this known functionality is redefined. But feel free to
try it.</para>
<para>As you can read in chapter 3 in this manual the default is that
Cppcheck checks all configurations. So only provide preprocessor defines
if you want to limit the checking.</para>
<para>As you can read in <link linkend="preprocessor-configurations">chapter
3</link> in this manual the default is that Cppcheck checks all configurations.
So only provide preprocessor defines if you want to limit the checking.</para>
</section>
</chapter>
<appendix>
<info>
<author>
<firstname>Daniel</firstname>
<surname>Marjamäki</surname>
<affiliation>
<orgname>Cppcheck</orgname>
</affiliation>
</author>
<pubdate>2010-2011</pubdate>
</info>
<title>Writing Cppcheck rules</title>
&writing-rules-1;
&writing-rules-2;

38
man/writing-rules-1.docbook
View File

@ -1,21 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<section>
<info>
<section id="writing-rules-1">
<title>Part 1 - Getting started</title>
<author>
<firstname>Daniel</firstname>
<surname>Marjamäki</surname>
<affiliation>
<orgname>Cppcheck</orgname>
</affiliation>
</author>
<pubdate>2010</pubdate>
</info>
<section>
<title>Introduction</title>
@ -30,7 +16,7 @@
<title>Data representation of the source code</title>
<para>The data used by the rules are not the raw source code.
<literal>Cppcheck</literal> will read the source code and process it
Cppcheck will read the source code and process it
before the rules are used.</para>
<para>Cppcheck is designed to find bugs and dangerous code. Stylistic
@ -39,7 +25,8 @@
you write rules.</para>
<para>Between each token in the code there is always a space. For instance
the raw code "1+f()" is processed into "1 + f ( )".</para>
the raw code "<code>1+f()</code>" is processed into "<code>1 + f ( )</code>"
.</para>
<para>The code is simplified in many ways.</para>
</section>
@ -62,10 +49,10 @@
<section>
<title>Step 1 - Creating the regular expression</title>
<para>Cppcheck uses the <literal>PCRE</literal> library to handle
regular expressions. <literal>PCRE</literal> stands for "Perl Compatible
Regular Expressions". The homepage for <literal>PCRE</literal> is
<literal>http://www.pcre.org</literal>.</para>
<para>Cppcheck uses the PCRE library to handle regular expressions.
<acronym>PCRE</acronym> stands for "Perl Compatible Regular Expressions".
The homepage for PCRE is <ulink url="http://www.pcre.org/">
http://www.pcre.org/</ulink>.</para>
<para>Let's create a regular expression that checks for code such
as:</para>
@ -74,7 +61,8 @@
free(p);</programlisting>
<para>For such code the condition is often redundant (on most
implementations it is valid to free a NULL pointer).</para>
implementations it is valid to free a <constant>NULL</constant> pointer).
</para>
<para>The regular expression must be written for the simplified code. To
see what the simplified code looks like you can create a source file
@ -85,8 +73,8 @@
free(p);
}</programlisting>
<para>Save that code as <literal>dealloc.cpp</literal> and then use
<literal>cppcheck --rule=".+" dealloc.cpp</literal>:</para>
<para>Save that code as <filename>dealloc.cpp</filename> and then use
<command>cppcheck --rule=".+" dealloc.cpp</command>:</para>
<programlisting>$ ./cppcheck --rule=".+" dealloc.cpp
Checking dealloc.cpp...
@ -134,7 +122,7 @@ Checking dealloc.cpp...
&lt;/message&gt;
&lt;/rule&gt;</programlisting>
<para>If you save that xml data in <literal>dealloc.rule</literal> you
<para>If you save that xml data in <filename>dealloc.rule</filename> you
can test this rule:</para>
<programlisting>$ cppcheck --rule-file=dealloc.rule dealloc.cpp

46
man/writing-rules-2.docbook
View File

@ -1,21 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<section>
<info>
<section id="writing-rules-2">
<title>Part 2 - The Cppcheck data representation</title>
<author>
<firstname>Daniel</firstname>
<surname>Marjamäki</surname>
<affiliation>
<orgname>Cppcheck</orgname>
</affiliation>
</author>
<pubdate>2010</pubdate>
</info>
<section>
<title>Introduction</title>
@ -33,23 +19,25 @@
<para>There are two ways to look at the data representation at
runtime.</para>
<para>Using --rule=.+ is one way. All tokens are written on a line:</para>
<para>Using <parameter class="command">--rule=.+</parameter> is one way.
All tokens are written on a line:</para>
<programlisting> int a ; int b ;</programlisting>
<para>Using --debug is another way. The tokens are line separated in the
same way as the original code:</para>
<para>Using <parameter class="command">--debug</parameter> is another way.
The tokens are line separated in the same way as the original code:</para>
<programlisting>1: int a@1 ;
2: int b@2 ;</programlisting>
<para>In the --debug output there are "@1" and "@2" shown. These are the
<para>In the <parameter class="command">--debug</parameter> output there are
"@1" and "@2" shown. These are the
variable ids (Cppcheck gives each variable a unique id). You can ignore
these if you only plan to write rules with regular expressions, you can't
use variable ids with regular expressions.</para>
<para>In general, I will use the <literal>--rule=.+</literal> output in
this article because it is more compact.</para>
<para>In general, I will use the <parameter class="command">--rule=.+</parameter>
output in this article because it is more compact.</para>
</section>
<section>
@ -130,7 +118,8 @@ s8 x;</programlisting>
array[x + 2] = 0;
}</programlisting>
<para>The <literal>--debug</literal> output for that is:</para>
<para>The <parameter class="command">--debug</parameter> output for that
is:</para>
<programlisting>1: void f ( )
2: {
@ -154,7 +143,8 @@ s8 x;</programlisting>
free(b);
}</programlisting>
<para>The <literal>--debug</literal> output for that is:</para>
<para>The <parameter class="command">--debug</parameter> output for that
is:</para>
<programlisting>1: void f ( )
2: {
@ -196,7 +186,7 @@ s8 x;</programlisting>
f2();
}</programlisting>
<para>The <literal>--debug</literal> output:</para>
<para>The <parameter class="command">--debug</parameter> output:</para>
<programlisting>1: void f ( int x@1 )
2: {
@ -252,8 +242,8 @@ s8 x;</programlisting>
}
}</programlisting>
<para>The <literal>x=f1()</literal> is broken out. The
<literal>--debug</literal> output:</para>
<para>The <code>x=f1()</code> is broken out. The
<parameter class="command">--debug</parameter> output:</para>
<programlisting>1: void f ( )
2: {
@ -274,7 +264,7 @@ s8 x;</programlisting>
}</programlisting>
<para>The <literal>x=f1()</literal> is broken out twice. The
<literal>--debug</literal> output:</para>
<parameter class="command">--debug</parameter> output:</para>
<programlisting>1: void f ( )
2: {
@ -331,7 +321,7 @@ s8 x;</programlisting>
if (x != 0);
}</programlisting>
<para>The <literal>--debug</literal> output is:</para>
<para>The <parameter class="command">--debug</parameter> output is:</para>
<programlisting>1: void f ( )
2: {

22
man/writing-rules-3.docbook
View File

@ -1,24 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<section>
<info>
<section id="writing-rules-3">
<title>Part 3 - Introduction to writing rules with C++</title>
<author>
<personname><firstname>Daniel</firstname><surname>Marjamäki</surname></personname>
<affiliation>
<orgname>Cppcheck</orgname>
</affiliation>
</author>
<pubdate>2011</pubdate>
</info>
<section>
<title>Introduction</title>
<para>The goal for this article is to introduce how
<literal>Cppcheck</literal> rules are written with C++. With C++ it is
Cppcheck rules are written with C++. With C++ it is
possible to write more complex rules than is possible with regular
expressions.</para>
</section>
@ -95,9 +83,9 @@ void CheckOther::divisionByZeroError()
<section>
<title>Condition before deallocation</title>
<para>In the first <literal>Writing rules</literal> article I described a
rule that looks for redundant conditions. Here is the regular expression
that was shown:</para>
<para>In the first <link linkend="writing-rules-1">Writing rules</link> part
I described a rule that looks for redundant conditions. Here is the regular
expression that was shown:</para>
<programlisting>if \( p \) { free \( p \) ; }</programlisting>