diff options
| author | mikesamuel <mikesamuel@ad8eed46-c659-4a31-e19d-951d88f54425> | 2014-02-27 22:37:22 +0000 |
|---|---|---|
| committer | mikesamuel <mikesamuel@ad8eed46-c659-4a31-e19d-951d88f54425> | 2014-02-27 22:37:22 +0000 |
| commit | 10f18856cda13e8f5ff16c26d965c2577f943457 (patch) | |
| tree | d0f8bda8b6849049370cabf278f4336e7d5cabbf /tools/findbugs/doc/manual | |
| parent | 299511715e3425b6525aa34332610e41975e77b2 (diff) | |
| download | sanitizer-10f18856cda13e8f5ff16c26d965c2577f943457.tar.gz | |
upgraded findbugs to 2.0.3
git-svn-id: http://owasp-java-html-sanitizer.googlecode.com/svn/trunk@222 ad8eed46-c659-4a31-e19d-951d88f54425
Diffstat (limited to 'tools/findbugs/doc/manual')
| -rw-r--r-- | tools/findbugs/doc/manual/acknowledgments.html | 124 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/analysisprops.html | 45 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/annotations.html | 101 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/anttask.html | 214 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/building.html | 123 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/datamining.html | 421 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/eclipse.html | 112 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/filter.html | 363 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/gui.html | 68 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/index.html | 10 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/installing.html | 29 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/introduction.html | 12 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/license.html | 13 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/rejarForAnalysis.html | 33 | ||||
| -rw-r--r-- | tools/findbugs/doc/manual/running.html | 209 |
15 files changed, 1877 insertions, 0 deletions
diff --git a/tools/findbugs/doc/manual/acknowledgments.html b/tools/findbugs/doc/manual/acknowledgments.html new file mode 100644 index 0000000..c2ac454 --- /dev/null +++ b/tools/findbugs/doc/manual/acknowledgments.html @@ -0,0 +1,124 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 14. Acknowledgments</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="license.html" title="Chapter 13. License"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. Acknowledgments</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="license.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 14. Acknowledgments"><div class="titlepage"><div><div><h2 class="title"><a name="acknowledgments"></a>Chapter 14. Acknowledgments</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="acknowledgments.html#d0e3629">1. Contributors</a></span></dt><dt><span class="sect1"><a href="acknowledgments.html#d0e3752">2. Software Used</a></span></dt></dl></div><div class="sect1" title="1. Contributors"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3629"></a>1. Contributors</h2></div></div></div><p><span class="application">FindBugs</span> was originally written by Bill Pugh (<code class="email"><<a class="email" href="mailto:pugh@cs.umd.edu">pugh@cs.umd.edu</a>></code>). +David Hovemeyer (<code class="email"><<a class="email" href="mailto:daveho@cs.umd.edu">daveho@cs.umd.edu</a>></code>) implemented some of the +detectors, added the Swing GUI, and is a co-maintainer.</p><p>Mike Fagan (<code class="email"><<a class="email" href="mailto:mfagan@tde.com">mfagan@tde.com</a>></code>) contributed the <span class="application">Ant</span> build script, +the <span class="application">Ant</span> task, and several enhancements and bug fixes to the GUI.</p><p>Germano Leichsenring contributed Japanese translations of the bug +summaries.</p><p>David Li contributed the Emacs bug report format.</p><p>Peter D. Stout contributed recursive detection of Class-Path +attributes in analyzed Jar files, German translations of +text used in the Swing GUI, and other fixes.</p><p>Peter Friese wrote the <span class="application">FindBugs</span> Eclipse plugin.</p><p>Rohan Lloyd contributed several Mac OS X enhancements, +bug detector improvements, +and maintains the Fink package for <span class="application">FindBugs</span>.</p><p>Hiroshi Okugawa translated the <span class="application">FindBugs</span> manual and +more of the bug summaries into Japanese.</p><p>Phil Crosby enhanced the Eclipse plugin to add a view +to display the bug details.</p><p>Dave Brosius fixed a number of bugs, added user preferences +to the Swing GUI, improved several bug detectors, and +contributed the string concatenation detector.</p><p>Thomas Klaeger contributed a number of bug fixes and +bug detector improvements.</p><p>Andrei Loskutov made a number of improvements to the +Eclipse plugin.</p><p>Brian Goetz contributed a major refactoring of the +visitor classes to improve readability and understandability.</p><p> Pete Angstadt fixed several problems in the Swing GUI.</p><p>Francis Lalonde provided a task resource file for the +FindBugs Ant task.</p><p>Garvin LeClaire contributed support for output in +Xdocs format, for use by Maven.</p><p>Holger Stenzhorn contributed improved German translations of items +in the Swing GUI.</p><p>Juha Knuutila contributed Finnish translations of items +in the Swing GUI.</p><p>Tanel Lebedev contributed Estonian translations of items +in the Swing GUI.</p><p>Hanai Shisei (ruimo) contributed full Japanese translations of +bug messages, and text used in the Swing GUI.</p><p>David Cotton contributed Fresh translations for bug +messages and for the Swing GUI.</p><p>Michael Tamm contributed support for the "errorProperty" attribute +in the Ant task.</p><p>Thomas Kuehne improved the German translation of the Swing GUI.</p><p>Len Trigg improved source file support for the Emacs output mode.</p><p>Greg Bentz provided a fix for the hashcode/equals detector.</p><p>K. Hashimoto contributed internationalization fixes and several other + bug fixes.</p><p> + Glenn Boysko contributed support for ignoring specified local + variables in the dead local store detector. +</p><p> + Jay Dunning contributed a detector to find equality comparisons + of floating-point values, and overhauled the analysis summary + report and its representation in the saved XML format. +</p><p> + Olivier Parent contributed updated French translations for bug descriptions and + Swing GUI. +</p><p> + Chris Nappin contributed the <code class="filename">plain.xsl</code> + stylesheet. +</p><p> + Etienne Giraudy contributed the <code class="filename">fancy.xsl</code> and <code class="filename">fancy-hist.xsl</code> + stylesheets, and made improvements to the <span class="command"><strong>-xml:withMessages</strong></span> + option. +</p><p> + Takashi Okamoto fixed bugs in the project preferences dialog + in the Eclipse plugin, and contributed to its internationalization and localization. +</p><p>Thomas Einwaller fixed bugs in the project preferences dialog in the Eclipse plugin.</p><p>Jeff Knox contributed support for the warningsProperty attribute +in the Ant task.</p><p>Peter Hendriks extended the Eclipse plugin preferences, +and fixed a bug related to renaming the Eclipse plugin ID.</p><p>Mark McKay contributed an Ant task to launch the findbugs frame.</p><p>Dieter von Holten (dvholten) contributed +some German improvements to findbugs_de.properties.</p><p>If you have contributed to <span class="application">FindBugs</span>, but aren't mentioned above, +please send email to <code class="email"><<a class="email" href="mailto:findbugs@cs.umd.edu">findbugs@cs.umd.edu</a>></code> (and also accept +our humble apologies).</p></div><div class="sect1" title="2. Software Used"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3752"></a>2. Software Used</h2></div></div></div><p><span class="application">FindBugs</span> uses several open-source software packages, without which its +development would have been much more difficult.</p><div class="sect2" title="2.1. BCEL"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3759"></a>2.1. BCEL</h3></div></div></div><p><span class="application">FindBugs</span> includes software developed by the Apache Software Foundation +(<a class="ulink" href="http://www.apache.org/" target="_top">http://www.apache.org/</a>). +Specifically, it uses the <a class="ulink" href="http://jakarta.apache.org/bcel/" target="_top">Byte Code +Engineering Library</a>.</p></div><div class="sect2" title="2.2. ASM"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3772"></a>2.2. ASM</h3></div></div></div><p><span class="application">FindBugs</span> uses the <a class="ulink" href="http://asm.objectweb.org/" target="_top">ASM</a> +bytecode framework, which is distributed under the following license:</p><div class="blockquote"><blockquote class="blockquote"><p> +Copyright (c) 2000-2005 INRIA, France Telecom +All rights reserved. +</p><p> +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: +</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + </p></li><li class="listitem"><p> + Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + </p></li><li class="listitem"><p> + Neither the name of the copyright holders nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + </p></li></ol></div><p> +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +THE POSSIBILITY OF SUCH DAMAGE. +</p></blockquote></div></div><div class="sect2" title="2.3. DOM4J"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3799"></a>2.3. DOM4J</h3></div></div></div><p><span class="application">FindBugs</span> uses <a class="ulink" href="http://dom4j.org" target="_top">DOM4J</a>, which is +distributed under the following license:</p><div class="blockquote"><blockquote class="blockquote"><p> +Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved. +</p><p> +Redistribution and use of this software and associated documentation +("Software"), with or without modification, are permitted provided that +the following conditions are met: +</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + Redistributions of source code must retain copyright statements and + notices. Redistributions must also contain a copy of this document. + </p></li><li class="listitem"><p> + Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + </p></li><li class="listitem"><p> + The name "DOM4J" must not be used to endorse or promote products + derived from this Software without prior written permission + of MetaStuff, Ltd. For written permission, please contact + <code class="email"><<a class="email" href="mailto:dom4j-info@metastuff.com">dom4j-info@metastuff.com</a>></code>. + </p></li><li class="listitem"><p> + Products derived from this Software may not be called "DOM4J" nor may + "DOM4J" appear in their names without prior written permission of + MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd. + </p></li><li class="listitem"><p> + Due credit should be given to the DOM4J Project (<a class="ulink" href="http://dom4j.org/" target="_top">http://dom4j.org/</a>). + </p></li></ol></div><p> +THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' +AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS +CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</p></blockquote></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="license.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Chapter 13. License </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/analysisprops.html b/tools/findbugs/doc/manual/analysisprops.html new file mode 100644 index 0000000..83fe93c --- /dev/null +++ b/tools/findbugs/doc/manual/analysisprops.html @@ -0,0 +1,45 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 9. Analysis Properties</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="filter.html" title="Chapter 8. Filter Files"><link rel="next" href="annotations.html" title="Chapter 10. Annotations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. Analysis Properties</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="filter.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="annotations.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 9. Analysis Properties"><div class="titlepage"><div><div><h2 class="title"><a name="analysisprops"></a>Chapter 9. Analysis Properties</h2></div></div></div><p> +<span class="application">FindBugs</span> allows several aspects of the analyses it performs to be +customized. System properties are used to configure these options. +This chapter describes the configurable analysis options. +</p><p> +The analysis options have two main purposes. First, they allow you +to inform <span class="application">FindBugs</span> about the meaning of methods in your application, +so that it can produce more accurate results, or produce fewer +false warnings. Second, they allow you to configure the precision +of the analysis performed. Reducing analysis precision can save +memory and analysis time, at the expense of missing some real bugs, +or producing more false warnings. +</p><p> +The analysis options are set using the <span class="command"><strong>-property</strong></span> +command line option. For example: +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong>findbugs -textui -property "cfg.noprune=true" <em class="replaceable"><code>myApp.jar</code></em></strong></span> +</pre><p> +</p><p> +The list of configurable analysis properties is shown in +<a class="xref" href="analysisprops.html#analysisproptable" title="Table 9.1. Configurable Analysis Properties">Table 9.1, “Configurable Analysis Properties”</a>. +</p><div class="table"><a name="analysisproptable"></a><p class="title"><b>Table 9.1. Configurable Analysis Properties</b></p><div class="table-contents"><table summary="Configurable Analysis Properties" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Property Name</th><th align="left">Value</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left">findbugs.assertionmethods</td><td align="left">Comma-separated list of fully qualified method names: + e.g., "com.foo.MyClass.checkAssertion"</td><td align="left">This property specifies the names of methods that are used + to check program assertions. Specifying these methods allows + the null pointer dereference bug detector to avoid reporting + false warnings for values which are checked by assertion + methods.</td></tr><tr><td align="left">findbugs.de.comment</td><td align="left">true or false</td><td align="left">If true, the DroppedException detector scans source code + for empty catch blocks for a comment, and if one is found, does + not report a warning.</td></tr><tr><td align="left">findbugs.maskedfields.locals</td><td align="left">true or false</td><td align="left">If true, emit low priority warnings for local variables + which obscure fields. Default is false.</td></tr><tr><td align="left">findbugs.nullderef.assumensp</td><td align="left">true or false</td><td align="left">not used + (intention: If true, the null dereference detector assumes that any + reference value returned from a method or passed to a method + in a parameter might be null. Default is false. Note that + enabling this property will very likely cause a large number + of false warnings to be produced.)</td></tr><tr><td align="left">findbugs.refcomp.reportAll</td><td align="left">true or false</td><td align="left">If true, all suspicious reference comparisons + using the == and != operators are reported. If false, + only one such warning is issued per method. Default + is false.</td></tr><tr><td align="left">findbugs.sf.comment</td><td align="left">true or false</td><td align="left">If true, the SwitchFallthrough detector will only report + warnings for cases where the source code does not have a comment + containing the words "fall" or "nobreak". (An accurate source + path must be used for this feature to work correctly.) + This helps find cases where the switch fallthrough is likely + to be unintentional.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="filter.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="annotations.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. Filter Files </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. Annotations</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/annotations.html b/tools/findbugs/doc/manual/annotations.html new file mode 100644 index 0000000..a9909f9 --- /dev/null +++ b/tools/findbugs/doc/manual/annotations.html @@ -0,0 +1,101 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 10. Annotations</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="analysisprops.html" title="Chapter 9. Analysis Properties"><link rel="next" href="rejarForAnalysis.html" title="Chapter 11. Using rejarForAnalysis"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. Annotations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="analysisprops.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="rejarForAnalysis.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 10. Annotations"><div class="titlepage"><div><div><h2 class="title"><a name="annotations"></a>Chapter 10. Annotations</h2></div></div></div><p> +<span class="application">FindBugs</span> supports several annotations to express the developer's intent +so that FindBugs can issue warnings more appropriately. You need to use +Java 5 to use annotations, and must place the annotations.jar and jsr305.jar +files in the classpath while compiling your program. +</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.CheckForNull</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter + <p> +The annotated element might be null, and uses of the element should check for null. +When this annotation is applied to a method it applies to the method return value. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.CheckReturnValue</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Method, Constructor + <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> + <span class="command"><strong>priority:</strong></span>The priority of the warning (HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. + </p><p> + <span class="command"><strong>explanation:</strong></span>A textual explaination of why the return value should be checked. Default value:"". + </p></dd></dl></div><p> +This annotation is used to denote a method whose return value should always be checked after invoking the method. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotation</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package + <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> + <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. + </p><p> + <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. + </p></dd></dl></div><p> +Indicates that all members of the class or package should be annotated with the default +value of the supplied annotation classes. This would be used for behavior annotations +such as @NonNull, @CheckForNull, or @CheckReturnValue. In particular, you can use +@DefaultAnnotation(NonNull.class) on a class or package, and then use @Nullable only +on those parameters, methods or fields that you want to allow to be null. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotationForFields</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package + <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> + <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. + </p><p> + <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. + </p></dd></dl></div><p> +This is same as the DefaultAnnotation except it only applys to fields. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotationForMethods</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package + <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> + <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. + </p><p> + <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. + </p></dd></dl></div><p> +This is same as the DefaultAnnotation except it only applys to methods. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package + <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> + <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. + </p><p> + <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. + </p></dd></dl></div><p> +This is same as the DefaultAnnotation except it only applys to method parameters. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.NonNull</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter + <p> +The annotated element must not be null. +Annotated fields must not be null after construction has completed. Annotated methods must have non-null return values. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.Nullable</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter + <p> +The annotated element could be null under some circumstances. In general, this means +developers will have to read the documentation to determine when a null value is +acceptable and whether it is neccessary to check for a null value. FindBugs will +treat the annotated items as though they had no annotation. + </p><p> +In pratice this annotation is useful only for overriding an overarching NonNull +annotation. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.OverrideMustInvoke</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Method + <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> + <span class="command"><strong>value:</strong></span>Specify when the super invocation should be + performed (FIRST, ANYTIME, LAST). Default value:ANYTIME. + </p></dd></dl></div><p> +Used to annotate a method that, if overridden, must (or should) be invoke super +in the overriding method. Examples of such methods include finalize() and clone(). +The argument to the method indicates when the super invocation should occur: +at any time, at the beginning of the overriding method, or at the end of the overriding method. +(This anotation is not implmemented in FindBugs as of September 8, 2006). + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.PossiblyNull</strong></span></span></dt><dd><p> +This annotation is deprecated. Use CheckForNull instead. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.SuppressWarnings</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Field, Method, Parameter, Constructor, Package + <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> + <span class="command"><strong>value:</strong></span>The name of the warning. More than one name can be specified. + </p><p> + <span class="command"><strong>justification:</strong></span>Reason why the warning should be ignored. Default value:"". + </p></dd></dl></div><p> +The set of warnings that are to be suppressed by the compiler in the annotated element. +Duplicate names are permitted. The second and successive occurrences of a name are ignored. +The presence of unrecognized warning names is <span class="emphasis"><em>not</em></span> an error: Compilers +must ignore any warning names they do not recognize. They are, however, free to emit a +warning if an annotation contains an unrecognized warning name. Compiler vendors should +document the warning names they support in conjunction with this annotation type. They +are encouraged to cooperate to ensure that the same names work across multiple compilers. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.UnknownNullness</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter + <p> +Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. + </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.UnknownNullness</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter + <p> +Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. + </p></dd></dl></div><p> + <span class="application">FindBugs</span> also supports the following annotations: +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">net.jcip.annotations.GuardedBy</li><li class="listitem">net.jcip.annotations.Immutable</li><li class="listitem">net.jcip.annotations.NotThreadSafe</li><li class="listitem">net.jcip.annotations.ThreadSafe</li></ul></div><p> +</p><p> +You can refer the JCIP annotation <a class="ulink" href="http://jcip.net/annotations/doc/index.html" target="_top"> +API documentation</a> at <a class="ulink" href="http://jcip.net/" target="_top">Java Concurrency in Practice</a>. +</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="analysisprops.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="rejarForAnalysis.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. Analysis Properties </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. Using rejarForAnalysis</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/anttask.html b/tools/findbugs/doc/manual/anttask.html new file mode 100644 index 0000000..e601e1f --- /dev/null +++ b/tools/findbugs/doc/manual/anttask.html @@ -0,0 +1,214 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 6. Using the FindBugs™ Ant task</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="gui.html" title="Chapter 5. Using the FindBugs GUI"><link rel="next" href="eclipse.html" title="Chapter 7. Using the FindBugs™ Eclipse plugin"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Using the <span class="application">FindBugs</span>™ <span class="application">Ant</span> task</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="gui.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="eclipse.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 6. Using the FindBugs™ Ant task"><div class="titlepage"><div><div><h2 class="title"><a name="anttask"></a>Chapter 6. Using the <span class="application">FindBugs</span>™ <span class="application">Ant</span> task</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="anttask.html#d0e1205">1. Installing the <span class="application">Ant</span> task</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1243">2. Modifying build.xml</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1314">3. Executing the task</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1339">4. Parameters</a></span></dt></dl></div><p> +This chapter describes how to integrate <span class="application">FindBugs</span> into a build script +for <a class="ulink" href="http://ant.apache.org/" target="_top"><span class="application">Ant</span></a>, which is a popular Java build +and deployment tool. Using the <span class="application">FindBugs</span> <span class="application">Ant</span> task, your build script can +automatically run <span class="application">FindBugs</span> on your Java code. +</p><p> +The <span class="application">Ant</span> task was generously contributed by Mike Fagan. +</p><div class="sect1" title="1. Installing the Ant task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1205"></a>1. Installing the <span class="application">Ant</span> task</h2></div></div></div><p> +To install the <span class="application">Ant</span> task, simply copy <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs-ant.jar</code> +into the <code class="filename">lib</code> subdirectory of your <span class="application">Ant</span> installation. + +</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>It is strongly recommended that you use the <span class="application">Ant</span> task with the version +of <span class="application">FindBugs</span> it was included with. We do not guarantee that the <span class="application">Ant</span> task Jar file +will work with any version of <span class="application">FindBugs</span> other than the one it was included with.</p></td></tr></table></div><p> +</p></div><div class="sect1" title="2. Modifying build.xml"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1243"></a>2. Modifying build.xml</h2></div></div></div><p> +To incorporate <span class="application">FindBugs</span> into <code class="filename">build.xml</code> (the build script +for <span class="application">Ant</span>), you first need to add a task definition. This should appear as follows: + +</p><pre class="screen"> + <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/> +</pre><p> + +The task definition specifies that when a <code class="literal">findbugs</code> element is +seen in <code class="filename">build.xml</code>, it should use the indicated class to execute the task. +</p><p> +After you have added the task definition, you can define a target +which uses the <code class="literal">findbugs</code> task. Here is an example +which could be added to the <code class="filename">build.xml</code> for the +Apache <a class="ulink" href="http://jakarta.apache.org/bcel/" target="_top">BCEL</a> library. + +</p><pre class="screen"> + <property name="findbugs.home" value="/export/home/daveho/work/findbugs" /> + + <target name="findbugs" depends="jar"> + <findbugs home="${findbugs.home}" + output="xml" + outputFile="bcel-fb.xml" > + <auxClasspath path="${basedir}/lib/Regex.jar" /> + <sourcePath path="${basedir}/src/java" /> + <class location="${basedir}/bin/bcel.jar" /> + </findbugs> + </target> +</pre><p> + +The <code class="literal">findbugs</code> element must have the <code class="literal">home</code> +attribute set to the directory in which <span class="application">FindBugs</span> is installed; in other words, +<em class="replaceable"><code>$FINDBUGS_HOME</code></em>. See <a class="xref" href="installing.html" title="Chapter 2. Installing FindBugs™">Chapter 2, <i>Installing <span class="application">FindBugs</span>™</i></a>. +</p><p> +This target will execute <span class="application">FindBugs</span> on <code class="filename">bcel.jar</code>, which is the +Jar file produced by BCEL's build script. (By making it depend on the "jar" +target, we ensure that the library is fully compiled before running <span class="application">FindBugs</span> on it.) +The output of <span class="application">FindBugs</span> will be saved in XML format to a file called +<code class="filename">bcel-fb.xml</code>. +An auxiliary Jar file, <code class="filename">Regex.jar</code>, is added to the aux classpath, +because it is referenced by the main BCEL library. A source path is specified +so that the saved bug data will have accurate references to the BCEL source code. +</p></div><div class="sect1" title="3. Executing the task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1314"></a>3. Executing the task</h2></div></div></div><p> +Here is an example of invoking <span class="application">Ant</span> from the command line, using the <code class="literal">findbugs</code> +target defined above. + +</p><pre class="screen"> + <code class="prompt">[daveho@noir]$</code> <span class="command"><strong>ant findbugs</strong></span> + Buildfile: build.xml + + init: + + compile: + + examples: + + jar: + + findbugs: + [findbugs] Running FindBugs... + [findbugs] Bugs were found + [findbugs] Output saved to bcel-fb.xml + + BUILD SUCCESSFUL + Total time: 35 seconds +</pre><p> + +In this case, because we saved the bug results in an XML file, we can +use the <span class="application">FindBugs</span> GUI to view the results; see <a class="xref" href="running.html" title="Chapter 4. Running FindBugs™">Chapter 4, <i>Running <span class="application">FindBugs</span>™</i></a>. +</p></div><div class="sect1" title="4. Parameters"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1339"></a>4. Parameters</h2></div></div></div><p>This section describes the parameters that may be specified when +using the <span class="application">FindBugs</span> task. + +</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">class</code></span></dt><dd><p> + A optional nested element specifying which classes to analyze. The <code class="literal">class</code> + element must specify a <code class="literal">location</code> attribute which names the + archive file (jar, zip, etc.), directory, or class file to be analyzed. Multiple <code class="literal">class</code> + elements may be specified as children of a single <code class="literal">findbugs</code> element. + </p><p>In addition to or instead of specifying a <code class="literal">class</code> element, + the <span class="application">FindBugs</span> task can contain one or more <code class="literal">fileset</code> element(s) that + specify files to be analyzed. + For example, you might use a fileset to specify that all of the jar files in a directory + should be analyzed. + </p></dd><dt><span class="term"><code class="literal">auxClasspath</code></span></dt><dd><p> + An optional nested element which specifies a classpath (Jar files or directories) + containing classes used by the analyzed library or application, but which + you don't want to analyze. It is specified the same way as + <span class="application">Ant</span>'s <code class="literal">classpath</code> element for the Java task. + </p></dd><dt><span class="term"><code class="literal">sourcePath</code></span></dt><dd><p> + An optional nested element which specifies a source directory path + containing source files used to compile the Java code being analyzed. + By specifying a source path, any generated XML bug output will have + complete source information, which allows later viewing in the + GUI. + </p></dd><dt><span class="term"><code class="literal">home</code></span></dt><dd><p> + A required attribute. + It must be set to the name of the directory where <span class="application">FindBugs</span> is installed. + </p></dd><dt><span class="term"><code class="literal">quietErrors</code></span></dt><dd><p> + An optional boolean attribute. + If true, reports of serious analysis errors and missing classes will + be suppressed in the <span class="application">FindBugs</span> output. Default is false. + </p></dd><dt><span class="term"><code class="literal">reportLevel</code></span></dt><dd><p> + An optional attribute. It specifies + the confidence/priority threshold for reporting issues. If set to "low", confidence is not used to filter bugs. + If set to "medium" (the default), low confidence issues are supressed. + If set to "high", only high confidence bugs are reported. + </p></dd><dt><span class="term"><code class="literal">output</code></span></dt><dd><p> + Optional attribute. + It specifies the output format. If set to "xml" (the default), output + is in XML format. + If set to "xml:withMessages", output is in XML format augmented with + human-readable messages. (You should use this format if you plan + to generate a report using an XSL stylesheet.) + If set to "html", output is in HTML formatted (default stylesheet is default.xsl). + If set to "text", output is in ad-hoc text format. + If set to "emacs", output is in <a class="ulink" href="http://www.gnu.org/software/emacs/" target="_top">Emacs</a> error message format. + If set to "xdocs", output is xdoc XML for use with Apache Maven. + </p></dd><dt><span class="term"><code class="literal">stylesheet</code></span></dt><dd><p> + Optional attribute. + It specifies the stylesheet to use to generate html output when the output is set to html. + Stylesheets included in the FindBugs distribution include default.xsl, fancy.xsl, fancy-hist.xsl, plain.xsl, and summary.xsl. + The default value, if no stylesheet attribute is provided, is default.xsl. + + </p></dd><dt><span class="term"><code class="literal">sort</code></span></dt><dd><p> + Optional attribute. If the <code class="literal">output</code> attribute + is set to "text", then the <code class="literal">sort</code> attribute specifies + whether or not reported bugs are sorted by class. Default is true. + </p></dd><dt><span class="term"><code class="literal">outputFile</code></span></dt><dd><p> + Optional attribute. If specified, names the output file in which the + <span class="application">FindBugs</span> output will be saved. By default, the output is displayed + directly by <span class="application">Ant</span>. + </p></dd><dt><span class="term"><code class="literal">debug</code></span></dt><dd><p> + Optional boolean attribute. If set to true, <span class="application">FindBugs</span> prints diagnostic + information about which classes are being analyzed, and which bug pattern + detectors are being run. Default is false. + </p></dd><dt><span class="term"><code class="literal">effort</code></span></dt><dd><p> + Set the analysis effort level. The value specified should be + one of <code class="literal">min</code>, <code class="literal">default</code>, + or <code class="literal">max</code>. See <a class="xref" href="running.html#commandLineOptions" title="3. Command-line Options">Section 3, “Command-line Options”</a> + for more information about setting the analysis level. + </p></dd><dt><span class="term"><code class="literal">conserveSpace</code></span></dt><dd><p>Synonym for effort="min".</p></dd><dt><span class="term"><code class="literal">workHard</code></span></dt><dd><p>Synonym for effort="max".</p></dd><dt><span class="term"><code class="literal">visitors</code></span></dt><dd><p> + Optional attribute. It specifies a comma-separated list of bug detectors + which should be run. The bug detectors are specified by their class names, + without any package qualification. By default, all detectors which are + not disabled by default are run. + </p></dd><dt><span class="term"><code class="literal">omitVisitors</code></span></dt><dd><p> + Optional attribute. It is like the <code class="literal">visitors</code> attribute, + except it specifies detectors which will <span class="emphasis"><em>not</em></span> be run. + </p></dd><dt><span class="term"><code class="literal">excludeFilter</code></span></dt><dd><p> + Optional attribute. It specifies the filename of a filter specifying bugs + to exclude from being reported. See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. + </p></dd><dt><span class="term"><code class="literal">includeFilter</code></span></dt><dd><p> + Optional attribute. It specifies the filename of a filter specifying + which bugs are reported. See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. + </p></dd><dt><span class="term"><code class="literal">projectFile</code></span></dt><dd><p> + Optional attribute. It specifies the name of a project file. + Project files are created by the <span class="application">FindBugs</span> GUI, and specify classes, + aux classpath entries, and source directories. By naming a project, + you don't need to specify any <code class="literal">class</code> elements, + nor do you need to specify <code class="literal">auxClasspath</code> or + <code class="literal">sourcePath</code> attributes. + See <a class="xref" href="running.html" title="Chapter 4. Running FindBugs™">Chapter 4, <i>Running <span class="application">FindBugs</span>™</i></a> for how to create a project. + </p></dd><dt><span class="term"><code class="literal">jvmargs</code></span></dt><dd><p> + Optional attribute. It specifies any arguments that should be passed + to the Java virtual machine used to run <span class="application">FindBugs</span>. You may need to + use this attribute to specify flags to increase the amount of memory + the JVM may use if you are analyzing a very large program. + </p></dd><dt><span class="term"><code class="literal">systemProperty</code></span></dt><dd><p> + Optional nested element. If specified, defines a system property. + The <code class="literal">name</code> attribute specifies the name of the + system property, and the <code class="literal">value</code> attribute specifies + the value of the system property. + </p></dd><dt><span class="term"><code class="literal">timeout</code></span></dt><dd><p> + Optional attribute. It specifies the amount of time, in milliseconds, + that the Java process executing <span class="application">FindBugs</span> may run before it is + assumed to be hung and is terminated. The default is 600,000 + milliseconds, which is ten minutes. Note that for very large + programs, <span class="application">FindBugs</span> may require more than ten minutes to complete its + analysis. + </p></dd><dt><span class="term"><code class="literal">failOnError</code></span></dt><dd><p> + Optional boolean attribute. Whether to abort the build process if there is an + error running <span class="application">FindBugs</span>. Defaults to "false" + </p></dd><dt><span class="term"><code class="literal">errorProperty</code></span></dt><dd><p> + Optional attribute which specifies the name of a property that + will be set to "true" if an error occurs while running <span class="application">FindBugs</span>. + </p></dd><dt><span class="term"><code class="literal">warningsProperty</code></span></dt><dd><p> + Optional attribute which specifies the name of a property + that will be set to "true" if any warnings are reported by + <span class="application">FindBugs</span> on the analyzed program. + </p></dd><dt><span class="term"><code class="literal">userPreferencesFile</code></span></dt><dd><p> + Optional attribute. Set the path of the user preferences file to use, which might override some of the options abobe. + Specifying <code class="literal">userPreferencesFile</code> as first argument would mean some later + options will override them, as last argument would mean they will override some previous options). + This rationale behind this option is to reuse FindBugs Eclipse project settings for command + line execution. + </p></dd></dl></div><p> + + +</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gui.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="eclipse.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Using the <span class="application">FindBugs</span> GUI </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Using the <span class="application">FindBugs</span>™ Eclipse plugin</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/building.html b/tools/findbugs/doc/manual/building.html new file mode 100644 index 0000000..ed3fcb2 --- /dev/null +++ b/tools/findbugs/doc/manual/building.html @@ -0,0 +1,123 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 3. Building FindBugs™ from Source</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="installing.html" title="Chapter 2. Installing FindBugs™"><link rel="next" href="running.html" title="Chapter 4. Running FindBugs™"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Building <span class="application">FindBugs</span>™ from Source</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="installing.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="running.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 3. Building FindBugs™ from Source"><div class="titlepage"><div><div><h2 class="title"><a name="building"></a>Chapter 3. Building <span class="application">FindBugs</span>™ from Source</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="building.html#d0e173">1. Prerequisites</a></span></dt><dt><span class="sect1"><a href="building.html#d0e262">2. Extracting the Source Distribution</a></span></dt><dt><span class="sect1"><a href="building.html#d0e275">3. Modifying <code class="filename">local.properties</code></a></span></dt><dt><span class="sect1"><a href="building.html#d0e333">4. Running <span class="application">Ant</span></a></span></dt><dt><span class="sect1"><a href="building.html#d0e427">5. Running <span class="application">FindBugs</span>™ from a source directory</a></span></dt></dl></div><p> +This chapter describes how to build <span class="application">FindBugs</span> from source code. Unless you are +interesting in modifying <span class="application">FindBugs</span>, you will probably want to skip to the +<a class="link" href="running.html" title="Chapter 4. Running FindBugs™">next chapter</a>. +</p><div class="sect1" title="1. Prerequisites"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e173"></a>1. Prerequisites</h2></div></div></div><p> +To compile <span class="application">FindBugs</span> from source, you will need the following: +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + The <a class="ulink" href="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3-source.zip?download" target="_top"><span class="application">FindBugs</span> source distribution</a> + </p></li><li class="listitem"><p> + <a class="ulink" href="http://java.sun.com/j2se/" target="_top">JDK 1.5.0 or later</a> + </p></li><li class="listitem"><p> + <a class="ulink" href="http://ant.apache.org/" target="_top">Apache <span class="application">Ant</span></a>, version 1.6.3 or later + </p></li></ul></div><p> +</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p> + The version of <span class="application">Ant</span> included as <code class="filename">/usr/bin/ant</code> on + Redhat Linux systems will <span class="emphasis"><em>not</em></span> work for compiling + <span class="application">FindBugs</span>. We recommend you install a binary distribution of <span class="application">Ant</span> + downloaded from the <a class="ulink" href="http://ant.apache.org/" target="_top"><span class="application">Ant</span> website</a>. + Make sure that when you run <span class="application">Ant</span> your <em class="replaceable"><code>JAVA_HOME</code></em> + environment variable points to the directory in which you installed + JDK 1.5 (or later). + </p></td></tr></table></div><p> +If you want to be able to generate formatted versions of the <span class="application">FindBugs</span> documentation, +you will also need the following software: +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + The <a class="ulink" href="http://docbook.sourceforge.net/projects/xsl/index.html" target="_top">DocBook XSL Stylesheets</a>. + These are required to convert the <span class="application">FindBugs</span> manual into HTML format. + </p></li><li class="listitem"><p> + The <a class="ulink" href="http://saxon.sourceforge.net/" target="_top"><span class="application">Saxon</span> XSLT Processor</a>. + (Also required for converting the <span class="application">FindBugs</span> manual to HTML.) + </p></li></ul></div><p> +</p></div><div class="sect1" title="2. Extracting the Source Distribution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e262"></a>2. Extracting the Source Distribution</h2></div></div></div><p> +After you download the source distribution, you'll need to extract it into +a working directory. A typical command to do this is: + +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong>unzip findbugs-2.0.3-source.zip</strong></span> +</pre><p> + +</p></div><div class="sect1" title="3. Modifying local.properties"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e275"></a>3. Modifying <code class="filename">local.properties</code></h2></div></div></div><p> +If you intend to build the FindBugs documentation, +you will need to modify the <code class="filename">local.properties</code> file +used by the <a class="ulink" href="http://ant.apache.org/" target="_top"><span class="application">Ant</span></a> +<code class="filename">build.xml</code> file to build <span class="application">FindBugs</span>. +If you do not want to build the FindBugs documentation, then you +can ignore this file. +</p><p> +The <code class="filename">local.properties</code> overrides definitions +in the <code class="filename">build.properties</code> file. +The <code class="filename">build.properties</code> file looks something like this: +</p><pre class="programlisting"> + +# User Configuration: +# This section must be modified to reflect your system. + +local.software.home =/export/home/daveho/linux + +# Set this to the directory containing the DocBook Modular XSL Stylesheets +# from http://docbook.sourceforge.net/projects/xsl/ + +xsl.stylesheet.home =${local.software.home}/docbook/docbook-xsl-1.71.1 + +# Set this to the directory where Saxon (http://saxon.sourceforge.net/) +# is installed. + +saxon.home =${local.software.home}/java/saxon-6.5.5 + +</pre><p> +</p><p> +The <code class="varname">xsl.stylesheet.home</code> property specifies the full +path to the directory where you have installed the +<a class="ulink" href="http://docbook.sourceforge.net/projects/xsl/" target="_top">DocBook Modular XSL +Stylesheets</a>. You only need to specify this property if you will be +generating the <span class="application">FindBugs</span> documentation. +</p><p> +The <code class="varname">saxon.home</code> property is the full path to the +directory where you installed the <a class="ulink" href="http://saxon.sourceforge.net/" target="_top"><span class="application">Saxon</span> XSLT Processor</a>. +You only need to specify this property if you will be +generating the <span class="application">FindBugs</span> documentation. +</p></div><div class="sect1" title="4. Running Ant"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e333"></a>4. Running <span class="application">Ant</span></h2></div></div></div><p> +Once you have extracted the source distribution, +made sure that <span class="application">Ant</span> is installed, +modified <code class="filename">build.properties</code> (optional), +and configured the tools (such as <span class="application">Saxon</span>), +you are ready to build <span class="application">FindBugs</span>. Invoking <span class="application">Ant</span> is a simple matter +of running the command +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong>ant <em class="replaceable"><code>target</code></em></strong></span> +</pre><p> +where <em class="replaceable"><code>target</code></em> is one of the following: +</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>build</strong></span></span></dt><dd><p> + This target compiles the code for <span class="application">FindBugs</span>. It is the default target. + </p></dd><dt><span class="term"><span class="command"><strong>docs</strong></span></span></dt><dd><p> + This target formats the documentation. (It also compiles some of + the source code as a side-effect.) + </p></dd><dt><span class="term"><span class="command"><strong>runjunit</strong></span></span></dt><dd><p> + This target compiles and runs the internal JUnit tests included + in <span class="application">FindBugs</span>. It will print an error message if any unit + tests fail. + </p></dd><dt><span class="term"><span class="command"><strong>bindist</strong></span></span></dt><dd><p> + Builds a binary distribution of <span class="application">FindBugs</span>. + The target creates both <code class="filename">.zip</code> and + <code class="filename">.tar.gz</code> archives. + </p></dd></dl></div><p> +</p><p> +After running an <span class="application">Ant</span> command, you should see output similar to +the following (after some other messages regarding the tasks that +<span class="application">Ant</span> is running): +</p><pre class="screen"> +<code class="computeroutput"> +BUILD SUCCESSFUL +Total time: 17 seconds +</code> +</pre><p> +</p></div><div class="sect1" title="5. Running FindBugs™ from a source directory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e427"></a>5. Running <span class="application">FindBugs</span>™ from a source directory</h2></div></div></div><p> +The <span class="application">Ant</span> build script for <span class="application">FindBugs</span> is written such that after +building the <span class="command"><strong>build</strong></span> target, the working directory +is set up just like a binary distribution. So, the information about +running <span class="application">FindBugs</span> in <a class="xref" href="running.html" title="Chapter 4. Running FindBugs™">Chapter 4, <i>Running <span class="application">FindBugs</span>™</i></a> +applies to source distributions, too. +</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installing.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="running.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Installing <span class="application">FindBugs</span>™ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Running <span class="application">FindBugs</span>™</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/datamining.html b/tools/findbugs/doc/manual/datamining.html new file mode 100644 index 0000000..134801a --- /dev/null +++ b/tools/findbugs/doc/manual/datamining.html @@ -0,0 +1,421 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 12. Data mining of bugs with FindBugs™</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="rejarForAnalysis.html" title="Chapter 11. Using rejarForAnalysis"><link rel="next" href="license.html" title="Chapter 13. License"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. Data mining of bugs with <span class="application">FindBugs</span>™</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="rejarForAnalysis.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="license.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 12. Data mining of bugs with FindBugs™"><div class="titlepage"><div><div><h2 class="title"><a name="datamining"></a>Chapter 12. Data mining of bugs with <span class="application">FindBugs</span>™</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="datamining.html#commands">1. Commands</a></span></dt><dt><span class="sect1"><a href="datamining.html#examples">2. Examples</a></span></dt><dt><span class="sect1"><a href="datamining.html#antexample">3. Ant example</a></span></dt></dl></div><p> +FindBugs incorporates an ability to perform sophisticated queries on bug +databases and track warnings across multiple versions of code being +studied, allowing you to do things such as seeing when a bug was first introduced, examining +just the warnings that have been introduced since the last release, or graphing the number +of infinite recursive loops in your code over time.</p><p> +These techniques all depend upon the XML format used by FindBugs for storing warnings. +These XML files usually contain just the warnings from one particular analysis run, but +they can also store the results from analyzing a sequence of software builds or versions. + </p><p> +Any FindBugs XML bug database contains a version name and timestamp. +FindBugs tries to compute a timestamp from the timestamps of the files that +are analyzed (e.g., the timestamp is intended to be the time the class files +were generated, not analyzed). Each bug database also contains a version name. +Both the version name and timestamp can be set manually using the +<span class="command"><strong>setBugDatabaseInfo</strong></span> (<a class="xref" href="datamining.html#setBugDatabaseInfo" title="1.7. setBugDatabaseInfo">Section 1.7, “setBugDatabaseInfo”</a>) command. + </p><p>A multiversion bug database assigns a sequence number to each version of +the analyzed code. These sequence numbers are simply successive integers, +starting at 0 (e.g., a bug database for 4 versions of the code will contain +versions 0..3). The bug database will also record the name and timestamp for +each version. The <span class="command"><strong>filterBugs</strong></span> command allows you to refer +to a version by sequence number, name or timestamp.</p><p> +You can take a sequence (or pair) of single version bug databases and create +from them a multiversion bug database, or combine a multiversion bug database +with a sequence of later single-version bug databases.</p><p> +Some of these commands can be invoked as ant tasks. See below for specifics +on how to invoke them and what attributes and arguments they take. All of +the examples assume that the <code class="literal">findbugs.lib</code> +<code class="literal">refid</code> is set correctly. Here is one way to set it: +</p><pre class="programlisting"> + + <!-- findbugs task definition --> + <property name="findbugs.home" value="/your/path/to/findbugs" /> + <path id="findbugs.lib"> + <fileset dir="${findbugs.home}/lib"> + <include name="findbugs-ant.jar"/> + </fileset> + </path> + +</pre><div class="sect1" title="1. Commands"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="commands"></a>1. Commands</h2></div></div></div><p> +All tools for FindBugs data mining are can be invoked from the command line, +and some of the more useful tools can also be invoked from an +ant build file.</p><p> +Briefly, the command-line tools are:</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#unionBugs" title="1.1. unionBugs">unionBugs</a></strong></span></span></dt><dd><p> + combine the results from separate analysis of disjoint + classes + </p></dd><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#computeBugHistory" title="1.2. computeBugHistory">computeBugHistory</a></strong></span></span></dt><dd><p>Merge bug warnings from multiple versions of + analyzed code into + a single multiversion bug database. This can either be used + to add more versions to an existing multiversion database, + or to create a multiversion database from a sequence of single version + bug warning databases.</p></dd><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#setBugDatabaseInfo" title="1.7. setBugDatabaseInfo">setBugDatabaseInfo</a></strong></span></span></dt><dd><p>Set information such as the revision name or +timestamp in an XML bug database</p></dd><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#listBugDatabaseInfo" title="1.8. listBugDatabaseInfo">listBugDatabaseInfo</a></strong></span></span></dt><dd><p>List information such as the revision name and +timestamp for a list of XML bug databases</p></dd><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#filterBugs" title="1.3. filterBugs">filterBugs</a></strong></span></span></dt><dd><p>Select a subset of a bug database</p></dd><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#mineBugHistory" title="1.4. mineBugHistory">mineBugHistory</a></strong></span></span></dt><dd><p>Generate a tabular listing of the number of warnings in each + version of a multiversion bug database</p></dd><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#defectDensity" title="1.5. defectDensity">defectDensity</a></strong></span></span></dt><dd><p>List information about defect density + (warnings per 1000 NCSS) + for the entire project and each class and package</p></dd><dt><span class="term"><span class="command"><strong><a class="link" href="datamining.html#convertXmlToText" title="1.6. convertXmlToText">convertXmlToText</a></strong></span></span></dt><dd><p>Convert bug warnings in XML format to + a textual one-line-per-bug format, or to HTML</p></dd></dl></div><div class="sect2" title="1.1. unionBugs"><div class="titlepage"><div><div><h3 class="title"><a name="unionBugs"></a>1.1. unionBugs</h3></div></div></div><p> + If you have, for example, separately analyzing each jar file used in an application, + you can use this command to combine the separately generated xml bug warning files into + a single file containing all of the warnings.</p><p>Do <span class="emphasis"><em>not</em></span> use this command to combine results from analyzing different versions of the same + file; use <span class="command"><strong>computeBugHistory</strong></span> instead.</p><p>Specify the xml files on the command line. The result is sent to standard output.</p></div><div class="sect2" title="1.2. computeBugHistory"><div class="titlepage"><div><div><h3 class="title"><a name="computeBugHistory"></a>1.2. computeBugHistory</h3></div></div></div><p>Use this command to generate a bug database containing information from different builds or versions +of software you are analyzing. +History is taken from the first file provided as input; any following +files should be single version bug databases (if they contain history, the history in those +files will be ignored).</p><p>By default, output is written to the standard output. +</p><p>This functionality may also can be accessed from ant. +First create a taskdef for <span class="command"><strong>computeBugHistory</strong></span> in your +build file: +</p><pre class="programlisting"> + +<taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask"> + <classpath refid="findbugs.lib" /> +</taskdef> + +</pre><p>Attributes for this ant task are listed in the following table. +To specify input files, nest them inside with a +<code class="literal"><datafile></code> element. For example: +</p><pre class="programlisting"> + +<computeBugHistory home="${findbugs.home}" ...> + <datafile name="analyze1.xml"/> + <datafile name="analyze2.xml"/> +</computeBugHistory> + +</pre><div class="table"><a name="computeBugHistoryTable"></a><p class="title"><b>Table 12.1. Options for computeBugHistory command</b></p><div class="table-contents"><table summary="Options for computeBugHistory command" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Command-line option</th><th align="left">Ant attribute</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left">-output <file></td><td align="left">output="<file>"</td><td align="left">save output in the named file (may also be an input file)</td></tr><tr><td align="left">-overrideRevisionNames[:truth]</td><td align="left">overrideRevisionNames="[true|false]"</td><td align="left">override revision names for each version with names computed from the filenames</td></tr><tr><td align="left">-noPackageMoves[:truth]</td><td align="left">noPackageMoves="[true|false]"</td><td align="left">if a class has moved to another package, treat warnings in that class as seperate</td></tr><tr><td align="left">-preciseMatch[:truth]</td><td align="left">preciseMatch="[true|false]"</td><td align="left">require bug patterns to match precisely</td></tr><tr><td align="left">-precisePriorityMatch[:truth]</td><td align="left">precisePriorityMatch="[true|false]"</td><td align="left">consider two warnings as the same only if priorities match exactly</td></tr><tr><td align="left">-quiet[:truth]</td><td align="left">quiet="[true|false]"</td><td align="left">don't generate any output to standard out unless there is an error</td></tr><tr><td align="left">-withMessages[:truth]</td><td align="left">withMessages="[true|false]"</td><td align="left">include human-readable messages describing the warnings in XML output</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="1.3. filterBugs"><div class="titlepage"><div><div><h3 class="title"><a name="filterBugs"></a>1.3. filterBugs</h3></div></div></div><p>This command is used to select a subset of warnings from a FindBugs XML warning file +and write the selected subset to a new FindBugs warning file.</p><p> +This command takes a sequence of options, and either zero, one or two +filenames of findbugs xml bug files on the command line.</p><p>If no file names are provided, the command reads from standard input +and writes to standard output. If one file name is provided, +it reads from the file and writes to standard output. +If two file names are provided, it reads from the first and writes the output +to the second file name.</p><p>This functionality may also can be accessed from ant. +First create a taskdef for <span class="command"><strong>filterBugs</strong></span> in your +build file: +</p><pre class="programlisting"> + +<taskdef name="filterBugs" classname="edu.umd.cs.findbugs.anttask.FilterBugsTask"> + <classpath refid="findbugs.lib" /> +</taskdef> + +</pre><p>Attributes for this ant task are listed in the following table. +To specify an input file either use the input attribute or nest it inside +the ant call with a <code class="literal"><datafile></code> element. For example: +</p><pre class="programlisting"> + +<filterBugs home="${findbugs.home}" ...> + <datafile name="analyze.xml"/> +</filterBugs> + +</pre><div class="table"><a name="filterOptionsTable"></a><p class="title"><b>Table 12.2. Options for filterBugs command</b></p><div class="table-contents"><table summary="Options for filterBugs command" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Command-line option</th><th align="left">Ant attribute</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"> </td><td align="left">input="<file>"</td><td align="left">use file as input</td></tr><tr><td align="left"> </td><td align="left">output="<file>"</td><td align="left">output results to file</td></tr><tr><td align="left">-not</td><td align="left">not="[true|false]"</td><td align="left">reverse (all) switches for the filter</td></tr><tr><td align="left">-withSource[:truth]</td><td align="left">withSource="[true|false]"</td><td align="left">only warnings for switch source is available</td></tr><tr><td align="left">-exclude <filter file></td><td align="left">exclude="<filter file>"</td><td align="left">exclude bugs matching given filter</td></tr><tr><td align="left">-include <filter file></td><td align="left">include="<filter file>"</td><td align="left">include only bugs matching given filter</td></tr><tr><td align="left">-annotation <text></td><td align="left">annotation="<text>"</td><td align="left">allow only warnings containing this text in a manual annotation</td></tr><tr><td align="left">-after <when></td><td align="left">after="<when>"</td><td align="left">allow only warnings that first occurred after this version</td></tr><tr><td align="left">-before <when></td><td align="left">before="<when>"</td><td align="left">allow only warnings that first occurred before this version</td></tr><tr><td align="left">-first <when></td><td align="left">first="<when>"</td><td align="left">allow only warnings that first occurred in this version</td></tr><tr><td align="left">-last <when></td><td align="left">last="<when>"</td><td align="left">allow only warnings that last occurred in this version</td></tr><tr><td align="left">-fixed <when></td><td align="left">fixed="<when>"</td><td align="left">allow only warnings that last occurred in the previous version (clobbers <code class="option">-last</code>)</td></tr><tr><td align="left">-present <when></td><td align="left">present="<when>"</td><td align="left">allow only warnings present in this version</td></tr><tr><td align="left">-absent <when></td><td align="left">absent="<when>"</td><td align="left">allow only warnings absent in this version</td></tr><tr><td align="left">-active[:truth]</td><td align="left">active="[true|false]"</td><td align="left">allow only warnings alive in the last sequence number</td></tr><tr><td align="left">-introducedByChange[:truth]</td><td align="left">introducedByChange="[true|false]"</td><td align="left">allow only warnings introduced by a change of an existing class</td></tr><tr><td align="left">-removedByChange[:truth]</td><td align="left">removedByChange="[true|false]"</td><td align="left">allow only warnings removed by a change of a persisting class</td></tr><tr><td align="left">-newCode[:truth]</td><td align="left">newCode="[true|false]"</td><td align="left">allow only warnings introduced by the addition of a new class</td></tr><tr><td align="left">-removedCode[:truth]</td><td align="left">removedCode="[true|false]"</td><td align="left">allow only warnings removed by removal of a class</td></tr><tr><td align="left">-priority <level></td><td align="left">priority="<level>"</td><td align="left">allow only warnings with this priority or higher</td></tr><tr><td align="left">-maxRank <rank></td><td align="left">rank="[1..20]"</td><td align="left">allow only warnings with this rank or lower</td></tr><tr><td align="left">-class <pattern></td><td align="left">class="<class>"</td><td align="left">allow only bugs whose primary class name matches this pattern</td></tr><tr><td align="left">-bugPattern <pattern></td><td align="left">bugPattern="<pattern>"</td><td align="left">allow only bugs whose type matches this pattern</td></tr><tr><td align="left">-category <category></td><td align="left">category="<category>"</td><td align="left">allow only warnings with a category that starts with this string</td></tr><tr><td align="left">-designation <designation></td><td align="left">designation="<designation>"</td><td align="left">allow only warnings with this designation (e.g., -designation SHOULD_FIX)</td></tr><tr><td align="left">-withMessages[:truth] </td><td align="left">withMessages="[true|false]"</td><td align="left">the generated XML should contain textual messages</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="1.4. mineBugHistory"><div class="titlepage"><div><div><h3 class="title"><a name="mineBugHistory"></a>1.4. mineBugHistory</h3></div></div></div><p>This command generates a table containing counts of the numbers of warnings +in each version of a multiversion bug database.</p><p>This functionality may also can be accessed from ant. +First create a taskdef for <span class="command"><strong>mineBugHistory</strong></span> in your +build file: +</p><pre class="programlisting"> + +<taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask"> + <classpath refid="findbugs.lib" /> +</taskdef> + +</pre><p>Attributes for this ant task are listed in the following table. +To specify an input file either use the <code class="literal">input</code> +attribute or nest it inside the ant call with a +<code class="literal"><datafile></code> element. For example: +</p><pre class="programlisting"> + +<mineBugHistory home="${findbugs.home}" ...> + <datafile name="analyze.xml"/> +</mineBugHistory> + +</pre><div class="table"><a name="mineBugHistoryOptionsTable"></a><p class="title"><b>Table 12.3. Options for mineBugHistory command</b></p><div class="table-contents"><table summary="Options for mineBugHistory command" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Command-line option</th><th align="left">Ant attribute</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"> </td><td align="left">input="<file>"</td><td align="left">use file as input</td></tr><tr><td align="left"> </td><td align="left">output="<file>"</td><td align="left">write output to file</td></tr><tr><td align="left">-formatDates</td><td align="left">formatDates="[true|false]"</td><td align="left">render dates in textual form</td></tr><tr><td align="left">-noTabs</td><td align="left">noTabs="[true|false]"</td><td align="left">delimit columns with groups of spaces instead of tabs (see below)</td></tr><tr><td align="left">-summary</td><td align="left">summary="[true|false]"</td><td align="left">output terse summary of changes over the last ten entries</td></tr></tbody></table></div></div><br class="table-break"><p> + The <code class="option">-noTabs</code> output can be easier to read from a shell + with a fixed-width font. + Because numeric columns are right-justified, spaces may precede the + first column value. This option also causes <code class="option">-formatDates</code> + to render dates in terser format without embedded whitespace. + </p><p>The table is a tab-separated (barring <code class="option">-noTabs</code>) + table with the following columns:</p><div class="table"><a name="mineBugHistoryColumns"></a><p class="title"><b>Table 12.4. Columns in mineBugHistory output</b></p><div class="table-contents"><table summary="Columns in mineBugHistory output" border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Title</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left">seq</td><td align="left">Sequence number (successive integers, starting at 0)</td></tr><tr><td align="left">version</td><td align="left">Version name</td></tr><tr><td align="left">time</td><td align="left">Release timestamp</td></tr><tr><td align="left">classes</td><td align="left">Number of classes analyzed</td></tr><tr><td align="left">NCSS</td><td align="left">Non Commenting Source Statements</td></tr><tr><td align="left">added</td><td align="left">Count of new warnings for a class that existed in the previous version</td></tr><tr><td align="left">newCode</td><td align="left">Count of new warnings for a class that did not exist in the previous version</td></tr><tr><td align="left">fixed</td><td align="left">Count of warnings removed from a class that remains in the current version</td></tr><tr><td align="left">removed</td><td align="left">Count of warnings in the previous version for a class that is not present in the current version</td></tr><tr><td align="left">retained</td><td align="left">Count of warnings that were in both the previous and current version</td></tr><tr><td align="left">dead</td><td align="left">Warnings that were present in earlier versions but in neither the current version or the immediately preceeding version</td></tr><tr><td align="left">active</td><td align="left">Total warnings present in the current version</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="1.5. defectDensity"><div class="titlepage"><div><div><h3 class="title"><a name="defectDensity"></a>1.5. defectDensity</h3></div></div></div><p> +This command lists information about defect density (warnings per 1000 NCSS) for the entire project and each class and package. +It can either be invoked with no files specified on the command line (in which case it reads from standard input) +or with one file specified on the command line.</p><p>It generates a table with the following columns, and with one +row for the entire project, and one row for each package or class that contains at least +4 warnings.</p><div class="table"><a name="defectDensityColumns"></a><p class="title"><b>Table 12.5. Columns in defectDensity output</b></p><div class="table-contents"><table summary="Columns in defectDensity output" border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Title</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left">kind</td><td align="left">project, package or class</td></tr><tr><td align="left">name</td><td align="left">The name of the project, package or class</td></tr><tr><td align="left">density</td><td align="left">Number of warnings generated per 1000 lines of NCSS.</td></tr><tr><td align="left">bugs</td><td align="left">Number of warnings</td></tr><tr><td align="left">NCSS</td><td align="left">Calculated number of NCSS</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="1.6. convertXmlToText"><div class="titlepage"><div><div><h3 class="title"><a name="convertXmlToText"></a>1.6. convertXmlToText</h3></div></div></div><p> + This command converts a warning collection in XML format to a text + format with one line per warning, or to HTML. + </p><p>This functionality may also can be accessed from ant. +First create a taskdef for <span class="command"><strong>convertXmlToText</strong></span> in your +build file: +</p><pre class="programlisting"> + +<taskdef name="convertXmlToText" classname="edu.umd.cs.findbugs.anttask.ConvertXmlToTextTask"> + <classpath refid="findbugs.lib" /> +</taskdef> + +</pre><p>Attributes for this ant task are listed in the following table.</p><div class="table"><a name="convertXmlToTextTable"></a><p class="title"><b>Table 12.6. Options for convertXmlToText command</b></p><div class="table-contents"><table summary="Options for convertXmlToText command" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Command-line option</th><th align="left">Ant attribute</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"> </td><td align="left">input="<filename>"</td><td align="left">use file as input</td></tr><tr><td align="left"> </td><td align="left">output="<filename>"</td><td align="left">output results to file</td></tr><tr><td align="left">-longBugCodes</td><td align="left">longBugCodes="[true|false]"</td><td align="left">use the full bug pattern code instead of two-letter abbreviation</td></tr><tr><td align="left"> </td><td align="left">format="text"</td><td align="left">generate plain text output with one bug per line (command-line default)</td></tr><tr><td align="left">-html[:stylesheet]</td><td align="left">format="html:<stylesheet>"</td><td align="left">generate output with specified stylesheet (see below), or default.xsl if unspecified</td></tr></tbody></table></div></div><br class="table-break"><p> + You may specify plain.xsl, default.xsl, fancy.xsl, fancy-hist.xsl, + or your own XSL stylesheet for the -html/format option. + Despite the name of this option, you may specify + a stylesheet that emits something other than html. + When applying a stylesheet other than those included + with FindBugs (listed above), the -html/format option should be used + with a path or URL to the stylesheet. + </p></div><div class="sect2" title="1.7. setBugDatabaseInfo"><div class="titlepage"><div><div><h3 class="title"><a name="setBugDatabaseInfo"></a>1.7. setBugDatabaseInfo</h3></div></div></div><p> + This command sets meta-information in a specified warning collection. + It takes the following options: + </p><p>This functionality may also can be accessed from ant. +First create a taskdef for <span class="command"><strong>setBugDatabaseInfo</strong></span> in your +build file: +</p><pre class="programlisting"> + +<taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask"> + <classpath refid="findbugs.lib" /> +</taskdef> + +</pre><p>Attributes for this ant task are listed in the following table. +To specify an input file either use the <code class="literal">input</code> +attribute or nest it inside the ant call with a +<code class="literal"><datafile></code> element. For example: +</p><pre class="programlisting"> + +<setBugDatabaseInfo home="${findbugs.home}" ...> + <datafile name="analyze.xml"/> +</setBugDatabaseInfo> + +</pre><div class="table"><a name="setBugDatabaseInfoOptions"></a><p class="title"><b>Table 12.7. setBugDatabaseInfo Options</b></p><div class="table-contents"><table summary="setBugDatabaseInfo Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Command-line option</th><th align="left">Ant attribute</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"> </td><td align="left">input="<file>"</td><td align="left">use file as input</td></tr><tr><td align="left"> </td><td align="left">output="<file>"</td><td align="left">write output to file</td></tr><tr><td align="left">-name <name></td><td align="left">name="<name>"</td><td align="left">set name for (last) revision</td></tr><tr><td align="left">-timestamp <when></td><td align="left">timestamp="<when>"</td><td align="left">set timestamp for (last) revision</td></tr><tr><td align="left">-source <directory></td><td align="left">source="<directory>"</td><td align="left">add specified directory to the source search path</td></tr><tr><td align="left">-findSource <directory></td><td align="left">findSource="<directory>"</td><td align="left">find and add all relevant source directions contained within specified directory</td></tr><tr><td align="left">-suppress <filter file></td><td align="left">suppress="<filter file>"</td><td align="left">suppress warnings matched by this file (replaces previous suppressions)</td></tr><tr><td align="left">-withMessages</td><td align="left">withMessages="[true|false]"</td><td align="left">add textual messages to XML</td></tr><tr><td align="left">-resetSource</td><td align="left">resetSource="[true|false]"</td><td align="left">remove all source search paths</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="1.8. listBugDatabaseInfo"><div class="titlepage"><div><div><h3 class="title"><a name="listBugDatabaseInfo"></a>1.8. listBugDatabaseInfo</h3></div></div></div><p>This command takes a list of zero or more xml bug database filenames on the command line. +If zero file names are provided, it reads from standard input and does not generate +a table header.</p><p>There is only one option: <code class="option">-formatDates</code> renders dates + in textual form. + </p><p>The output is a table one row per bug database and the following columns:</p><div class="table"><a name="listBugDatabaseInfoColumns"></a><p class="title"><b>Table 12.8. listBugDatabaseInfo Columns</b></p><div class="table-contents"><table summary="listBugDatabaseInfo Columns" border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Column</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left">version</td><td align="left">version name</td></tr><tr><td align="left">time</td><td align="left">Release timestamp</td></tr><tr><td align="left">classes</td><td align="left">Number of classes analyzed</td></tr><tr><td align="left">NCSS</td><td align="left">Non Commenting Source Statements analyzed</td></tr><tr><td align="left">total</td><td align="left">Total number of warnings of all kinds</td></tr><tr><td align="left">high</td><td align="left">Total number of high priority warnings of all kinds</td></tr><tr><td align="left">medium</td><td align="left">Total number of medium/normal priority warnings of all kinds</td></tr><tr><td align="left">low</td><td align="left">Total number of low priority warnings of all kinds</td></tr><tr><td align="left">filename</td><td align="left">filename of database</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="sect1" title="2. Examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="examples"></a>2. Examples</h2></div></div></div><div class="sect2" title="2.1. Mining history using proveded shell scrips"><div class="titlepage"><div><div><h3 class="title"><a name="unixscriptsexamples"></a>2.1. Mining history using proveded shell scrips</h3></div></div></div><p>In all of the following, the commands are given in a directory that contains +directories jdk1.6.0-b12, jdk1.6.0-b13, ..., jdk1.6.0-b60.</p><p>You can use the command:</p><pre class="screen"> +computeBugHistory jdk1.6.0-b* | filterBugs -bugPattern IL_ | mineBugHistory -formatDates +</pre><p>to generate the following output:</p><pre class="screen"> +seq version time classes NCSS added newCode fixed removed retained dead active +0 jdk1.6.0-b12 "Thu Nov 11 09:07:20 EST 2004" 13128 811569 0 4 0 0 0 0 4 +1 jdk1.6.0-b13 "Thu Nov 18 06:02:06 EST 2004" 13128 811570 0 0 0 0 4 0 4 +2 jdk1.6.0-b14 "Thu Dec 02 06:12:26 EST 2004" 13145 811786 0 0 2 0 2 0 2 +3 jdk1.6.0-b15 "Thu Dec 09 06:07:04 EST 2004" 13174 811693 0 0 1 0 1 2 1 +4 jdk1.6.0-b16 "Thu Dec 16 06:21:28 EST 2004" 13175 811715 0 0 0 0 1 3 1 +5 jdk1.6.0-b17 "Thu Dec 23 06:27:22 EST 2004" 13176 811974 0 0 0 0 1 3 1 +6 jdk1.6.0-b19 "Thu Jan 13 06:41:16 EST 2005" 13176 812011 0 0 0 0 1 3 1 +7 jdk1.6.0-b21 "Thu Jan 27 05:57:52 EST 2005" 13177 812173 0 0 0 0 1 3 1 +8 jdk1.6.0-b23 "Thu Feb 10 05:44:36 EST 2005" 13179 812188 0 0 0 0 1 3 1 +9 jdk1.6.0-b26 "Thu Mar 03 06:04:02 EST 2005" 13199 811770 0 0 0 0 1 3 1 +10 jdk1.6.0-b27 "Thu Mar 10 04:48:38 EST 2005" 13189 812440 0 0 0 0 1 3 1 +11 jdk1.6.0-b28 "Thu Mar 17 02:54:22 EST 2005" 13185 812056 0 0 0 0 1 3 1 +12 jdk1.6.0-b29 "Thu Mar 24 03:09:20 EST 2005" 13117 809468 0 0 0 0 1 3 1 +13 jdk1.6.0-b30 "Thu Mar 31 02:53:32 EST 2005" 13118 809501 0 0 0 0 1 3 1 +14 jdk1.6.0-b31 "Thu Apr 07 03:00:14 EDT 2005" 13117 809572 0 0 0 0 1 3 1 +15 jdk1.6.0-b32 "Thu Apr 14 02:56:56 EDT 2005" 13169 811096 0 0 0 0 1 3 1 +16 jdk1.6.0-b33 "Thu Apr 21 02:46:22 EDT 2005" 13187 811942 0 0 0 0 1 3 1 +17 jdk1.6.0-b34 "Thu Apr 28 02:49:00 EDT 2005" 13195 813488 0 1 0 0 1 3 2 +18 jdk1.6.0-b35 "Thu May 05 02:49:04 EDT 2005" 13457 829837 0 0 0 0 2 3 2 +19 jdk1.6.0-b36 "Thu May 12 02:59:46 EDT 2005" 13462 831278 0 0 0 0 2 3 2 +20 jdk1.6.0-b37 "Thu May 19 02:55:08 EDT 2005" 13464 831971 0 0 0 0 2 3 2 +21 jdk1.6.0-b38 "Thu May 26 03:08:16 EDT 2005" 13564 836565 0 0 0 0 2 3 2 +22 jdk1.6.0-b39 "Fri Jun 03 03:10:48 EDT 2005" 13856 849992 0 1 0 0 2 3 3 +23 jdk1.6.0-b40 "Thu Jun 09 03:30:28 EDT 2005" 15972 959619 0 2 0 0 3 3 5 +24 jdk1.6.0-b41 "Thu Jun 16 03:19:22 EDT 2005" 15972 959619 0 0 0 0 5 3 5 +25 jdk1.6.0-b42 "Fri Jun 24 03:38:54 EDT 2005" 15966 958581 0 0 0 0 5 3 5 +26 jdk1.6.0-b43 "Thu Jul 14 03:09:34 EDT 2005" 16041 960544 0 0 0 0 5 3 5 +27 jdk1.6.0-b44 "Thu Jul 21 03:05:54 EDT 2005" 16041 960547 0 0 0 0 5 3 5 +28 jdk1.6.0-b45 "Thu Jul 28 03:26:10 EDT 2005" 16037 960606 0 0 1 0 4 3 4 +29 jdk1.6.0-b46 "Thu Aug 04 03:02:48 EDT 2005" 15936 951355 0 0 0 0 4 4 4 +30 jdk1.6.0-b47 "Thu Aug 11 03:18:56 EDT 2005" 15964 952387 0 0 1 0 3 4 3 +31 jdk1.6.0-b48 "Thu Aug 18 08:10:40 EDT 2005" 15970 953421 0 0 0 0 3 5 3 +32 jdk1.6.0-b49 "Thu Aug 25 03:24:38 EDT 2005" 16048 958940 0 0 0 0 3 5 3 +33 jdk1.6.0-b50 "Thu Sep 01 01:52:40 EDT 2005" 16287 974937 1 0 0 0 3 5 4 +34 jdk1.6.0-b51 "Thu Sep 08 01:55:36 EDT 2005" 16362 979377 0 0 0 0 4 5 4 +35 jdk1.6.0-b52 "Thu Sep 15 02:04:08 EDT 2005" 16477 979399 0 0 0 0 4 5 4 +36 jdk1.6.0-b53 "Thu Sep 22 02:00:28 EDT 2005" 16019 957900 0 0 1 0 3 5 3 +37 jdk1.6.0-b54 "Thu Sep 29 01:54:34 EDT 2005" 16019 957900 0 0 0 0 3 6 3 +38 jdk1.6.0-b55 "Thu Oct 06 01:54:14 EDT 2005" 16051 959014 0 0 0 0 3 6 3 +39 jdk1.6.0-b56 "Thu Oct 13 01:54:12 EDT 2005" 16211 970835 0 0 0 0 3 6 3 +40 jdk1.6.0-b57 "Thu Oct 20 01:55:26 EDT 2005" 16279 971627 0 0 0 0 3 6 3 +41 jdk1.6.0-b58 "Thu Oct 27 01:56:30 EDT 2005" 16283 971945 0 0 0 0 3 6 3 +42 jdk1.6.0-b59 "Thu Nov 03 01:56:58 EST 2005" 16232 972193 0 0 0 0 3 6 3 +43 jdk1.6.0-b60 "Thu Nov 10 01:54:18 EST 2005" 16235 972346 0 0 0 0 3 6 3 +</pre><p> +We could also generate that information directly, without creating an intermediate db.xml file, using the command +</p><pre class="screen"> +computeBugHistory jdk1.6.0-b*/jre/lib/rt.xml | filterBugs -bugPattern IL_ db.xml | mineBugHistory -formatDates +</pre><p>We can then use that information to display a graph showing the number of infinite recursive loops +found by FindBugs in each build of Sun's JDK1.6.0. The blue area indicates the number of infinite +recursive loops in that build, the red area above it indicates the number of infinite recursive loops that existed +in some previous version but not in the current version (thus, the combined height of the red and blue areas +is guaranteed to never decrease, and goes up whenever a new infinite recursive loop bug is introduced). The height +of the red area is computed as the sum of the fixed, removed and dead values for each version. +The reductions in builds 13 and 14 came after Sun was notified about the bugs found by FindBugs in the JDK. + </p><div class="mediaobject"><img src="infiniteRecursiveLoops.png"></div><p> +Given the db.xml file that contains the results for all the jdk1.6.0 builds, the following command will show the history of high and medium priority correctness warnings: +</p><pre class="screen"> +filterBugs -priority M -category C db.xml | mineBugHistory -formatDates +</pre><p> +generating the table: +</p><pre class="screen"> +seq version time classes NCSS added newCode fixed removed retained dead active +0 jdk1.6.0-b12 "Thu Nov 11 09:07:20 EST 2004" 13128 811569 0 1075 0 0 0 0 1075 +1 jdk1.6.0-b13 "Thu Nov 18 06:02:06 EST 2004" 13128 811570 0 0 0 0 1075 0 1075 +2 jdk1.6.0-b14 "Thu Dec 02 06:12:26 EST 2004" 13145 811786 3 0 6 0 1069 0 1072 +3 jdk1.6.0-b15 "Thu Dec 09 06:07:04 EST 2004" 13174 811693 2 1 3 0 1069 6 1072 +4 jdk1.6.0-b16 "Thu Dec 16 06:21:28 EST 2004" 13175 811715 0 0 1 0 1071 9 1071 +5 jdk1.6.0-b17 "Thu Dec 23 06:27:22 EST 2004" 13176 811974 0 0 1 0 1070 10 1070 +6 jdk1.6.0-b19 "Thu Jan 13 06:41:16 EST 2005" 13176 812011 0 0 0 0 1070 11 1070 +7 jdk1.6.0-b21 "Thu Jan 27 05:57:52 EST 2005" 13177 812173 0 0 1 0 1069 11 1069 +8 jdk1.6.0-b23 "Thu Feb 10 05:44:36 EST 2005" 13179 812188 0 0 0 0 1069 12 1069 +9 jdk1.6.0-b26 "Thu Mar 03 06:04:02 EST 2005" 13199 811770 0 0 2 1 1066 12 1066 +10 jdk1.6.0-b27 "Thu Mar 10 04:48:38 EST 2005" 13189 812440 1 0 1 1 1064 15 1065 +11 jdk1.6.0-b28 "Thu Mar 17 02:54:22 EST 2005" 13185 812056 0 0 0 0 1065 17 1065 +12 jdk1.6.0-b29 "Thu Mar 24 03:09:20 EST 2005" 13117 809468 3 0 8 26 1031 17 1034 +13 jdk1.6.0-b30 "Thu Mar 31 02:53:32 EST 2005" 13118 809501 0 0 0 0 1034 51 1034 +14 jdk1.6.0-b31 "Thu Apr 07 03:00:14 EDT 2005" 13117 809572 0 0 0 0 1034 51 1034 +15 jdk1.6.0-b32 "Thu Apr 14 02:56:56 EDT 2005" 13169 811096 1 1 0 1 1033 51 1035 +16 jdk1.6.0-b33 "Thu Apr 21 02:46:22 EDT 2005" 13187 811942 3 0 2 1 1032 52 1035 +17 jdk1.6.0-b34 "Thu Apr 28 02:49:00 EDT 2005" 13195 813488 0 1 0 0 1035 55 1036 +18 jdk1.6.0-b35 "Thu May 05 02:49:04 EDT 2005" 13457 829837 0 36 2 0 1034 55 1070 +19 jdk1.6.0-b36 "Thu May 12 02:59:46 EDT 2005" 13462 831278 0 0 0 0 1070 57 1070 +20 jdk1.6.0-b37 "Thu May 19 02:55:08 EDT 2005" 13464 831971 0 1 1 0 1069 57 1070 +21 jdk1.6.0-b38 "Thu May 26 03:08:16 EDT 2005" 13564 836565 1 7 2 6 1062 58 1070 +22 jdk1.6.0-b39 "Fri Jun 03 03:10:48 EDT 2005" 13856 849992 6 39 5 0 1065 66 1110 +23 jdk1.6.0-b40 "Thu Jun 09 03:30:28 EDT 2005" 15972 959619 7 147 11 0 1099 71 1253 +24 jdk1.6.0-b41 "Thu Jun 16 03:19:22 EDT 2005" 15972 959619 0 0 0 0 1253 82 1253 +25 jdk1.6.0-b42 "Fri Jun 24 03:38:54 EDT 2005" 15966 958581 3 0 1 2 1250 82 1253 +26 jdk1.6.0-b43 "Thu Jul 14 03:09:34 EDT 2005" 16041 960544 5 11 15 8 1230 85 1246 +27 jdk1.6.0-b44 "Thu Jul 21 03:05:54 EDT 2005" 16041 960547 0 0 0 0 1246 108 1246 +28 jdk1.6.0-b45 "Thu Jul 28 03:26:10 EDT 2005" 16037 960606 19 0 2 0 1244 108 1263 +29 jdk1.6.0-b46 "Thu Aug 04 03:02:48 EDT 2005" 15936 951355 13 1 1 32 1230 110 1244 +30 jdk1.6.0-b47 "Thu Aug 11 03:18:56 EDT 2005" 15964 952387 163 8 7 20 1217 143 1388 +31 jdk1.6.0-b48 "Thu Aug 18 08:10:40 EDT 2005" 15970 953421 0 0 0 0 1388 170 1388 +32 jdk1.6.0-b49 "Thu Aug 25 03:24:38 EDT 2005" 16048 958940 1 11 1 0 1387 170 1399 +33 jdk1.6.0-b50 "Thu Sep 01 01:52:40 EDT 2005" 16287 974937 19 27 16 7 1376 171 1422 +34 jdk1.6.0-b51 "Thu Sep 08 01:55:36 EDT 2005" 16362 979377 1 15 3 0 1419 194 1435 +35 jdk1.6.0-b52 "Thu Sep 15 02:04:08 EDT 2005" 16477 979399 0 0 1 1 1433 197 1433 +36 jdk1.6.0-b53 "Thu Sep 22 02:00:28 EDT 2005" 16019 957900 13 12 16 20 1397 199 1422 +37 jdk1.6.0-b54 "Thu Sep 29 01:54:34 EDT 2005" 16019 957900 0 0 0 0 1422 235 1422 +38 jdk1.6.0-b55 "Thu Oct 06 01:54:14 EDT 2005" 16051 959014 1 4 7 0 1415 235 1420 +39 jdk1.6.0-b56 "Thu Oct 13 01:54:12 EDT 2005" 16211 970835 6 8 37 0 1383 242 1397 +40 jdk1.6.0-b57 "Thu Oct 20 01:55:26 EDT 2005" 16279 971627 0 0 0 0 1397 279 1397 +41 jdk1.6.0-b58 "Thu Oct 27 01:56:30 EDT 2005" 16283 971945 0 1 1 0 1396 279 1397 +42 jdk1.6.0-b59 "Thu Nov 03 01:56:58 EST 2005" 16232 972193 6 0 5 0 1392 280 1398 +43 jdk1.6.0-b60 "Thu Nov 10 01:54:18 EST 2005" 16235 972346 0 0 0 0 1398 285 1398 +44 jdk1.6.0-b61 "Thu Nov 17 01:58:42 EST 2005" 16202 971134 2 0 4 0 1394 285 1396 +</pre></div><div class="sect2" title="2.2. Incremental history maintenance"><div class="titlepage"><div><div><h3 class="title"><a name="incrementalhistory"></a>2.2. Incremental history maintenance</h3></div></div></div><p> +If db.xml contains the results of running findbugs over builds b12 - b60, we can update db.xml to include the results of analyzing b61 with the commands: +</p><pre class="screen"> +computeBugHistory -output db.xml db.xml jdk1.6.0-b61/jre/lib/rt.xml +</pre></div></div><div class="sect1" title="3. Ant example"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="antexample"></a>3. Ant example</h2></div></div></div><p> +Here is a complete ant script example for both running findbugs and running a chain of data-mining tools afterward: +</p><pre class="screen"> + +<project name="analyze_asm_util" default="findbugs"> + <!-- findbugs task definition --> + <property name="findbugs.home" value="/Users/ben/Documents/workspace/findbugs/findbugs" /> + <property name="jvmargs" value="-server -Xss1m -Xmx800m -Duser.language=en -Duser.region=EN -Dfindbugs.home=${findbugs.home}" /> + + <path id="findbugs.lib"> + <fileset dir="${findbugs.home}/lib"> + <include name="findbugs-ant.jar"/> + </fileset> + </path> + + <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"> + <classpath refid="findbugs.lib" /> + </taskdef> + + <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask"> + <classpath refid="findbugs.lib" /> + </taskdef> + + <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask"> + <classpath refid="findbugs.lib" /> + </taskdef> + + <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask"> + <classpath refid="findbugs.lib" /> + </taskdef> + + <!-- findbugs task definition --> + <target name="findbugs"> + <antcall target="analyze" /> + <antcall target="mine" /> + </target> + + <!-- analyze task --> + <target name="analyze"> + <!-- run findbugs against asm-util --> + <findbugs home="${findbugs.home}" + output="xml:withMessages" + timeout="90000000" + reportLevel="experimental" + workHard="true" + effort="max" + adjustExperimental="true" + jvmargs="${jvmargs}" + failOnError="true" + outputFile="out.xml" + projectName="Findbugs" + debug="false"> + <class location="asm-util-3.0.jar" /> + </findbugs> + </target> + + <target name="mine"> + + <!-- Set info to the latest analysis --> + <setBugDatabaseInfo home="${findbugs.home}" + withMessages="true" + name="asm-util-3.0.jar" + input="out.xml" + output="out-rel.xml"/> + + <!-- Checking if history file already exists (out-hist.xml) --> + <condition property="mining.historyfile.available"> + <available file="out-hist.xml"/> + </condition> + <condition property="mining.historyfile.notavailable"> + <not> + <available file="out-hist.xml"/> + </not> + </condition> + + <!-- this target is executed if the history file do not exist (first run) --> + <antcall target="history-init"> + <param name="data.file" value="out-rel.xml" /> + <param name="hist.file" value="out-hist.xml" /> + </antcall> + <!-- else this one is executed --> + <antcall target="history"> + <param name="data.file" value="out-rel.xml" /> + <param name="hist.file" value="out-hist.xml" /> + <param name="hist.summary.file" value="out-hist.txt" /> + </antcall> + </target> + + <!-- Initializing history file --> + <target name="history-init" if="mining.historyfile.notavailable"> + <copy file="${data.file}" tofile="${hist.file}" /> + </target> + + <!-- Computing bug history --> + <target name="history" if="mining.historyfile.available"> + <!-- Merging ${data.file} into ${hist.file} --> + <computeBugHistory home="${findbugs.home}" + withMessages="true" + output="${hist.file}"> + <dataFile name="${hist.file}"/> + <dataFile name="${data.file}"/> + </computeBugHistory> + + <!-- Compute history into ${hist.summary.file} --> + <mineBugHistory home="${findbugs.home}" + formatDates="true" + noTabs="true" + input="${hist.file}" + output="${hist.summary.file}"/> + </target> + +</project> + +</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rejarForAnalysis.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="license.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 11. Using rejarForAnalysis </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 13. License</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/eclipse.html b/tools/findbugs/doc/manual/eclipse.html new file mode 100644 index 0000000..52ac8e9 --- /dev/null +++ b/tools/findbugs/doc/manual/eclipse.html @@ -0,0 +1,112 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 7. Using the FindBugs™ Eclipse plugin</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="anttask.html" title="Chapter 6. Using the FindBugs™ Ant task"><link rel="next" href="filter.html" title="Chapter 8. Filter Files"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. Using the <span class="application">FindBugs</span>™ Eclipse plugin</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="anttask.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="filter.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 7. Using the FindBugs™ Eclipse plugin"><div class="titlepage"><div><div><h2 class="title"><a name="eclipse"></a>Chapter 7. Using the <span class="application">FindBugs</span>™ Eclipse plugin</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="eclipse.html#d0e1662">1. Requirements</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1670">2. Installation</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1717">3. Using the Plugin</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1748">4. Extending the Eclipse Plugin (since 2.0.0)</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1802">5. Troubleshooting</a></span></dt></dl></div><p> +The FindBugs Eclipse plugin allows <span class="application">FindBugs</span> to be used within +the <a class="ulink" href="http://www.eclipse.org/" target="_top">Eclipse</a> IDE. +The FindBugs Eclipse plugin was generously contributed by Peter Friese. +Phil Crosby and Andrei Loskutov contributed major improvements +to the plugin. +</p><div class="sect1" title="1. Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1662"></a>1. Requirements</h2></div></div></div><p> +To use the <span class="application">FindBugs</span> Plugin for Eclipse, you need Eclipse 3.3 or later, +and JRE/JDK 1.5 or later. +</p></div><div class="sect1" title="2. Installation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1670"></a>2. Installation</h2></div></div></div><p> + We provide update sites that allow you to automatically install FindBugs into Eclipse and also query and install updates. + There are three different update sites</p><div class="variablelist" title="FindBugs Eclipse update sites"><p class="title"><b>FindBugs Eclipse update sites</b></p><dl><dt><span class="term"><a class="ulink" href="http://findbugs.cs.umd.edu/eclipse/" target="_top">http://findbugs.cs.umd.edu/eclipse/</a></span></dt><dd><p> + Only provides official releases of FindBugs. + </p></dd><dt><span class="term"><a class="ulink" href="http://findbugs.cs.umd.edu/eclipse-candidate/" target="_top">http://findbugs.cs.umd.edu/eclipse-candidate/</a></span></dt><dd><p> + Provides official releases and release candidates of FindBugs. + </p></dd><dt><span class="term"><a class="ulink" href="http://findbugs.cs.umd.edu/eclipse-daily/" target="_top">http://findbugs.cs.umd.edu/eclipse-daily/</a></span></dt><dd><p> + Provides the daily build of FindBugs. No testing other than that it compiles. + </p></dd></dl></div><p>You can also manually +download the plugin from the following link: +<a class="ulink" href="http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download" target="_top">http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download</a>. +Extract it in Eclipse's "plugins" subdirectory. +(So <eclipse_install_dir>/plugins/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122/findbugs.png +should be the path to the <span class="application">FindBugs</span> logo.) + +</p><p> +Once the plugin is extracted, start Eclipse and choose +<span class="guimenu">Help</span> → <span class="guimenuitem">About Eclipse Platform</span> → <span class="guimenuitem">Plug-in Details</span>. +You should find a plugin called "FindBugs Plug-in" provided by "FindBugs Project". +</p></div><div class="sect1" title="3. Using the Plugin"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1717"></a>3. Using the Plugin</h2></div></div></div><p> +To get started, right click on a Java project in Package Explorer, +and select the option labeled "Find Bugs". +<span class="application">FindBugs</span> will run, and problem markers (displayed in source +windows, and also in the Eclipse Problems view) will point to +locations in your code which have been identified as potential instances +of bug patterns. +</p><p> +You can also run <span class="application">FindBugs</span> on existing java archives (jar, ear, zip, war etc). Simply +create an empty Java project and attach archives to the project classpath. Having that, you +can now right click the archive node in Package Explorer and select the option labeled +"Find Bugs". If you additionally configure the source code locations for the binaries, +<span class="application">FindBugs</span> will also link the generated warnings to the right source files. +</p><p> +You may customize how <span class="application">FindBugs</span> runs by opening the Properties +dialog for a Java project, and choosing the "Findbugs" property page. +Options you may choose include: +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Enable or disable the "Run FindBugs Automatically" checkbox. + When enabled, FindBugs will run every time you modify a Java class + within the project. + </p></li><li class="listitem"><p> + Choose minimum warning priority and enabled bug categories. + These options will choose which warnings are shown. + For example, if you select the "Medium" warning priority, + only Medium and High priority warnings will be shown. + Similarly, if you uncheck the "Style" checkbox, no warnings + in the Style category will be displayed. + </p></li><li class="listitem"><p> + Select detectors. The table allows you to select which detectors + you want to enable for your project. + </p></li></ul></div></div><div class="sect1" title="4. Extending the Eclipse Plugin (since 2.0.0)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1748"></a>4. Extending the Eclipse Plugin (since 2.0.0)</h2></div></div></div><p> +Eclipse plugin supports contribution of custom <span class="application">FindBugs</span> detectors (see also +<a class="ulink" href="http://code.google.com/p/findbugs/source/browse/trunk/findbugs/src/doc/AddingDetectors.txt" target="_top">AddingDetectors.txt</a> +for more information). There are two ways to contribute custom plugins to the Eclipse: +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Existing standard <span class="application">FindBugs</span> detector packages can be configured via + <span class="guimenu">Window</span> → <span class="guimenuitem">Preferences</span> → <span class="guimenuitem">Java</span> → <span class="guimenuitem"><span class="application">FindBugs</span></span> → <span class="guimenuitem">Misc. Settings</span> → <span class="guimenuitem">Custom Detectors</span>. + Simply specify there locations of any additional plugin libraries. + </p><p> + The benefit of this solution is that already existing detector packages can be + used "as is", and that you can quickly verify the quality of third party detectors. + The drawback is that you have to apply this settings in each + new Eclipse workspace, and this settings can't be shared between team members. + </p></li><li class="listitem"><p> + It is possible to contribute custom detectors via standard Eclipse extensions mechanism. + </p><p> + Please check the documentation of the + <a class="ulink" href="http://code.google.com/p/findbugs/source/browse/trunk/eclipsePlugin/schema/detectorPlugins.exsd" target="_top"> + findBugsEclipsePlugin/schema/detectorPlugins.exsd</a> + extension point how to update the plugin.xml. Existing <span class="application">FindBugs</span> detector plugins can + be easily "extended" to be full featured <span class="application">FindBugs</span> AND Eclipse detector plugins. + Usually you only need to add META-INF/MANIFEST.MF and plugin.xml to the jar and + update your build scripts to not to override the MANIFEST.MF during the build. + </p><p> + The benefit of this solution is that for given (shared) Eclipse installation + each team member has exactly same detectors set, and there is no need to configure + anything anymore. The (really small) precondition + is that you have to convert your existing detectors package to the valid + Eclipse plugin. You can do this even for third-party detector packages. + Another major differentiator is the ability to extend the default FindBugs + classpath at runtime with required third party libraries (see + <a class="ulink" href="http://code.google.com/p/findbugs/source/browse/trunk/findbugs/src/doc/AddingDetectors.txt" target="_top">AddingDetectors.txt</a> + for more information). + </p></li></ul></div></div><div class="sect1" title="5. Troubleshooting"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1802"></a>5. Troubleshooting</h2></div></div></div><p> +This section lists common problems with the plugin and (if known) how to resolve them. +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + If you see OutOfMemory error dialogs after starting <span class="application">FindBugs</span> analysis in Eclipse, + please increase JVM available memory: change eclipse.ini and add the lines below + to the end of the file: + </p><pre class="programlisting"> + -vmargs + -Xmx1000m + </pre><p> + Important: the configuration arguments starting with the line "-vmargs" must + be last lines in the eclipse.ini file, and only one argument per line is allowed! + </p></li><li class="listitem"><p> + If you do not see any <span class="application">FindBugs</span> problem markers (in your source + windows or in the Problems View), you may need to change your + Problems View filter settings. See + <a class="ulink" href="http://findbugs.sourceforge.net/FAQ.html#q7" target="_top">http://findbugs.sourceforge.net/FAQ.html#q7</a> for more information. + </p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="anttask.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="filter.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Using the <span class="application">FindBugs</span>™ <span class="application">Ant</span> task </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Filter Files</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/filter.html b/tools/findbugs/doc/manual/filter.html new file mode 100644 index 0000000..98b264f --- /dev/null +++ b/tools/findbugs/doc/manual/filter.html @@ -0,0 +1,363 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 8. Filter Files</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="eclipse.html" title="Chapter 7. Using the FindBugs™ Eclipse plugin"><link rel="next" href="analysisprops.html" title="Chapter 9. Analysis Properties"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Filter Files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="eclipse.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="analysisprops.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 8. Filter Files"><div class="titlepage"><div><div><h2 class="title"><a name="filter"></a>Chapter 8. Filter Files</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="filter.html#d0e1838">1. Introduction to Filter Files</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1888">2. Types of Match clauses</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2136">3. Java element name matching</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2161">4. Caveats</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2191">5. Examples</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2249">6. Complete Example</a></span></dt></dl></div><p> +Filter files may be used to include or exclude bug reports for particular classes +and methods. This chapter explains how to use filter files. + +</p><div class="note" title="Planned Features" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: Planned Features"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png"></td><th align="left">Planned Features</th></tr><tr><td align="left" valign="top"><p> + Filters are currently only supported by the Command Line interface. + Eventually, filter support will be added to the GUI. +</p></td></tr></table></div><p> +</p><div class="sect1" title="1. Introduction to Filter Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1838"></a>1. Introduction to Filter Files</h2></div></div></div><p> +Conceptually, a filter matches bug instances against a set of criteria. +By defining a filter, you can select bug instances for special treatment; +for example, to exclude or include them in a report. +</p><p> +A filter file is an <a class="ulink" href="http://www.w3.org/XML/" target="_top">XML</a> document with a top-level <code class="literal">FindBugsFilter</code> element +which has some number of <code class="literal">Match</code> elements as children. Each <code class="literal">Match</code> +element represents a predicate which is applied to generated bug instances. +Usually, a filter will be used to exclude bug instances. For example: + +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong>findbugs -textui -exclude <em class="replaceable"><code>myExcludeFilter.xml</code></em> <em class="replaceable"><code>myApp.jar</code></em></strong></span> +</pre><p> + +However, a filter could also be used to select bug instances to specifically +report: + +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong>findbugs -textui -include <em class="replaceable"><code>myIncludeFilter.xml</code></em> <em class="replaceable"><code>myApp.jar</code></em></strong></span> +</pre><p> +</p><p> +<code class="literal">Match</code> elements contain children, which are conjuncts of the predicate. +In other words, each of the children must be true for the predicate to be true. +</p></div><div class="sect1" title="2. Types of Match clauses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1888"></a>2. Types of Match clauses</h2></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="literal"><Bug></code></span></dt><dd><p> + This element specifies a particular bug pattern or patterns to match. + The <code class="literal">pattern</code> attribute is a comma-separated list of + bug pattern types. You can find the bug pattern types for particular + warnings by looking at the output produced by the <span class="command"><strong>-xml</strong></span> + output option (the <code class="literal">type</code> attribute of <code class="literal">BugInstance</code> + elements), or from the <a class="ulink" href="../bugDescriptions.html" target="_top">bug + descriptions document</a>. + </p><p> + For more coarse-grained matching, use <code class="literal">code</code> attribute. It takes + a comma-separated list of bug abbreviations. For most-coarse grained matching use + <code class="literal">category</code> attriute, that takes a comma separated list of bug category names: + <code class="literal">CORRECTNESS</code>, <code class="literal">MT_CORRECTNESS</code>, + <code class="literal">BAD_PRACTICICE</code>, <code class="literal">PERFORMANCE</code>, <code class="literal">STYLE</code>. + </p><p> + If more than one of the attributes mentioned above are specified on the same + <code class="literal"><Bug></code> element, all bug patterns that match either one of specified + pattern names, or abreviations, or categories will be matched. + </p><p> + As a backwards compatibility measure, <code class="literal"><BugPattern></code> and + <code class="literal"><BugCode></code> elements may be used instead of + <code class="literal"><Bug></code> element. Each of these uses a + <code class="literal">name</code> attribute for specifying accepted values list. Support for these + elements may be removed in a future release. + </p></dd><dt><span class="term"><code class="literal"><Confidence></code></span></dt><dd><p> + This element matches warnings with a particular bug confidence. + The <code class="literal">value</code> attribute should be an integer value: + 1 to match high-confidence warnings, 2 to match normal-confidence warnings, + or 3 to match low-confidence warnings. <Confidence> replaced + <Priority> in 2.0.0 release. + </p></dd><dt><span class="term"><code class="literal"><Priority></code></span></dt><dd><p> + Same as <code class="literal"><Confidence></code>, exists for backward compatibility. + </p></dd><dt><span class="term"><code class="literal"><Rank></code></span></dt><dd><p> + This element matches warnings with a particular bug rank. + The <code class="literal">value</code> attribute should be an integer value + between 1 and 20, where 1 to 4 are scariest, 5 to 9 scary, 10 to 14 troubling, + and 15 to 20 of concern bugs. + </p></dd><dt><span class="term"><code class="literal"><Package></code></span></dt><dd><p> + This element matches warnings associated with classes within the package specified + using <code class="literal">name</code> attribute. Nested packages are not included (along the + lines of Java import statement). However matching multiple packages can be achieved + easily using regex name match. + </p></dd><dt><span class="term"><code class="literal"><Class></code></span></dt><dd><p> + This element matches warnings associated with a particular class. The + <code class="literal">name</code> attribute is used to specify the exact or regex match pattern + for the class name. + </p><p> + As a backward compatibility measure, instead of element of this type, you can use + <code class="literal">class</code> attribute on a <code class="literal">Match</code> element to specify + exact an class name or <code class="literal">classregex</code> attribute to specify a regular + expression to match the class name against. + </p><p> + If the <code class="literal">Match</code> element contains neither a <code class="literal">Class</code> element, + nor a <code class="literal">class</code> / <code class="literal">classregex</code> attribute, the predicate will apply + to all classes. Such predicate is likely to match more bug instances than you want, unless it is + refined further down with apropriate method or field predicates. + </p></dd><dt><span class="term"><code class="literal"><Method></code></span></dt><dd><p>This element specifies a method. The <code class="literal">name</code> is used to specify + the exact or regex match pattern for the method name. + The <code class="literal">params</code> attribute is a comma-separated list + of the types of the method's parameters. The <code class="literal">returns</code> attribute is + the method's return type. In <code class="literal">params</code> and <code class="literal">returns</code>, class names + must be fully qualified. (E.g., "java.lang.String" instead of just + "String".) If one of the latter attributes is specified the other is required for creating a method signature. + Note that you can provide either <code class="literal">name</code> attribute or <code class="literal">params</code> + and <code class="literal">returns</code> attributes or all three of them. This way you can provide various kinds of + name and signature based matches. + </p></dd><dt><span class="term"><code class="literal"><Field></code></span></dt><dd><p>This element specifies a field. The <code class="literal">name</code> attribute is is used to specify + the exact or regex match pattern for the field name. You can also filter fields according to their signature - + use <code class="literal">type</code> attribute to specify fully qualified type of the field. You can specify eiter or both + of these attributes in order to perform name / signature based matches. + </p></dd><dt><span class="term"><code class="literal"><Local></code></span></dt><dd><p>This element specifies a local variable. The <code class="literal">name</code> attribute is is used to specify + the exact or regex match pattern for the local variable name. Local variables are variables defined within a method. + </p></dd><dt><span class="term"><code class="literal"><Or></code></span></dt><dd><p> + This element combines <code class="literal">Match</code> clauses as disjuncts. I.e., you can put two + <code class="literal">Method</code> elements in an <code class="literal">Or</code> clause in order to match either method. + </p></dd><dt><span class="term"><code class="literal"><And></code></span></dt><dd><p> + This element combines <code class="literal">Match</code> clauses which both must evaluate to true. I.e., you can put + <code class="literal">Bug</code> and <code class="literal">Priority</code> elements in an <code class="literal">And</code> clause in order + to match specific bugs with given priority only. + </p></dd><dt><span class="term"><code class="literal"><Not></code></span></dt><dd><p> + This element inverts the included child <code class="literal">Match</code>. I.e., you can put a + <code class="literal">Bug</code> element in a <code class="literal">Not</code> clause in order to match any bug + excluding the given one. + </p></dd></dl></div></div><div class="sect1" title="3. Java element name matching"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2136"></a>3. Java element name matching</h2></div></div></div><p> +If the <code class="literal">name</code> attribute of <code class="literal">Class</code>, <code class="literal">Method</code> or +<code class="literal">Field</code> starts with the ~ character the rest of attribute content is interpreted as +a Java regular expression that is matched against the names of the Java element in question. +</p><p> +Note that the pattern is matched against whole element name and therefore .* clauses need to be used +at pattern beginning and/or end to perform substring matching. +</p><p> +See <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html" target="_top"><code class="literal">java.util.regex.Pattern</code></a> +documentation for pattern syntax. +</p></div><div class="sect1" title="4. Caveats"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2161"></a>4. Caveats</h2></div></div></div><p> +<code class="literal">Match</code> clauses can only match information that is actually contained in the +bug instances. Every bug instance has a class, so in general, excluding +bugs by class will work. +</p><p> +Some bug instances have two (or more) classes. For example, the DE (dropped exception) +bugs report both the class containing the method where the dropped exception +happens, and the class which represents the type of the dropped exception. +Only the <span class="emphasis"><em>first</em></span> (primary) class is matched against <code class="literal">Match</code> clauses. +So, for example, if you want to suppress IC (initialization circularity) +reports for classes "com.foobar.A" and "com.foobar.B", you would use +two <code class="literal">Match</code> clauses: + +</p><pre class="programlisting"> + <Match> + <Class name="com.foobar.A" /> + <Bug code="IC" /> + </Match> + + <Match> + <Class name="com.foobar.B" /> + <Bug code="IC" /> + </Match> +</pre><p> + +By explicitly matching both classes, you ensure that the IC bug instance will be +matched regardless of which class involved in the circularity happens to be +listed first in the bug instance. (Of course, this approach might accidentally +supress circularities involving "com.foobar.A" or "com.foobar.B" and a third +class.) +</p><p> +Many kinds of bugs report what method they occur in. For those bug instances, +you can put <code class="literal">Method</code> clauses in the <code class="literal">Match</code> element and they should work +as expected. +</p></div><div class="sect1" title="5. Examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2191"></a>5. Examples</h2></div></div></div><p> + 1. Match all bug reports for a class. + +</p><pre class="programlisting"> + + <Match> + <Class name="com.foobar.MyClass" /> + </Match> + +</pre><p> + +</p><p> + 2. Match certain tests from a class by specifying their abbreviations. +</p><pre class="programlisting"> + + <Match> + <Class name="com.foobar.MyClass"/ > + <Bug code="DE,UrF,SIC" /> + </Match> + +</pre><p> +</p><p> + 3. Match certain tests from all classes by specifying their abbreviations. + +</p><pre class="programlisting"> + + <Match> + <Bug code="DE,UrF,SIC" /> + </Match> + +</pre><p> +</p><p> + 4. Match certain tests from all classes by specifying their category. + +</p><pre class="programlisting"> + + <Match> + <Bug category="PERFORMANCE" /> + </Match> + +</pre><p> +</p><p> + 5. Match bug types from specified methods of a class by their abbreviations. + +</p><pre class="programlisting"> + + <Match> + <Class name="com.foobar.MyClass" /> + <Or> + <Method name="frob" params="int,java.lang.String" returns="void" /> + <Method name="blat" params="" returns="boolean" /> + </Or> + <Bug code="DC" /> + </Match> + +</pre><p> +</p><p> + 6. Match a particular bug pattern in a particular method. + +</p><pre class="programlisting"> + + <!-- A method with an open stream false positive. --> + <Match> + <Class name="com.foobar.MyClass" /> + <Method name="writeDataToFile" /> + <Bug pattern="OS_OPEN_STREAM" /> + </Match> + +</pre><p> +</p><p> + 7. Match a particular bug pattern with a given priority in a particular method. + +</p><pre class="programlisting"> + + <!-- A method with a dead local store false positive (medium priority). --> + <Match> + <Class name="com.foobar.MyClass" /> + <Method name="someMethod" /> + <Bug pattern="DLS_DEAD_LOCAL_STORE" /> + <Priority value="2" /> + </Match> + +</pre><p> +</p><p> + 8. Match minor bugs introduced by AspectJ compiler (you are probably not interested in these unless + you are an AspectJ developer). + +</p><pre class="programlisting"> + + <Match> + <Class name="~.*\$AjcClosure\d+" /> + <Bug pattern="DLS_DEAD_LOCAL_STORE" /> + <Method name="run" /> + </Match> + <Match> + <Bug pattern="UUF_UNUSED_FIELD" /> + <Field name="~ajc\$.*" /> + </Match> + +</pre><p> +</p><p> + 9. Match bugs in specific parts of the code base + +</p><pre class="programlisting"> + + <!-- match unused fields warnings in Messages classes in all packages --> + <Match> + <Class name="~.*\.Messages" /> + <Bug code="UUF" /> + </Match> + <!-- match mutable statics warnings in all internal packages --> + <Match> + <Package name="~.*\.internal" /> + <Bug code="MS" /> + </Match> + <!-- match anonymoous inner classes warnings in ui package hierarchy --> + <Match> + <Package name="~com\.foobar\.fooproject\.ui.*" /> + <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" /> + </Match> + +</pre><p> +</p><p> + 10. Match bugs on fields or methods with specific signatures +</p><pre class="programlisting"> + + <!-- match System.exit(...) usage warnings in void main(String[]) methods in all classes --> + <Match> + <Method returns="void" name="main" params="java.lang.String[]" /> + <Bug pattern="DM_EXIT" /> + </Match> + <!-- match UuF warnings on fields of type com.foobar.DebugInfo on all classes --> + <Match> + <Field type="com.foobar.DebugInfo" /> + <Bug code="UuF" /> + </Match> + +</pre><p> +</p><p> + 11. Match bugs using the Not filter operator +</p><pre class="programlisting"> + +<!-- ignore all bugs in test classes, except for those bugs specifically relating to JUnit tests --> +<!-- i.e. filter bug if ( classIsJUnitTest && ! bugIsRelatedToJUnit ) --> +<Match> + <!-- the Match filter is equivalent to a logical 'And' --> + + <Class name="~.*\.*Test" /> + <!-- test classes are suffixed by 'Test' --> + + <Not> + <Bug code="IJU" /> <!-- 'IJU' is the code for bugs related to JUnit test code --> + </Not> +</Match> + +</pre><p> +</p></div><div class="sect1" title="6. Complete Example"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2249"></a>6. Complete Example</h2></div></div></div><pre class="programlisting"> + +<FindBugsFilter> + <Match> + <Class name="com.foobar.ClassNotToBeAnalyzed" /> + </Match> + + <Match> + <Class name="com.foobar.ClassWithSomeBugsMatched" /> + <Bug code="DE,UrF,SIC" /> + </Match> + + <!-- Match all XYZ violations. --> + <Match> + <Bug code="XYZ" /> + </Match> + + <!-- Match all doublecheck violations in these methods of "AnotherClass". --> + <Match> + <Class name="com.foobar.AnotherClass" /> + <Or> + <Method name="nonOverloadedMethod" /> + <Method name="frob" params="int,java.lang.String" returns="void" /> + <Method name="blat" params="" returns="boolean" /> + </Or> + <Bug code="DC" /> + </Match> + + <!-- A method with a dead local store false positive (medium priority). --> + <Match> + <Class name="com.foobar.MyClass" /> + <Method name="someMethod" /> + <Bug pattern="DLS_DEAD_LOCAL_STORE" /> + <Priority value="2" /> + </Match> + + <!-- All bugs in test classes, except for JUnit-specific bugs --> + <Match> + <Class name="~.*\.*Test" /> + <Not> + <Bug code="IJU" /> + </Not> + </Match> + +</FindBugsFilter> + +</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eclipse.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="analysisprops.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Using the <span class="application">FindBugs</span>™ Eclipse plugin </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 9. Analysis Properties</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/gui.html b/tools/findbugs/doc/manual/gui.html new file mode 100644 index 0000000..122b074 --- /dev/null +++ b/tools/findbugs/doc/manual/gui.html @@ -0,0 +1,68 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 5. Using the FindBugs GUI</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="running.html" title="Chapter 4. Running FindBugs™"><link rel="next" href="anttask.html" title="Chapter 6. Using the FindBugs™ Ant task"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Using the <span class="application">FindBugs</span> GUI</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="running.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="anttask.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 5. Using the FindBugs GUI"><div class="titlepage"><div><div><h2 class="title"><a name="gui"></a>Chapter 5. Using the <span class="application">FindBugs</span> GUI</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="gui.html#d0e1092">1. Creating a Project</a></span></dt><dt><span class="sect1"><a href="gui.html#d0e1134">2. Running the Analysis</a></span></dt><dt><span class="sect1"><a href="gui.html#d0e1139">3. Browsing Results</a></span></dt><dt><span class="sect1"><a href="gui.html#d0e1154">4. Saving and Opening</a></span></dt></dl></div><p> + This chapter describes how to use the <span class="application">FindBugs</span> graphical user interface (GUI). + </p><div class="sect1" title="1. Creating a Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1092"></a>1. Creating a Project</h2></div></div></div><p> +After you have started <span class="application">FindBugs</span> using the <span class="command"><strong>findbugs</strong></span> command, +choose the <span class="guimenu">File</span> → <span class="guimenuitem">New Project</span> +menu item. You will see a dialog which looks like this: +</p><div class="mediaobject"><img src="project-dialog.png"></div><p> +</p><p> +Use the "Add" button next to "Classpath to analyze" to select a Java archive +file (zip, jar, ear, or war file) or directory containing java classes to analyze for bugs. You may add multiple +archives/directories. +</p><p> +You can also add the source directories which contain +the source code for the Java archives you are analyzing. This will enable +<span class="application">FindBugs</span> to highlight the source code which contains a possible error. +The source directories you add should be the roots of the Java +package hierarchy. For example, if your application is contained in the +<code class="varname">org.foobar.myapp</code> package, you should add the +parent directory of the <code class="filename">org</code> directory +to the source directory list for the project. +</p><p> +Another optional step is to add additional Jar files or directories as +"Auxiliary classpath locations" entries. You should do this if the archives and directories you are analyzing +have references to other classes which are not included in the analyzed +archives/directories and are not in the standard runtime classpath. Some of the bug +pattern detectors in <span class="application">FindBugs</span> make use of class hierarchy information, +so you will get more accurate results if the entire class hierarchy is +available which <span class="application">FindBugs</span> performs its analysis. +</p></div><div class="sect1" title="2. Running the Analysis"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1134"></a>2. Running the Analysis</h2></div></div></div><p> +Once you have added all of the archives, directories, and source directories, +click the "Analyze" button to analyze the classes contained in the +Jar files. Note that for a very large program on an older computer, +this may take quite a while (tens of minutes). A recent computer with +ample memory will typically be able to analyze a large program in only a +few minutes. +</p></div><div class="sect1" title="3. Browsing Results"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1139"></a>3. Browsing Results</h2></div></div></div><p> +When the analysis completes, you will see a screen like the following: +</p><div class="mediaobject"><img src="example-details.png"></div><p> +</p><p> +The upper left-hand pane of the window shows the bug tree; this is a hierarchical +representation of all of the potential bugs detected in the analyzed +Jar files. +</p><p> +When you select a particular bug instance in the top pane, you will +see a description of the bug in the "Details" tab of the bottom pane. +In addition, the source code pane on the upper-right will show the +program source code where the potential bug occurs, if source is available. +In the above example, the bug is a stream object that is not closed. The +source code window highlights the line where the stream object is created. +</p><p> +You may add a textual annotations to bug instances. To do so, type them +into the text box just below the hierarchical view. You can type any +information which you would like to record. When you load and save bug +results files, the annotations are preserved. +</p></div><div class="sect1" title="4. Saving and Opening"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1154"></a>4. Saving and Opening</h2></div></div></div><p> +You may use the <span class="guimenu">File</span> → <span class="guimenuitem">Save as...</span> +menu option to save your work. To save your work, including the jar +file lists you specified and all bug results, choose +"FindBugs analysis results (.xml)" from the drop-down list in the +"Save as..." dialog. There are also options for saving just the jar +file lists ("FindBugs project file (.fbp)") or just the results +("FindBugs analysis file (.fba)"). +A saved file may be loaded with the +<span class="guimenu">File</span> → <span class="guimenuitem">Open...</span> +menu option. +</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="running.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="anttask.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. Running <span class="application">FindBugs</span>™ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 6. Using the <span class="application">FindBugs</span>™ <span class="application">Ant</span> task</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/index.html b/tools/findbugs/doc/manual/index.html new file mode 100644 index 0000000..42924a6 --- /dev/null +++ b/tools/findbugs/doc/manual/index.html @@ -0,0 +1,10 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>FindBugs™ Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="next" href="introduction.html" title="Chapter 1. Introduction"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="application">FindBugs</span>™ Manual</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="introduction.html">Next</a></td></tr></table><hr></div><div lang="en" class="book" title="FindBugs™ Manual"><div class="titlepage"><div><div><h1 class="title"><a name="findbugs-manual"></a><span class="application">FindBugs</span>™ Manual</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="othername">H.</span> <span class="surname">Hovemeyer</span></h3></div><div class="author"><h3 class="author"><span class="firstname">William</span> <span class="othername">W.</span> <span class="surname">Pugh</span></h3></div></div></div><div><p class="copyright">Copyright © 2003 - 2012 University of Maryland</p></div><div><div class="legalnotice" title="Legal Notice"><a name="d0e27"></a><p> +This manual is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. +To view a copy of this license, visit +<a class="ulink" href="http://creativecommons.org/licenses/by-nc-sa/1.0/" target="_top">http://creativecommons.org/licenses/by-nc-sa/1.0/</a> +or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. +</p><p> +The name FindBugs and the FindBugs logo are trademarked by the University of Maryland. +</p></div></div><div><p class="pubdate">17:16:15 EST, 22 November, 2013</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="introduction.html">1. Introduction</a></span></dt><dd><dl><dt><span class="sect1"><a href="introduction.html#d0e67">1. Requirements</a></span></dt></dl></dd><dt><span class="chapter"><a href="installing.html">2. Installing <span class="application">FindBugs</span>™</a></span></dt><dd><dl><dt><span class="sect1"><a href="installing.html#d0e98">1. Extracting the Distribution</a></span></dt></dl></dd><dt><span class="chapter"><a href="building.html">3. Building <span class="application">FindBugs</span>™ from Source</a></span></dt><dd><dl><dt><span class="sect1"><a href="building.html#d0e173">1. Prerequisites</a></span></dt><dt><span class="sect1"><a href="building.html#d0e262">2. Extracting the Source Distribution</a></span></dt><dt><span class="sect1"><a href="building.html#d0e275">3. Modifying <code class="filename">local.properties</code></a></span></dt><dt><span class="sect1"><a href="building.html#d0e333">4. Running <span class="application">Ant</span></a></span></dt><dt><span class="sect1"><a href="building.html#d0e427">5. Running <span class="application">FindBugs</span>™ from a source directory</a></span></dt></dl></dd><dt><span class="chapter"><a href="running.html">4. Running <span class="application">FindBugs</span>™</a></span></dt><dd><dl><dt><span class="sect1"><a href="running.html#d0e465">1. Quick Start</a></span></dt><dt><span class="sect1"><a href="running.html#d0e503">2. Executing <span class="application">FindBugs</span></a></span></dt><dt><span class="sect1"><a href="running.html#commandLineOptions">3. Command-line Options</a></span></dt></dl></dd><dt><span class="chapter"><a href="gui.html">5. Using the <span class="application">FindBugs</span> GUI</a></span></dt><dd><dl><dt><span class="sect1"><a href="gui.html#d0e1092">1. Creating a Project</a></span></dt><dt><span class="sect1"><a href="gui.html#d0e1134">2. Running the Analysis</a></span></dt><dt><span class="sect1"><a href="gui.html#d0e1139">3. Browsing Results</a></span></dt><dt><span class="sect1"><a href="gui.html#d0e1154">4. Saving and Opening</a></span></dt></dl></dd><dt><span class="chapter"><a href="anttask.html">6. Using the <span class="application">FindBugs</span>™ <span class="application">Ant</span> task</a></span></dt><dd><dl><dt><span class="sect1"><a href="anttask.html#d0e1205">1. Installing the <span class="application">Ant</span> task</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1243">2. Modifying build.xml</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1314">3. Executing the task</a></span></dt><dt><span class="sect1"><a href="anttask.html#d0e1339">4. Parameters</a></span></dt></dl></dd><dt><span class="chapter"><a href="eclipse.html">7. Using the <span class="application">FindBugs</span>™ Eclipse plugin</a></span></dt><dd><dl><dt><span class="sect1"><a href="eclipse.html#d0e1662">1. Requirements</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1670">2. Installation</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1717">3. Using the Plugin</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1748">4. Extending the Eclipse Plugin (since 2.0.0)</a></span></dt><dt><span class="sect1"><a href="eclipse.html#d0e1802">5. Troubleshooting</a></span></dt></dl></dd><dt><span class="chapter"><a href="filter.html">8. Filter Files</a></span></dt><dd><dl><dt><span class="sect1"><a href="filter.html#d0e1838">1. Introduction to Filter Files</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e1888">2. Types of Match clauses</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2136">3. Java element name matching</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2161">4. Caveats</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2191">5. Examples</a></span></dt><dt><span class="sect1"><a href="filter.html#d0e2249">6. Complete Example</a></span></dt></dl></dd><dt><span class="chapter"><a href="analysisprops.html">9. Analysis Properties</a></span></dt><dt><span class="chapter"><a href="annotations.html">10. Annotations</a></span></dt><dt><span class="chapter"><a href="rejarForAnalysis.html">11. Using rejarForAnalysis</a></span></dt><dt><span class="chapter"><a href="datamining.html">12. Data mining of bugs with <span class="application">FindBugs</span>™</a></span></dt><dd><dl><dt><span class="sect1"><a href="datamining.html#commands">1. Commands</a></span></dt><dt><span class="sect1"><a href="datamining.html#examples">2. Examples</a></span></dt><dt><span class="sect1"><a href="datamining.html#antexample">3. Ant example</a></span></dt></dl></dd><dt><span class="chapter"><a href="license.html">13. License</a></span></dt><dt><span class="chapter"><a href="acknowledgments.html">14. Acknowledgments</a></span></dt><dd><dl><dt><span class="sect1"><a href="acknowledgments.html#d0e3629">1. Contributors</a></span></dt><dt><span class="sect1"><a href="acknowledgments.html#d0e3752">2. Software Used</a></span></dt></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>9.1. <a href="analysisprops.html#analysisproptable">Configurable Analysis Properties</a></dt><dt>12.1. <a href="datamining.html#computeBugHistoryTable">Options for computeBugHistory command</a></dt><dt>12.2. <a href="datamining.html#filterOptionsTable">Options for filterBugs command</a></dt><dt>12.3. <a href="datamining.html#mineBugHistoryOptionsTable">Options for mineBugHistory command</a></dt><dt>12.4. <a href="datamining.html#mineBugHistoryColumns">Columns in mineBugHistory output</a></dt><dt>12.5. <a href="datamining.html#defectDensityColumns">Columns in defectDensity output</a></dt><dt>12.6. <a href="datamining.html#convertXmlToTextTable">Options for convertXmlToText command</a></dt><dt>12.7. <a href="datamining.html#setBugDatabaseInfoOptions">setBugDatabaseInfo Options</a></dt><dt>12.8. <a href="datamining.html#listBugDatabaseInfoColumns">listBugDatabaseInfo Columns</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="introduction.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Chapter 1. Introduction</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/installing.html b/tools/findbugs/doc/manual/installing.html new file mode 100644 index 0000000..b14a6eb --- /dev/null +++ b/tools/findbugs/doc/manual/installing.html @@ -0,0 +1,29 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 2. Installing FindBugs™</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="introduction.html" title="Chapter 1. Introduction"><link rel="next" href="building.html" title="Chapter 3. Building FindBugs™ from Source"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Installing <span class="application">FindBugs</span>™</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="building.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 2. Installing FindBugs™"><div class="titlepage"><div><div><h2 class="title"><a name="installing"></a>Chapter 2. Installing <span class="application">FindBugs</span>™</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="installing.html#d0e98">1. Extracting the Distribution</a></span></dt></dl></div><p> +This chapter explains how to install <span class="application">FindBugs</span>. +</p><div class="sect1" title="1. Extracting the Distribution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e98"></a>1. Extracting the Distribution</h2></div></div></div><p> +The easiest way to install <span class="application">FindBugs</span> is to download a binary distribution. +Binary distributions are available in +<a class="ulink" href="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.tar.gz?download" target="_top">gzipped tar format</a> and +<a class="ulink" href="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.zip?download" target="_top">zip format</a>. +Once you have downloaded a binary distribution, extract it into a directory of your choice. +</p><p> +Extracting a gzipped tar format distribution: +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong>gunzip -c findbugs-2.0.3.tar.gz | tar xvf -</strong></span> +</pre><p> +</p><p> +Extracting a zip format distribution: +</p><pre class="screen"> +<code class="prompt">C:\Software></code><span class="command"><strong>unzip findbugs-2.0.3.zip</strong></span> +</pre><p> +</p><p> +Usually, extracting a binary distribution will create a directory ending in +<code class="filename">findbugs-2.0.3</code>. For example, if you extracted +the binary distribution from the <code class="filename">C:\Software</code> +directory, then the <span class="application">FindBugs</span> software will be extracted into the directory +<code class="filename">C:\Software\findbugs-2.0.3</code>. +This directory is the <span class="application">FindBugs</span> home directory. We'll refer to it as +<em class="replaceable"><code>$FINDBUGS_HOME</code></em> (or <em class="replaceable"><code>%FINDBUGS_HOME%</code></em> for Windows) throughout this manual. +</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="building.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Building <span class="application">FindBugs</span>™ from Source</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/introduction.html b/tools/findbugs/doc/manual/introduction.html new file mode 100644 index 0000000..a65b499 --- /dev/null +++ b/tools/findbugs/doc/manual/introduction.html @@ -0,0 +1,12 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 1. Introduction</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="index.html" title="FindBugs™ Manual"><link rel="next" href="installing.html" title="Chapter 2. Installing FindBugs™"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="installing.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="introduction.html#d0e67">1. Requirements</a></span></dt></dl></div><p> <span class="application">FindBugs</span>™ is a program to find bugs in Java programs. It looks for instances +of "bug patterns" --- code instances that are likely to be errors.</p><p> This document describes version 2.0.3 of <span class="application">FindBugs</span>.We +are very interested in getting your feedback on <span class="application">FindBugs</span>. Please visit +the <a class="ulink" href="http://findbugs.sourceforge.net" target="_top"><span class="application">FindBugs</span> web page</a> for +the latest information on <span class="application">FindBugs</span>, contact information, and support resources such +as information about the <span class="application">FindBugs</span> mailing lists.</p><div class="sect1" title="1. Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e67"></a>1. Requirements</h2></div></div></div><p> To use <span class="application">FindBugs</span>, you need a runtime environment compatible with +<a class="ulink" href="http://java.sun.com/j2se" target="_top">Java 2 Standard Edition</a>, version 1.5 or later. +<span class="application">FindBugs</span> is platform independent, and is known to run on GNU/Linux, Windows, and +MacOS X platforms.</p><p>You should have at least 512 MB of memory to use <span class="application">FindBugs</span>. +To analyze very large projects, more memory may be needed.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="installing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">FindBugs</span>™ Manual </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. Installing <span class="application">FindBugs</span>™</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/license.html b/tools/findbugs/doc/manual/license.html new file mode 100644 index 0000000..bfe9cb1 --- /dev/null +++ b/tools/findbugs/doc/manual/license.html @@ -0,0 +1,13 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 13. License</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="datamining.html" title="Chapter 12. Data mining of bugs with FindBugs™"><link rel="next" href="acknowledgments.html" title="Chapter 14. Acknowledgments"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="datamining.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="acknowledgments.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 13. License"><div class="titlepage"><div><div><h2 class="title"><a name="license"></a>Chapter 13. License</h2></div></div></div><p> +The name FindBugs and the FindBugs logo is trademarked by the University +of Maryland. +FindBugs is free software distributed under the terms of the +<a class="ulink" href="http://www.gnu.org/licenses/lgpl.html" target="_top">Lesser GNU Public License</a>. +You should have received a copy of the license in the file <code class="filename">LICENSE.txt</code> +in the <span class="application">FindBugs</span> distribution. +</p><p> +You can find the latest version of FindBugs, along with its source code, from the +<a class="ulink" href="http://findbugs.sourceforge.net" target="_top">FindBugs web page</a>. +</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datamining.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="acknowledgments.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. Data mining of bugs with <span class="application">FindBugs</span>™ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 14. Acknowledgments</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/rejarForAnalysis.html b/tools/findbugs/doc/manual/rejarForAnalysis.html new file mode 100644 index 0000000..e28241a --- /dev/null +++ b/tools/findbugs/doc/manual/rejarForAnalysis.html @@ -0,0 +1,33 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 11. Using rejarForAnalysis</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="annotations.html" title="Chapter 10. Annotations"><link rel="next" href="datamining.html" title="Chapter 12. Data mining of bugs with FindBugs™"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 11. Using rejarForAnalysis</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="annotations.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="datamining.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 11. Using rejarForAnalysis"><div class="titlepage"><div><div><h2 class="title"><a name="rejarForAnalysis"></a>Chapter 11. Using rejarForAnalysis</h2></div></div></div><p> +If your project consists of many jarfiles or the jarfiles are scattered +over many directories, you may wish to use the <span class="command"><strong>rejarForAnalysis +</strong></span> script to make +FindBugs invocation easier. The script collects many jarfiles and combines them +into a single, large jarfile that can then be easily passed to FindBugs for +analysis. This can be particularly useful in combination with the 'find' command +on unix systems; e.g. <span class="command"><strong>find . -name '*.jar' | xargs rejarForAnalysis +</strong></span>. +</p><p> +The <span class="command"><strong>rejarForAnalysis</strong></span> script +can also be used to split a very large project up into a set of jarfiles with +the project classfiles evenly divided between them. This is useful when running +FindBugs on the entire project is not practical due to time or memory consumption. +Instead of running FindBugs on the entire project, you may use <span class="command"><strong> +rejarForAnalysis</strong></span> build one large, all-inclusive jarfile +containing all classes, invoke <span class="command"><strong>rejarForAnalysis</strong></span> +again to split the project into multiple jarfiles, then run FindBugs +on each divided jarfiles in turn, specifying the the all-inclusive jarfile in +the <span class="command"><strong>-auxclasspath</strong></span>. +</p><p> +These are the options accepted by the <span class="command"><strong>rejarForAnalysis</strong></span> script: +</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-maxAge</strong></span> <em class="replaceable"><code>days</code></em></span></dt><dd><p> + Maximum age in days (ignore jar files older than this). + </p></dd><dt><span class="term"><span class="command"><strong>-inputFileList</strong></span> <em class="replaceable"><code>filename</code></em></span></dt><dd><p> + Text file containing names of jar files. + </p></dd><dt><span class="term"><span class="command"><strong>-maxClasses</strong></span> <em class="replaceable"><code>num</code></em></span></dt><dd><p> + Maximum number of classes per analysis*.jar file. + </p></dd><dt><span class="term"><span class="command"><strong>-prefix</strong></span> <em class="replaceable"><code>class name prefix</code></em></span></dt><dd><p> + Prefix of class names that should be analyzed (e.g., edu.umd.cs.). + </p></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="annotations.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="datamining.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 10. Annotations </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 12. Data mining of bugs with <span class="application">FindBugs</span>™</td></tr></table></div></body></html>
\ No newline at end of file diff --git a/tools/findbugs/doc/manual/running.html b/tools/findbugs/doc/manual/running.html new file mode 100644 index 0000000..cf83c85 --- /dev/null +++ b/tools/findbugs/doc/manual/running.html @@ -0,0 +1,209 @@ +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>Chapter 4. Running FindBugs™</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="building.html" title="Chapter 3. Building FindBugs™ from Source"><link rel="next" href="gui.html" title="Chapter 5. Using the FindBugs GUI"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. Running <span class="application">FindBugs</span>™</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="building.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="gui.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 4. Running FindBugs™"><div class="titlepage"><div><div><h2 class="title"><a name="running"></a>Chapter 4. Running <span class="application">FindBugs</span>™</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="running.html#d0e465">1. Quick Start</a></span></dt><dt><span class="sect1"><a href="running.html#d0e503">2. Executing <span class="application">FindBugs</span></a></span></dt><dt><span class="sect1"><a href="running.html#commandLineOptions">3. Command-line Options</a></span></dt></dl></div><p> +<span class="application">FindBugs</span> has two user interfaces: a graphical user interface (GUI) and a +command line user interface. This chapter describes +how to run each of these user interfaces. +</p><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p> + This chapter is in the process of being re-written. + The rewrite is not complete yet. + </p></td></tr></table></div><div class="sect1" title="1. Quick Start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e465"></a>1. Quick Start</h2></div></div></div><p> + If you are running <span class="application">FindBugs</span> on a Windows system, + double-click on the file <code class="filename"><em class="replaceable"><code>%FINDBUGS_HOME%</code></em>\lib\findbugs.jar</code> to start the <span class="application">FindBugs</span> GUI. + </p><p> + On a Unix, Linux, or Mac OS X system, run the <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/bin/findbugs</code> + script, or run the command </p><pre class="screen"> +<span class="command"><strong>java -jar <em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar</strong></span></pre><p> + to run the <span class="application">FindBugs</span> GUI. + </p><p> + Refer to <a class="xref" href="gui.html" title="Chapter 5. Using the FindBugs GUI">Chapter 5, <i>Using the <span class="application">FindBugs</span> GUI</i></a> for information on how to use the GUI. + </p></div><div class="sect1" title="2. Executing FindBugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e503"></a>2. Executing <span class="application">FindBugs</span></h2></div></div></div><p> + This section describes how to invoke the <span class="application">FindBugs</span> program. + There are two ways to invoke <span class="application">FindBugs</span>: directly, or using a + wrapper script. + </p><div class="sect2" title="2.1. Direct invocation of FindBugs"><div class="titlepage"><div><div><h3 class="title"><a name="directInvocation"></a>2.1. Direct invocation of <span class="application">FindBugs</span></h3></div></div></div><p> + The preferred method of running <span class="application">FindBugs</span> is to directly execute + <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar</code> using the <span class="command"><strong>-jar</strong></span> + command line switch of the JVM (<span class="command"><strong>java</strong></span>) executable. + (Versions of <span class="application">FindBugs</span> prior to 1.3.5 required a wrapper script + to invoke <span class="application">FindBugs</span>.) + </p><p> + The general syntax of invoking <span class="application">FindBugs</span> directly is the following: +</p><pre class="screen"> + <span class="command"><strong>java <em class="replaceable"><code>[JVM arguments]</code></em> -jar <em class="replaceable"><code>$FINDBUGS_HOME</code></em>/lib/findbugs.jar <em class="replaceable"><code>options...</code></em></strong></span> +</pre><p> + </p><div class="sect3" title="2.1.1. Choosing the User Interface"><div class="titlepage"><div><div><h4 class="title"><a name="chooseUI"></a>2.1.1. Choosing the User Interface</h4></div></div></div><p> + The first command line option chooses the <span class="application">FindBugs</span> user interface to execute. + Possible values are: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <span class="command"><strong>-gui</strong></span>: runs the graphical user interface (GUI) + </p></li><li class="listitem"><p> + <span class="command"><strong>-textui</strong></span>: runs the command line user interface + </p></li><li class="listitem"><p> + <span class="command"><strong>-version</strong></span>: displays the <span class="application">FindBugs</span> version number + </p></li><li class="listitem"><p> + <span class="command"><strong>-help</strong></span>: displays help information for the + <span class="application">FindBugs</span> command line user interface + </p></li><li class="listitem"><p> + <span class="command"><strong>-gui1</strong></span>: executes the original (obsolete) + <span class="application">FindBugs</span> graphical user interface + </p></li></ul></div></div><div class="sect3" title="2.1.2. Java Virtual Machine (JVM) arguments"><div class="titlepage"><div><div><h4 class="title"><a name="jvmArgs"></a>2.1.2. Java Virtual Machine (JVM) arguments</h4></div></div></div><p> + Several Java Virtual Machine arguments are useful when invoking + <span class="application">FindBugs</span>. + </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-Xmx<em class="replaceable"><code>NN</code></em>m</strong></span></span></dt><dd><p> + Set the maximum Java heap size to <em class="replaceable"><code>NN</code></em> + megabytes. <span class="application">FindBugs</span> generally requires a large amount of + memory. For a very large project, using 1500 megabytes + is not unusual. + </p></dd><dt><span class="term"><span class="command"><strong>-D<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></strong></span></span></dt><dd><p> + Set a Java system property. For example, you might use the + argument <span class="command"><strong>-Duser.language=ja</strong></span> to display + GUI messages in Japanese. + </p></dd></dl></div></div></div><div class="sect2" title="2.2. Invocation of FindBugs using a wrapper script"><div class="titlepage"><div><div><h3 class="title"><a name="wrapperScript"></a>2.2. Invocation of <span class="application">FindBugs</span> using a wrapper script</h3></div></div></div><p> + Another way to run <span class="application">FindBugs</span> is to use a wrapper script. + </p><p> +On Unix-like systems, use the following command to invoke the wrapper script: +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/bin/findbugs <em class="replaceable"><code>options...</code></em></strong></span> +</pre><p> +</p><p> +On Windows systems, the command to invoke the wrapper script is +</p><pre class="screen"> +<code class="prompt">C:\My Directory></code><span class="command"><strong><em class="replaceable"><code>%FINDBUGS_HOME%</code></em>\bin\findbugs.bat <em class="replaceable"><code>options...</code></em></strong></span> +</pre><p> +</p><p> +On both Unix-like and Windows systems, you can simply add the <code class="filename"><em class="replaceable"><code>$FINDBUGS_HOME</code></em>/bin</code> +directory to your <code class="filename">PATH</code> environment variable and then invoke +FindBugs using the <span class="command"><strong>findbugs</strong></span> command. +</p><div class="sect3" title="2.2.1. Wrapper script command line options"><div class="titlepage"><div><div><h4 class="title"><a name="wrapperOptions"></a>2.2.1. Wrapper script command line options</h4></div></div></div><p>The <span class="application">FindBugs</span> wrapper scripts support the following command-line options. + Note that these command line options are <span class="emphasis"><em>not</em></span> handled by + the <span class="application">FindBugs</span> program per se; rather, they are handled by the wrapper + script. + </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-jvmArgs <em class="replaceable"><code>args</code></em></strong></span></span></dt><dd><p> + Specifies arguments to pass to the JVM. For example, you might want + to set a JVM property: +</p><pre class="screen"> +<code class="prompt">$ </code><span class="command"><strong>findbugs -textui -jvmArgs "-Duser.language=ja" <em class="replaceable"><code>myApp.jar</code></em></strong></span> +</pre><p> + </p></dd><dt><span class="term"><span class="command"><strong>-javahome <em class="replaceable"><code>directory</code></em></strong></span></span></dt><dd><p> + Specifies the directory containing the JRE (Java Runtime Environment) to + use to execute <span class="application">FindBugs</span>. + </p></dd><dt><span class="term"><span class="command"><strong>-maxHeap <em class="replaceable"><code>size</code></em></strong></span></span></dt><dd><p> + Specifies the maximum Java heap size in megabytes. The default is 256. + More memory may be required to analyze very large programs or libraries. + </p></dd><dt><span class="term"><span class="command"><strong>-debug</strong></span></span></dt><dd><p> + Prints a trace of detectors run and classes analyzed to standard output. + Useful for troubleshooting unexpected analysis failures. + </p></dd><dt><span class="term"><span class="command"><strong>-property</strong></span> <em class="replaceable"><code>name=value</code></em></span></dt><dd><p> + This option sets a system property. <span class="application">FindBugs</span> uses system properties + to configure analysis options. See <a class="xref" href="analysisprops.html" title="Chapter 9. Analysis Properties">Chapter 9, <i>Analysis Properties</i></a>. + You can use this option multiple times in order to set multiple properties. + Note: In most versions of Windows, the <em class="replaceable"><code>name=value</code></em> + string must be in quotes. + </p></dd></dl></div></div></div></div><div class="sect1" title="3. Command-line Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="commandLineOptions"></a>3. Command-line Options</h2></div></div></div><p> + This section describes the command line options supported by <span class="application">FindBugs</span>. + These command line options may be used when invoking <span class="application">FindBugs</span> directly, + or when using a wrapper script. +</p><div class="sect2" title="3.1. Common command-line options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e796"></a>3.1. Common command-line options</h3></div></div></div><p> +These options may be used with both the GUI and command-line interfaces. +</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-effort:min</strong></span></span></dt><dd><p> + This option disables analyses that increase precision but also + increase memory consumption. You may want to try this option if + you find that <span class="application">FindBugs</span> runs out of memory, or takes an unusually + long time to complete its analysis. + </p></dd><dt><span class="term"><span class="command"><strong>-effort:max</strong></span></span></dt><dd><p> + Enable analyses which increase precision and find more bugs, but which + may require more memory and take more time to complete. + </p></dd><dt><span class="term"><span class="command"><strong>-project</strong></span> <em class="replaceable"><code>project</code></em></span></dt><dd><p> + Specify a project to be analyzed. The project file you specify should + be one that was created using the GUI interface. It will typically end + in the extension <code class="filename">.fb</code> or <code class="filename">.fbp</code>. + </p></dd></dl></div></div><div class="sect2" title="3.2. GUI Options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e836"></a>3.2. GUI Options</h3></div></div></div><p> +These options are only accepted by the Graphical User Interface. + +</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-look:</strong></span><em class="replaceable"><code>plastic|gtk|native</code></em></span></dt><dd><p> + Set Swing look and feel. + </p></dd></dl></div><p> +</p></div><div class="sect2" title="3.3. Text UI Options"><div class="titlepage"><div><div><h3 class="title"><a name="d0e852"></a>3.3. Text UI Options</h3></div></div></div><p> +These options are only accepted by the Text User Interface. +</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>-sortByClass</strong></span></span></dt><dd><p> + Sort reported bug instances by class name. + </p></dd><dt><span class="term"><span class="command"><strong>-include</strong></span> <em class="replaceable"><code>filterFile.xml</code></em></span></dt><dd><p> + Only report bug instances that match the filter specified by <em class="replaceable"><code>filterFile.xml</code></em>. + See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. + </p></dd><dt><span class="term"><span class="command"><strong>-exclude</strong></span> <em class="replaceable"><code>filterFile.xml</code></em></span></dt><dd><p> + Report all bug instances except those matching the filter specified by <em class="replaceable"><code>filterFile.xml</code></em>. + See <a class="xref" href="filter.html" title="Chapter 8. Filter Files">Chapter 8, <i>Filter Files</i></a>. + </p></dd><dt><span class="term"><span class="command"><strong>-onlyAnalyze</strong></span> <em class="replaceable"><code>com.foobar.MyClass,com.foobar.mypkg.*</code></em></span></dt><dd><p> + Restrict analysis to find bugs to given comma-separated list of + classes and packages. + Unlike filtering, this option avoids running analysis on + classes and packages that are not explicitly matched: + for large projects, this may greatly reduce the amount of time + needed to run the analysis. (However, some detectors may produce + inaccurate results if they aren't run on the entire application.) + Classes should be specified using their full classnames (including + package), and packages should be specified in the same way + they would in a Java <code class="literal">import</code> statement to + import all classes in the package (i.e., add <code class="literal">.*</code> + to the full name of the package). + Replace <code class="literal">.*</code> with <code class="literal">.-</code> to also + analyze all subpackages. + </p></dd><dt><span class="term"><span class="command"><strong>-low</strong></span></span></dt><dd><p> + Report all bugs. + </p></dd><dt><span class="term"><span class="command"><strong>-medium</strong></span></span></dt><dd><p> + Report medium and high priority bugs. This is the default setting. + </p></dd><dt><span class="term"><span class="command"><strong>-high</strong></span></span></dt><dd><p> + Report only high priority bugs. + </p></dd><dt><span class="term"><span class="command"><strong>-relaxed</strong></span></span></dt><dd><p> + Relaxed reporting mode. For many detectors, this option + suppresses the heuristics used to avoid reporting false positives. + </p></dd><dt><span class="term"><span class="command"><strong>-xml</strong></span></span></dt><dd><p> + Produce the bug reports as XML. The XML data produced may be + viewed in the GUI at a later time. You may also specify this + option as <span class="command"><strong>-xml:withMessages</strong></span>; when this variant + of the option is used, the XML output will contain human-readable + messages describing the warnings contained in the file. + XML files generated this way are easy to transform into reports. + </p></dd><dt><span class="term"><span class="command"><strong>-html</strong></span></span></dt><dd><p> + Generate HTML output. By default, <span class="application">FindBugs</span> will use the <code class="filename">default.xsl</code> + <a class="ulink" href="http://www.w3.org/TR/xslt" target="_top">XSLT</a> + stylesheet to generate the HTML: you can find this file in <code class="filename">findbugs.jar</code>, + or in the <span class="application">FindBugs</span> source or binary distributions. Variants of this option include + <span class="command"><strong>-html:plain.xsl</strong></span>, <span class="command"><strong>-html:fancy.xsl</strong></span> and <span class="command"><strong>-html:fancy-hist.xsl</strong></span>. + The <code class="filename">plain.xsl</code> stylesheet does not use Javascript or DOM, + and may work better with older web browsers, or for printing. The <code class="filename">fancy.xsl</code> + stylesheet uses DOM and Javascript for navigation and CSS for + visual presentation. The <span class="command"><strong>fancy-hist.xsl</strong></span> an evolution of <span class="command"><strong>fancy.xsl</strong></span> stylesheet. + It makes an extensive use of DOM and Javascript for dynamically filtering the lists of bugs. + </p><p> + If you want to specify your own + XSLT stylesheet to perform the transformation to HTML, specify the option as + <span class="command"><strong>-html:<em class="replaceable"><code>myStylesheet.xsl</code></em></strong></span>, + where <em class="replaceable"><code>myStylesheet.xsl</code></em> is the filename of the + stylesheet you want to use. + </p></dd><dt><span class="term"><span class="command"><strong>-emacs</strong></span></span></dt><dd><p> + Produce the bug reports in Emacs format. + </p></dd><dt><span class="term"><span class="command"><strong>-xdocs</strong></span></span></dt><dd><p> + Produce the bug reports in xdoc XML format for use with Apache Maven. + </p></dd><dt><span class="term"><span class="command"><strong>-output</strong></span> <em class="replaceable"><code>filename</code></em></span></dt><dd><p> + Produce the output in the specified file. + </p></dd><dt><span class="term"><span class="command"><strong>-outputFile</strong></span> <em class="replaceable"><code>filename</code></em></span></dt><dd><p> + This argument is deprecated. Use <span class="command"><strong>-output</strong></span> instead. + </p></dd><dt><span class="term"><span class="command"><strong>-nested</strong></span><em class="replaceable"><code>[:true|false]</code></em></span></dt><dd><p> + This option enables or disables scanning of nested jar and zip files found in + the list of files and directories to be analyzed. + By default, scanning of nested jar/zip files is enabled. + To disable it, add <span class="command"><strong>-nested:false</strong></span> to the command line + arguments. + </p></dd><dt><span class="term"><span class="command"><strong>-auxclasspath</strong></span> <em class="replaceable"><code>classpath</code></em></span></dt><dd><p> + Set the auxiliary classpath for analysis. This classpath should include all + jar files and directories containing classes that are part of the program + being analyzed but you do not want to have analyzed for bugs. + </p></dd><dt><span class="term"><span class="command"><strong>-userPrefs</strong></span> <em class="replaceable"><code>edu.umd.cs.findbugs.core.prefs</code></em></span></dt><dd><p> + Set the path of the user preferences file to use, which might override some of the options abobe. + Specifying <code class="literal">userPrefs</code> as first argument would mean some later + options will override them, as last argument would mean they will override some previous options). + This rationale behind this option is to reuse FindBugs Eclipse project settings for command + line execution. + </p></dd></dl></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="building.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="gui.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Building <span class="application">FindBugs</span>™ from Source </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Using the <span class="application">FindBugs</span> GUI</td></tr></table></div></body></html>
\ No newline at end of file |