option as <command>-xml:withMessages</command>; 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.    </para>  </listitem>  </varlistentry>  <varlistentry>  <term><command>-html</command></term>  <listitem>    <para>    Generate HTML output.  By default, &FindBugs; will use the <filename>default.xsl</filename>    <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink>    stylesheet to generate the HTML: you can find this file in <filename>findbugs.jar</filename>,    or in the &FindBugs; source or binary distributions.  Variants of this option include	<command>-html:plain.xsl</command>, <command>-html:fancy.xsl</command> and <command>-html:fancy-hist.xsl</command>.	The <filename>plain.xsl</filename> stylesheet does not use Javascript or DOM,	and may work better with older web browsers, or for printing.  The <filename>fancy.xsl</filename>	stylesheet uses DOM and Javascript for navigation and CSS for	visual presentation. The <command>fancy-hist.xsl</command> an evolution of <command>fancy.xsl</command> stylesheet.	It makes an extensive use of DOM and Javascript for dynamically filtering the lists of bugs.	</para>					<para>  	If you want to specify your own    XSLT stylesheet to perform the transformation to HTML, specify the option as    <command>-html:<replaceable>myStylesheet.xsl</replaceable></command>,    where <replaceable>myStylesheet.xsl</replaceable> is the filename of the    stylesheet you want to use.    </para>  </listitem>  </varlistentry>  <varlistentry>  <term><command>-emacs</command></term>  <listitem>    <para>    Produce the bug reports in Emacs format.    </para>  </listitem>  </varlistentry>  <varlistentry>  <term><command>-xdocs</command></term>  <listitem>    <para>    Produce the bug reports in xdoc XML format for use with Apache Maven.    </para>  </listitem>  </varlistentry>  <varlistentry>    <term><command>-output</command> <replaceable>filename</replaceable></term>    <listitem>       <para>       Produce the output in the specified file.       </para>    </listitem>  </varlistentry>  <varlistentry>    <term><command>-outputFile</command> <replaceable>filename</replaceable></term>    <listitem>       <para>       This argument is deprecated.  Use <command>-output</command> instead.       </para>    </listitem>  </varlistentry>  <varlistentry>  <term><command>-nested</command><replaceable>[:true|false]</replaceable></term>  <listitem>    <para>    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 <command>-nested:false</command> to the command line    arguments.    </para>  </listitem>  </varlistentry>  <varlistentry>  <term><command>-auxclasspath</command> <replaceable>classpath</replaceable></term>  <listitem>    <para>    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.    </para>  </listitem>  </varlistentry><!--  <varlistentry>  <term><command></command> <replaceable></replaceable></term>  <listitem>    <para>    </para>  </listitem>  </varlistentry>--></variablelist></sect2></sect1></chapter><chapter id="gui">	<title>Using the &FindBugs; GUI</title>	<para>		This chapter describes how to use the &FindBugs; graphical user interface (GUI).	</para><sect1><title>Creating a Project</title><para>After you have started &FindBugs; using the <command>findbugs</command> command,choose the <menuchoice><guimenu>File</guimenu><guimenuitem>New Project</guimenuitem></menuchoice>menu item.  You will see a dialog which looks like this:<mediaobject><imageobject><imagedata fileref="project-dialog.png"  /></imageobject></mediaobject></para><para>Use the "Add" button next to the "Class archives and directories to analyze" text field to select a Java archivefile (zip, jar, ear, or war file) or directory containing java classes to analyze for bugs.  You may add multiplearchives/directories.</para><para>You can also add the source directories which containthe source code for the Java archives you are analyzing.  This will enable&FindBugs; to highlight the source code which contains a possible error.The source directories you add should be the roots of the Javapackage hierarchy.  For example, if your application is contained in the<varname>org.foobar.myapp</varname> package, you should add theparent directory of the <filename class="directory">org</filename> directoryto the source directory list for the project.</para><para>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 analyzinghave references to other classes which are not included in the analyzedarchives/directories and are not in the standard runtime classpath.  Some of the bugpattern detectors in &FindBugs; make use of class hierarchy information,so you will get more accurate results if the entire class hierarchy isavailable which &FindBugs; performs its analysis.</para></sect1><sect1><title>Running the Analysis</title><para>Once you have added all of the archives, directories, and source directories,click the "Finish" button to analyze the classes contained in theJar files.  Note that for a very large program on an older computer,this may take quite a while (tens of minutes).  A recent computer withample memory will typically be able to analyze a large program in only afew minutes.</para></sect1><sect1><title>Browsing Results</title><para>When the analysis completes, you will see a screen like the following:<mediaobject>  <imageobject>    <imagedata fileref="example-details.png"  />  </imageobject></mediaobject></para><para>The upper left-hand pane of the window shows the bug tree; this is a hierarchicalrepresentation of all of the potential bugs detected in the analyzedJar files.</para><para>When you select a particular bug instance in the top pane, you willsee 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 theprogram 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.  Thesource code window highlights the line where the stream object is created.</para><para>You may add a textual annotations to bug instances.  To do so, type theminto the text box just below the hierarchical view.  You can type anyinformation which you would like to record.  When you load and save bugresults files, the annotations are preserved.</para></sect1><sect1><title>Saving and Opening</title><para>You may use the <menuchoice><guimenu>File</guimenu><guimenuitem>Save as...</guimenuitem></menuchoice>menu option to save your work.  To save your work, including the jarfile 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 jarfile lists ("FindBugs project file (.fbp)") or just the results("FindBugs analysis file (.fba)").A saved file may be loaded with the<menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice>menu option.</para></sect1><!--<sect1 id="textui"><title>Using the &FindBugs;&trade; Command Line Interface</title><para>The &FindBugs; Command Line Interface (or Text UI) can be used toanalyze an application for bugs non-interactively.  Each bug instance will bereported on a single line.  All output is written to the standard output file descriptor.<xref linkend="filter" /> explains how bug reports may be filtered in orderto get only the output you're interested in.</para><para>See <xref linkend="commandLineOptions" /> for a description of how to invoke theCommand Line Interface.</para></sect1>--></chapter><!--   **************************************************************************   Using the FindBugs Ant task   **************************************************************************--><chapter id="anttask"><title>Using the &FindBugs;&trade; &Ant; task</title><para>This chapter describes how to integrate &FindBugs; into a build scriptfor <ulink url="http://ant.apache.org/">&Ant;</ulink>, which is a popular Java buildand deployment tool.  Using the &FindBugs; &Ant; task, your build script canautomatically run &FindBugs; on your Java code.</para><para>The &Ant; task was generously contributed by Mike Fagan.</para><sect1><title>Installing the &Ant; task</title><para>To install the &Ant; task, simply copy <filename>&FBHome;/lib/findbugs-ant.jar</filename>into the <filename>lib</filename> subdirectory of your &Ant; installation.<note><para>It is strongly recommended that you use the &Ant; task with the versionof &FindBugs; it was included with.  We do not guarantee that the &Ant; task Jar filewill work with any version of &FindBugs; other than the one it was included with.</para></note></para></sect1><sect1><title>Modifying build.xml</title><para>To incorporate &FindBugs; into <filename>build.xml</filename> (the build scriptfor &Ant;), you first need to add a task definition.  This should appear as follows:<screen>  &lt;taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/&gt;</screen>The task definition specifies that when a <literal>findbugs</literal> element isseen in <filename>build.xml</filename>, it should use the indicated class to execute the task.</para><para>After you have added the task definition, you can define a targetwhich uses the <literal>findbugs</literal> task.  Here is an examplewhich could be added to the <filename>build.xml</filename> for theApache <ulink url="http://jakarta.apache.org/bcel/">BCEL</ulink> library.<screen>  &lt;property name="findbugs.home" value="/export/home/daveho/work/findbugs" /&gt;  &lt;target name="findbugs" depends="jar"&gt;    &lt;findbugs home="${findbugs.home}"              output="xml"              outputFile="bcel-fb.xml" &gt;      &lt;auxClasspath path="${basedir}/lib/Regex.jar" /&gt;      &lt;sourcePath path="${basedir}/src/java" /&gt;      &lt;class location="${basedir}/bin/bcel.jar" /&gt;    &lt;/findbugs&gt;  &lt;/target&gt;</screen>The <literal>findbugs</literal> element must have the <literal>home</literal>attribute set to the directory in which &FindBugs; is installed; in other words,&FBHome;.  See <xref linkend="installing" />.</para><para>This target will execute &FindBugs; on <filename>bcel.jar</filename>, which is theJar 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 &FindBugs; on it.)The output of &FindBugs; will be saved in XML format to a file called<filename>bcel-fb.xml</filename>.An auxiliary Jar file, <filename>Regex.jar</filename>, is added to the aux classpath,because it is referenced by the main BCEL library.  A source path is specifiedso that the saved bug data will have accurate references to the BCEL source code.</para></sect1><sect1><title>Executing the task</title><para>Here is an example of invoking &Ant; from the command line, using the <literal>findbugs</literal>target defined above.<screen>  <prompt>[daveho@noir]$</prompt> <command>ant findbugs</command>  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</screen>In this case, because we saved the bug results in an XML file, we canuse the &FindBugs; GUI to view the results; see <xref linkend="running"/>.</para></sect1><sect1><title>Parameters</title><para>This section describes the parameters that may be specified whenusing the &FindBugs; task.<variablelist>  <varlistentry>    <term><literal>class</literal></term>    <listitem>       <para>       A nested element specifying which classes to analyze.  The <literal>class</literal>       element must specify a <literal>location</literal> attribute which names the       archive file (jar, zip, etc.), directory, or class file to be analyzed.  Multiple <literal>class</literal>       elements may be specified as children of a single <literal>findbugs</literal> element.       </para>    </listitem>  </varlistentry>  <varlistentry>    <term><literal>auxClasspath</literal></term>    <listitem>       <para>       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       &Ant;'s <literal>classpath</literal> element for the Java task.       </para>    </listitem>  </varlistentry>  <varlistentry>    <term><literal>sourcePath</literal></term>    <listitem>       <para>       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.       </para>    </listitem>  </varlistentry>  <varlistentry>    <term><literal>home</literal></term>    <listitem>       <para>       A required attribute.       It must be set to the name of the directory where &FindBugs; is installed.       </para>    </listitem>  </varlistentry>