<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"                    "file:../etc/docbook/docbookx.dtd" [<!ENTITY FindBugs "<application>FindBugs</application>"><!ENTITY Ant "<application>Ant</application>"><!ENTITY Saxon "<application>Saxon</application>"><!ENTITY FBHome "<replaceable>$FINDBUGS_HOME</replaceable>"><!ENTITY FBHomeWin "<replaceable>&#x25;FINDBUGS_HOME&#x25;</replaceable>"><!ENTITY nbsp "&#160;">]> <book lang="en" id="findbugs-manual"> <bookinfo><title>&FindBugs;&trade; Manual</title><authorgroup>  <author>    <firstname>David</firstname>    <othername>H.</othername>    <surname>Hovemeyer</surname>  </author>	<author>		<firstname>William</firstname>		<othername>W.</othername>		<surname>Pugh</surname>	</author></authorgroup><copyright>  <year>2003</year>  <year>2004</year>  <year>2005</year>  <year>2006</year>  <year>2008</year>  <holder>University of Maryland</holder></copyright><legalnotice><para>This manual is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License.To view a copy of this license, visit<ulink url="http://creativecommons.org/licenses/by-nc-sa/1.0/">http://creativecommons.org/licenses/by-nc-sa/1.0/</ulink>or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.</para><para>The name FindBugs and the FindBugs logo are trademarked by the University of Maryland.</para></legalnotice><edition>1.3.8</edition><pubdate>13:06:06 EDT, 15 March, 2009</pubdate></bookinfo><!--   **************************************************************************   Introduction   **************************************************************************--> <chapter id="introduction"><title>Introduction</title><para> &FindBugs;&trade; is a program to find bugs in Java programs.  It looks for instancesof "bug patterns" --- code instances that are likely to be errors.</para><para> This document describes version 1.3.8 of &FindBugs;.Weare very interested in getting your feedback on &FindBugs;. Please visitthe <ulink url="http://findbugs.sourceforge.net">&FindBugs; web page</ulink> forthe latest information on &FindBugs;, contact information, and support resources suchas information about the &FindBugs; mailing lists.</para><sect1><title>Requirements</title><para> To use &FindBugs;, you need a runtime environment compatible with<ulink url="http://java.sun.com/j2se">Java 2 Standard Edition</ulink>, version 1.5 or later.&FindBugs; is platform independent, and is known to run on GNU/Linux, Windows, andMacOS X platforms.</para><para>You should have at least 512 MB of memory to use &FindBugs;.To analyze very large projects, more memory may be needed.</para></sect1> </chapter><!--   **************************************************************************   Installing FindBugs   **************************************************************************--><chapter id="installing"><title>Installing &FindBugs;&trade;</title><para>This chapter explains how to install &FindBugs;.</para><sect1><title>Extracting the Distribution</title><para>The easiest way to install &FindBugs; is to download a binary distribution.Binary distributions are available in<ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.8.tar.gz?download">gzipped tar format</ulink> and<ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.8.zip?download">zip format</ulink>.Once you have downloaded a binary distribution, extract it into a directory of your choice.</para><para>Extracting a gzipped tar format distribution:<screen><prompt>$ </prompt><command>gunzip -c findbugs-1.3.8.tar.gz | tar xvf -</command></screen></para><para>Extracting a zip format distribution:<screen><prompt>C:\Software></prompt><command>unzip findbugs-1.3.8.zip</command></screen></para><para>Usually, extracting a binary distribution will create a directory ending in<filename class="directory">findbugs-1.3.8</filename>. For example, if you extractedthe binary distribution from the <filename class="directory">C:\Software</filename>directory, then the &FindBugs; software will be extracted into the directory<filename class="directory">C:\Software\findbugs-1.3.8</filename>.This directory is the &FindBugs; home directory.  We'll refer to it as&FBHome; (or &FBHomeWin; for Windows) throughout this manual.</para></sect1></chapter><!--   **************************************************************************   Compiling FindBugs from Source   **************************************************************************--><chapter id="building"><title>Building &FindBugs;&trade; from Source</title><para>This chapter describes how to build &FindBugs; from source code.  Unless you areinteresting in modifying &FindBugs;, you will probably want to skip to the<link linkend="running">next chapter</link>.</para><sect1><title>Prerequisites</title><para>To compile &FindBugs; from source, you will need the following:<itemizedlist>  <listitem>    <para>      The <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-1.3.8-source.zip?download"      >&FindBugs; source distribution</ulink>    </para>  </listitem>  <listitem>    <para>      <ulink url="http://java.sun.com/j2se/">JDK 1.5.0 beta or later</ulink>    </para>  </listitem>  <listitem>    <para>      <ulink url="http://ant.apache.org/">Apache &Ant;</ulink>, version 1.6.3 or later    </para>  </listitem></itemizedlist></para><warning>	<para>		The version of &Ant; included as <filename>/usr/bin/ant</filename> on		Redhat Linux systems will <emphasis>not</emphasis> work for compiling		&FindBugs;.  We recommend you install a binary distribution of &Ant;		downloaded from the <ulink url="http://ant.apache.org/">&Ant; website</ulink>.		Make sure that when you run &Ant; your <replaceable>JAVA_HOME</replaceable>		environment variable points to the directory in which you installed		JDK 1.5 (or later).	</para></warning><para>If you want to be able to generate formatted versions of the &FindBugs; documentation,you will also need the following software:<itemizedlist>  <listitem>    <para>    The <ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">DocBook XSL Stylesheets</ulink>.    These are required to convert the &FindBugs; manual into HTML format.    </para>  </listitem>  <listitem>    <para>      The <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>.      (Also required for converting the &FindBugs; manual to HTML.)    </para>  </listitem><!--  <listitem>    <para>    </para>  </listitem>--></itemizedlist></para></sect1><sect1><title>Extracting the Source Distribution</title><para>After you download the source distribution, you'll need to extract it intoa working directory.  A typical command to do this is:<screen><prompt>$ </prompt><command>unzip findbugs-1.3.8-source.zip</command></screen></para></sect1><sect1><title>Modifying <filename>local.properties</filename></title><para>If you intend to build the FindBugs documentation,you will need to modify the <filename>local.properties</filename> fileused by the <ulink url="http://ant.apache.org/">&Ant;</ulink><filename>build.xml</filename> file to build &FindBugs;.If you do not want to build the FindBugs documentation, then youcan ignore this file.</para>	<para>The <filename>local.properties</filename> overrides definitionsin the <filename>build.properties</filename> file.The <filename>build.properties</filename> file looks something like this:<programlisting><![CDATA[# 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]]></programlisting></para><para>The <varname>xsl.stylesheet.home</varname> property specifies the fullpath to the directory where you have installed the<ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook Modular XSLStylesheets</ulink>.  You only need to specify this property if you will begenerating the &FindBugs; documentation.</para><para>The <varname>saxon.home</varname> property is the full path to thedirectory where you installed the <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>.You only need to specify this property if you will begenerating the &FindBugs; documentation.</para></sect1><sect1><title>Running &Ant;</title><para>Once you have extracted the source distribution,made sure that &Ant; is installed,modified <filename>build.properties</filename> (optional),and configured the tools (such as &Saxon;),you are ready to build &FindBugs;.  Invoking &Ant; is a simple matterof running the command<screen><prompt>$ </prompt><command>ant <replaceable>target</replaceable></command></screen>where <replaceable>target</replaceable> is one of the following:<variablelist>  <varlistentry>    <term><command>build</command></term>    <listitem>       <para>         This target compiles the code for &FindBugs;. It is the default target.       </para>    </listitem>  </varlistentry>  <varlistentry>    <term><command>docs</command></term>    <listitem>       <para>       This target formats the documentation.  (It also compiles some of       the source code as a side-effect.)       </para>    </listitem>  </varlistentry>    <varlistentry>	<term><command>runjunit</command></term>	<listitem>		<para>			This target compiles and runs the internal JUnit tests included			in &FindBugs;.  It will print an error message if any unit			tests fail.		</para>	</listitem>  </varlistentry>    <varlistentry>	<term><command>bindist</command></term>	<listitem>		<para>			Builds a binary distribution of &FindBugs;.			The target creates both <filename>.zip</filename> and			<filename>.tar.gz</filename> archives.		</para>	</listitem>  </varlistentry></variablelist></para><para>After running an &Ant; command, you should see output similar tothe following (after some other messages regarding the tasks that&Ant; is running):<screen><computeroutput>BUILD SUCCESSFULTotal time: 17 seconds</computeroutput></screen></para></sect1><sect1><title>Running &FindBugs;&trade; from a source directory</title><para>The &Ant; build script for &FindBugs; is written such that after building the <command>build</command> target, the working directoryis set up just like a binary distribution.  So, the information aboutrunning &FindBugs; in <xref linkend="running" />applies to source distributions, too.</para></sect1></chapter><!--   **************************************************************************   Running FindBugs   **************************************************************************--><chapter id="running"><title>Running &FindBugs;&trade;</title><para>&FindBugs; has two user interfaces: a graphical user interface (GUI) and acommand line user interface.  This chapter describes how to run each of these user interfaces.</para>	<warning>		<para>			This chapter is in the process of being re-written.			The rewrite is not complete yet.		</para>	</warning><!--<sect1><title>Executing the &FindBugs;&trade; GUI</title></sect1>--><sect1>	<title>Quick Start</title>	<para>		If you are running &FindBugs; on a  Windows system,		double-click on the file <filename>&FBHomeWin;\lib\findbugs.jar</filename> to start the &FindBugs; GUI.	</para>		<para>		On a Unix, Linux, or Mac OS X system, run the <filename>&FBHome;/bin/findbugs</filename>		script, or run the command <screen><command>java -jar &FBHome;/lib/findbugs.jar</command></screen>	to run the &FindBugs; GUI.	</para>		<para>	Refer to <xref linkend="gui"/> for information on how to use the GUI.	</para></sect1><sect1>		<title>Executing &FindBugs;</title>	<para>		This section describes how to invoke the &FindBugs; program.		There are two ways to invoke &FindBugs;: directly, or using a		wrapper script.	</para>