1 <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> 2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 3 "file:../etc/docbook/docbookx.dtd" [ 4 <!ENTITY FindBugs "<application>FindBugs</application>"> 5 <!ENTITY Ant "<application>Ant</application>"> 6 <!ENTITY Saxon "<application>Saxon</application>"> 7 <!ENTITY FBHome "<replaceable>$FINDBUGS_HOME</replaceable>"> 8 <!ENTITY FBHomeWin "<replaceable>%FINDBUGS_HOME%</replaceable>"> 9 <!ENTITY nbsp " "> 10 ]> 11 12 <book lang="en" id="findbugs-manual"> 13 14 <bookinfo> 15 <title>&FindBugs;™ Manual</title> 16 17 <authorgroup> 18 <author> 19 <firstname>David</firstname> 20 <othername>H.</othername> 21 <surname>Hovemeyer</surname> 22 </author> 23 <author> 24 <firstname>William</firstname> 25 <othername>W.</othername> 26 <surname>Pugh</surname> 27 </author> 28 </authorgroup> 29 30 <copyright> 31 <year>2003 - 2012</year> 32 <holder>University of Maryland</holder> 33 </copyright> 34 35 <legalnotice> 36 <para> 37 This manual is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. 38 To view a copy of this license, visit 39 <ulink url="http://creativecommons.org/licenses/by-nc-sa/1.0/">http://creativecommons.org/licenses/by-nc-sa/1.0/</ulink> 40 or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. 41 </para> 42 <para> 43 The name FindBugs and the FindBugs logo are trademarked by the University of Maryland. 44 </para> 45 </legalnotice> 46 47 <edition>2.0.3</edition> 48 49 <pubdate>17:16:15 EST, 22 November, 2013</pubdate> 50 51 </bookinfo> 52 53 <!-- 54 ************************************************************************** 55 Introduction 56 ************************************************************************** 57 --> 58 59 <chapter id="introduction"> 60 <title>Introduction</title> 61 62 <para> &FindBugs;™ is a program to find bugs in Java programs. It looks for instances 63 of "bug patterns" --- code instances that are likely to be errors.</para> 64 65 <para> This document describes version 2.0.3 of &FindBugs;.We 66 are very interested in getting your feedback on &FindBugs;. Please visit 67 the <ulink url="http://findbugs.sourceforge.net">&FindBugs; web page</ulink> for 68 the latest information on &FindBugs;, contact information, and support resources such 69 as information about the &FindBugs; mailing lists.</para> 70 71 <sect1> 72 <title>Requirements</title> 73 <para> To use &FindBugs;, you need a runtime environment compatible with 74 <ulink url="http://java.sun.com/j2se">Java 2 Standard Edition</ulink>, version 1.5 or later. 75 &FindBugs; is platform independent, and is known to run on GNU/Linux, Windows, and 76 MacOS X platforms.</para> 77 78 <para>You should have at least 512 MB of memory to use &FindBugs;. 79 To analyze very large projects, more memory may be needed.</para> 80 </sect1> 81 82 </chapter> 83 84 <!-- 85 ************************************************************************** 86 Installing FindBugs 87 ************************************************************************** 88 --> 89 90 <chapter id="installing"> 91 <title>Installing &FindBugs;™</title> 92 93 <para> 94 This chapter explains how to install &FindBugs;. 95 </para> 96 97 <sect1> 98 <title>Extracting the Distribution</title> 99 100 <para> 101 The easiest way to install &FindBugs; is to download a binary distribution. 102 Binary distributions are available in 103 <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.tar.gz?download">gzipped tar format</ulink> and 104 <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3.zip?download">zip format</ulink>. 105 Once you have downloaded a binary distribution, extract it into a directory of your choice. 106 </para> 107 108 <para> 109 Extracting a gzipped tar format distribution: 110 <screen> 111 <prompt>$ </prompt><command>gunzip -c findbugs-2.0.3.tar.gz | tar xvf -</command> 112 </screen> 113 </para> 114 115 <para> 116 Extracting a zip format distribution: 117 <screen> 118 <prompt>C:\Software></prompt><command>unzip findbugs-2.0.3.zip</command> 119 </screen> 120 </para> 121 122 <para> 123 Usually, extracting a binary distribution will create a directory ending in 124 <filename class="directory">findbugs-2.0.3</filename>. For example, if you extracted 125 the binary distribution from the <filename class="directory">C:\Software</filename> 126 directory, then the &FindBugs; software will be extracted into the directory 127 <filename class="directory">C:\Software\findbugs-2.0.3</filename>. 128 This directory is the &FindBugs; home directory. We'll refer to it as 129 &FBHome; (or &FBHomeWin; for Windows) throughout this manual. 130 </para> 131 </sect1> 132 133 </chapter> 134 135 <!-- 136 ************************************************************************** 137 Compiling FindBugs from Source 138 ************************************************************************** 139 --> 140 141 <chapter id="building"> 142 <title>Building &FindBugs;™ from Source</title> 143 144 <para> 145 This chapter describes how to build &FindBugs; from source code. Unless you are 146 interesting in modifying &FindBugs;, you will probably want to skip to the 147 <link linkend="running">next chapter</link>. 148 </para> 149 150 <sect1> 151 <title>Prerequisites</title> 152 153 <para> 154 To compile &FindBugs; from source, you will need the following: 155 <itemizedlist> 156 <listitem> 157 <para> 158 The <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-2.0.3-source.zip?download" 159 >&FindBugs; source distribution</ulink> 160 </para> 161 </listitem> 162 <listitem> 163 <para> 164 <ulink url="http://java.sun.com/j2se/">JDK 1.5.0 or later</ulink> 165 </para> 166 </listitem> 167 <listitem> 168 <para> 169 <ulink url="http://ant.apache.org/">Apache &Ant;</ulink>, version 1.6.3 or later 170 </para> 171 </listitem> 172 </itemizedlist> 173 </para> 174 175 <warning> 176 <para> 177 The version of &Ant; included as <filename>/usr/bin/ant</filename> on 178 Redhat Linux systems will <emphasis>not</emphasis> work for compiling 179 &FindBugs;. We recommend you install a binary distribution of &Ant; 180 downloaded from the <ulink url="http://ant.apache.org/">&Ant; website</ulink>. 181 Make sure that when you run &Ant; your <replaceable>JAVA_HOME</replaceable> 182 environment variable points to the directory in which you installed 183 JDK 1.5 (or later). 184 </para> 185 </warning> 186 187 <para> 188 If you want to be able to generate formatted versions of the &FindBugs; documentation, 189 you will also need the following software: 190 <itemizedlist> 191 <listitem> 192 <para> 193 The <ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">DocBook XSL Stylesheets</ulink>. 194 These are required to convert the &FindBugs; manual into HTML format. 195 </para> 196 </listitem> 197 <listitem> 198 <para> 199 The <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>. 200 (Also required for converting the &FindBugs; manual to HTML.) 201 </para> 202 </listitem> 203 <!-- 204 <listitem> 205 <para> 206 </para> 207 </listitem> 208 --> 209 </itemizedlist> 210 </para> 211 212 </sect1> 213 214 <sect1> 215 <title>Extracting the Source Distribution</title> 216 <para> 217 After you download the source distribution, you'll need to extract it into 218 a working directory. A typical command to do this is: 219 220 <screen> 221 <prompt>$ </prompt><command>unzip findbugs-2.0.3-source.zip</command> 222 </screen> 223 224 </para> 225 </sect1> 226 227 <sect1> 228 <title>Modifying <filename>local.properties</filename></title> 229 <para> 230 If you intend to build the FindBugs documentation, 231 you will need to modify the <filename>local.properties</filename> file 232 used by the <ulink url="http://ant.apache.org/">&Ant;</ulink> 233 <filename>build.xml</filename> file to build &FindBugs;. 234 If you do not want to build the FindBugs documentation, then you 235 can ignore this file. 236 </para> 237 238 <para> 239 The <filename>local.properties</filename> overrides definitions 240 in the <filename>build.properties</filename> file. 241 The <filename>build.properties</filename> file looks something like this: 242 <programlisting> 243 <![CDATA[ 244 # User Configuration: 245 # This section must be modified to reflect your system. 246 247 local.software.home =/export/home/daveho/linux 248 249 # Set this to the directory containing the DocBook Modular XSL Stylesheets 250 # from http://docbook.sourceforge.net/projects/xsl/ 251 252 xsl.stylesheet.home =${local.software.home}/docbook/docbook-xsl-1.71.1 253 254 # Set this to the directory where Saxon (http://saxon.sourceforge.net/) 255 # is installed. 256 257 saxon.home =${local.software.home}/java/saxon-6.5.5 258 ]]> 259 </programlisting> 260 </para> 261 262 <para> 263 The <varname>xsl.stylesheet.home</varname> property specifies the full 264 path to the directory where you have installed the 265 <ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook Modular XSL 266 Stylesheets</ulink>. You only need to specify this property if you will be 267 generating the &FindBugs; documentation. 268 </para> 269 270 <para> 271 The <varname>saxon.home</varname> property is the full path to the 272 directory where you installed the <ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT Processor</ulink>. 273 You only need to specify this property if you will be 274 generating the &FindBugs; documentation. 275 </para> 276 277 </sect1> 278 279 <sect1> 280 <title>Running &Ant;</title> 281 282 <para> 283 Once you have extracted the source distribution, 284 made sure that &Ant; is installed, 285 modified <filename>build.properties</filename> (optional), 286 and configured the tools (such as &Saxon;), 287 you are ready to build &FindBugs;. Invoking &Ant; is a simple matter 288 of running the command 289 <screen> 290 <prompt>$ </prompt><command>ant <replaceable>target</replaceable></command> 291 </screen> 292 where <replaceable>target</replaceable> is one of the following: 293 <variablelist> 294 <varlistentry> 295 <term><command>build</command></term> 296 <listitem> 297 <para> 298 This target compiles the code for &FindBugs;. It is the default target. 299 </para> 300 </listitem> 301 </varlistentry> 302 303 <varlistentry> 304 <term><command>docs</command></term> 305 <listitem> 306 <para> 307 This target formats the documentation. (It also compiles some of 308 the source code as a side-effect.) 309 </para> 310 </listitem> 311 </varlistentry> 312 313 <varlistentry> 314 <term><command>runjunit</command></term> 315 <listitem> 316 <para> 317 This target compiles and runs the internal JUnit tests included 318 in &FindBugs;. It will print an error message if any unit 319 tests fail. 320 </para> 321 </listitem> 322 </varlistentry> 323 324 <varlistentry> 325 <term><command>bindist</command></term> 326 <listitem> 327 <para> 328 Builds a binary distribution of &FindBugs;. 329 The target creates both <filename>.zip</filename> and 330 <filename>.tar.gz</filename> archives. 331 </para> 332 </listitem> 333 </varlistentry> 334 </variablelist> 335 </para> 336 337 <para> 338 After running an &Ant; command, you should see output similar to 339 the following (after some other messages regarding the tasks that 340 &Ant; is running): 341 <screen> 342 <computeroutput> 343 BUILD SUCCESSFUL 344 Total time: 17 seconds 345 </computeroutput> 346 </screen> 347 </para> 348 349 </sect1> 350 351 <sect1> 352 <title>Running &FindBugs;™ from a source directory</title> 353 <para> 354 The &Ant; build script for &FindBugs; is written such that after 355 building the <command>build</command> target, the working directory 356 is set up just like a binary distribution. So, the information about 357 running &FindBugs; in <xref linkend="running" /> 358 applies to source distributions, too. 359 </para> 360 </sect1> 361 362 </chapter> 363 364 365 <!-- 366 ************************************************************************** 367 Running FindBugs 368 ************************************************************************** 369 --> 370 371 <chapter id="running"> 372 <title>Running &FindBugs;™</title> 373 374 <para> 375 &FindBugs; has two user interfaces: a graphical user interface (GUI) and a 376 command line user interface. This chapter describes 377 how to run each of these user interfaces. 378 </para> 379 380 <warning> 381 <para> 382 This chapter is in the process of being re-written. 383 The rewrite is not complete yet. 384 </para> 385 </warning> 386 387 <!-- 388 <sect1> 389 <title>Executing the &FindBugs;™ GUI</title> 390 </sect1> 391 --> 392 393 <sect1> 394 <title>Quick Start</title> 395 <para> 396 If you are running &FindBugs; on a Windows system, 397 double-click on the file <filename>&FBHomeWin;\lib\findbugs.jar</filename> to start the &FindBugs; GUI. 398 </para> 399 400 <para> 401 On a Unix, Linux, or Mac OS X system, run the <filename>&FBHome;/bin/findbugs</filename> 402 script, or run the command <screen> 403 <command>java -jar &FBHome;/lib/findbugs.jar</command></screen> 404 to run the &FindBugs; GUI. 405 </para> 406 407 <para> 408 Refer to <xref linkend="gui"/> for information on how to use the GUI. 409 </para> 410 </sect1> 411 412 <sect1> 413 414 <title>Executing &FindBugs;</title> 415 416 <para> 417 This section describes how to invoke the &FindBugs; program. 418 There are two ways to invoke &FindBugs;: directly, or using a 419 wrapper script. 420 </para> 421 422 423 <sect2 id="directInvocation"> 424 <title>Direct invocation of &FindBugs;</title> 425 426 <para> 427 The preferred method of running &FindBugs; is to directly execute 428 <filename>&FBHome;/lib/findbugs.jar</filename> using the <command>-jar</command> 429 command line switch of the JVM (<command>java</command>) executable. 430 (Versions of &FindBugs; prior to 1.3.5 required a wrapper script 431 to invoke &FindBugs;.) 432 </para> 433 434 <para> 435 The general syntax of invoking &FindBugs; directly is the following: 436 <screen> 437 <command>java <replaceable>[JVM arguments]</replaceable> -jar &FBHome;/lib/findbugs.jar <replaceable>options...</replaceable></command> 438 </screen> 439 </para> 440 441 <!-- 442 <para> 443 By default, executing <filename>findbugs.jar</filename> runs the 444 &FindBugs; graphical user interface (GUI). On windows systems, 445 you can double-click on <filename>findbugs.jar</filename> to launch 446 the GUI. From a command line, the command 447 <screen> 448 java -jar <replaceable>&FBHome;</replaceable>/lib/findbugs.jar</screen> 449 will launch the GUI. 450 </para> 451 --> 452 453 <sect3 id="chooseUI"> 454 <title>Choosing the User Interface</title> 455 456 <para> 457 The first command line option chooses the &FindBugs; user interface to execute. 458 Possible values are: 459 </para> 460 <itemizedlist> 461 <listitem> 462 <para> 463 <command>-gui</command>: runs the graphical user interface (GUI) 464 </para> 465 </listitem> 466 467 <listitem> 468 <para> 469 <command>-textui</command>: runs the command line user interface 470 </para> 471 </listitem> 472 473 <listitem> 474 <para> 475 <command>-version</command>: displays the &FindBugs; version number 476 </para> 477 </listitem> 478 479 <listitem> 480 <para> 481 <command>-help</command>: displays help information for the 482 &FindBugs; command line user interface 483 </para> 484 </listitem> 485 486 <listitem> 487 <para> 488 <command>-gui1</command>: executes the original (obsolete) 489 &FindBugs; graphical user interface 490 </para> 491 </listitem> 492 </itemizedlist> 493 494 </sect3> 495 496 <sect3 id="jvmArgs"> 497 <title>Java Virtual Machine (JVM) arguments</title> 498 499 <para> 500 Several Java Virtual Machine arguments are useful when invoking 501 &FindBugs;. 502 </para> 503 504 <variablelist> 505 <varlistentry> 506 <term><command>-Xmx<replaceable>NN</replaceable>m</command></term> 507 <listitem> 508 <para> 509 Set the maximum Java heap size to <replaceable>NN</replaceable> 510 megabytes. &FindBugs; generally requires a large amount of 511 memory. For a very large project, using 1500 megabytes 512 is not unusual. 513 </para> 514 </listitem> 515 </varlistentry> 516 517 <varlistentry> 518 <term><command>-D<replaceable>name</replaceable>=<replaceable>value</replaceable></command></term> 519 <listitem> 520 <para> 521 Set a Java system property. For example, you might use the 522 argument <command>-Duser.language=ja</command> to display 523 GUI messages in Japanese. 524 </para> 525 </listitem> 526 </varlistentry> 527 528 <!-- 529 <varlistentry> 530 <term></term> 531 <listitem> 532 <para> 533 </para> 534 </listitem> 535 </varlistentry> 536 --> 537 </variablelist> 538 </sect3> 539 540 </sect2> 541 542 <sect2 id="wrapperScript"> 543 <title>Invocation of &FindBugs; using a wrapper script</title> 544 545 <para> 546 Another way to run &FindBugs; is to use a wrapper script. 547 </para> 548 549 <para> 550 On Unix-like systems, use the following command to invoke the wrapper script: 551 <screen> 552 <prompt>$ </prompt><command>&FBHome;/bin/findbugs <replaceable>options...</replaceable></command> 553 </screen> 554 </para> 555 556 <para> 557 On Windows systems, the command to invoke the wrapper script is 558 <screen> 559 <prompt>C:\My Directory></prompt><command>&FBHomeWin;\bin\findbugs.bat <replaceable>options...</replaceable></command> 560 </screen> 561 </para> 562 563 <para> 564 On both Unix-like and Windows systems, you can simply add the <filename><replaceable>$FINDBUGS_HOME</replaceable>/bin</filename> 565 directory to your <filename>PATH</filename> environment variable and then invoke 566 FindBugs using the <command>findbugs</command> command. 567 </para> 568 569 <sect3 id="wrapperOptions"> 570 <title>Wrapper script command line options</title> 571 <para>The &FindBugs; wrapper scripts support the following command-line options. 572 Note that these command line options are <emphasis>not</emphasis> handled by 573 the &FindBugs; program per se; rather, they are handled by the wrapper 574 script. 575 </para> 576 <variablelist> 577 <varlistentry> 578 <term><command>-jvmArgs <replaceable>args</replaceable></command></term> 579 <listitem> 580 <para> 581 Specifies arguments to pass to the JVM. For example, you might want 582 to set a JVM property: 583 <screen> 584 <prompt>$ </prompt><command>findbugs -textui -jvmArgs "-Duser.language=ja" <replaceable>myApp.jar</replaceable></command> 585 </screen> 586 </para> 587 </listitem> 588 </varlistentry> 589 590 <varlistentry> 591 <term><command>-javahome <replaceable>directory</replaceable></command></term> 592 <listitem> 593 <para> 594 Specifies the directory containing the JRE (Java Runtime Environment) to 595 use to execute &FindBugs;. 596 </para> 597 </listitem> 598 </varlistentry> 599 600 <varlistentry> 601 <term><command>-maxHeap <replaceable>size</replaceable></command></term> 602 <listitem> 603 <para> 604 Specifies the maximum Java heap size in megabytes. The default is 256. 605 More memory may be required to analyze very large programs or libraries. 606 </para> 607 </listitem> 608 </varlistentry> 609 610 <varlistentry> 611 <term><command>-debug</command></term> 612 <listitem> 613 <para> 614 Prints a trace of detectors run and classes analyzed to standard output. 615 Useful for troubleshooting unexpected analysis failures. 616 </para> 617 </listitem> 618 </varlistentry> 619 620 <varlistentry> 621 <term><command>-property</command> <replaceable>name=value</replaceable></term> 622 <listitem> 623 <para> 624 This option sets a system property. &FindBugs; uses system properties 625 to configure analysis options. See <xref linkend="analysisprops"/>. 626 You can use this option multiple times in order to set multiple properties. 627 Note: In most versions of Windows, the <replaceable>name=value</replaceable> 628 string must be in quotes. 629 </para> 630 </listitem> 631 </varlistentry> 632 633 </variablelist> 634 635 </sect3> 636 637 </sect2> 638 639 </sect1> 640 641 <sect1 id="commandLineOptions"> 642 <title>Command-line Options</title> 643 644 <!-- 645 <para> 646 647 There are two ways to invoke &FindBugs;. The first invokes the the Graphical User Interface (GUI): 648 649 <screen> 650 <prompt>$ </prompt><command>findbugs <replaceable>[standard options]</replaceable> <replaceable>[GUI options]</replaceable></command> 651 </screen> 652 653 The second invokes the Command Line Interface (Text UI): 654 655 <screen> 656 <prompt>$ </prompt><command>findbugs -textui <replaceable>[standard options]</replaceable> <replaceable>[Text UI options]</replaceable></command> 657 </screen> 658 </para> 659 --> 660 661 <para> 662 This section describes the command line options supported by &FindBugs;. 663 These command line options may be used when invoking &FindBugs; directly, 664 or when using a wrapper script. 665 </para> 666 667 <sect2> 668 <title>Common command-line options</title> 669 670 <para> 671 These options may be used with both the GUI and command-line interfaces. 672 </para> 673 674 <variablelist> 675 676 <varlistentry> 677 <term><command>-effort:min</command></term> 678 <listitem> 679 <para> 680 This option disables analyses that increase precision but also 681 increase memory consumption. You may want to try this option if 682 you find that &FindBugs; runs out of memory, or takes an unusually 683 long time to complete its analysis. 684 </para> 685 </listitem> 686 </varlistentry> 687 688 689 <varlistentry> 690 <term><command>-effort:max</command></term> 691 <listitem> 692 <para> 693 Enable analyses which increase precision and find more bugs, but which 694 may require more memory and take more time to complete. 695 </para> 696 </listitem> 697 </varlistentry> 698 699 <varlistentry> 700 <term><command>-project</command> <replaceable>project</replaceable></term> 701 <listitem> 702 <para> 703 Specify a project to be analyzed. The project file you specify should 704 be one that was created using the GUI interface. It will typically end 705 in the extension <filename>.fb</filename> or <filename>.fbp</filename>. 706 </para> 707 </listitem> 708 </varlistentry> 709 710 <!-- 711 <varlistentry> 712 <term><command></command></term> 713 <listitem> 714 <para> 715 716 </para> 717 </listitem> 718 </varlistentry> 719 --> 720 721 </variablelist> 722 723 </sect2> 724 725 <sect2> 726 <title>GUI Options</title> 727 728 <para> 729 These options are only accepted by the Graphical User Interface. 730 731 <variablelist> 732 <varlistentry> 733 <term><command>-look:</command><replaceable>plastic|gtk|native</replaceable></term> 734 <listitem> 735 <para> 736 Set Swing look and feel. 737 </para> 738 </listitem> 739 </varlistentry> 740 741 </variablelist> 742 </para> 743 </sect2> 744 745 <sect2> 746 <title>Text UI Options</title> 747 748 <para> 749 These options are only accepted by the Text User Interface. 750 </para> 751 752 <variablelist> 753 <varlistentry> 754 <term><command>-sortByClass</command></term> 755 <listitem> 756 <para> 757 Sort reported bug instances by class name. 758 </para> 759 </listitem> 760 </varlistentry> 761 762 <varlistentry> 763 <term><command >-include</command> <replaceable>filterFile.xml</replaceable></term> 764 <listitem> 765 <para> 766 Only report bug instances that match the filter specified by <replaceable>filterFile.xml</replaceable>. 767 See <xref linkend="filter" />. 768 </para> 769 </listitem> 770 </varlistentry> 771 772 <varlistentry> 773 <term><command >-exclude</command> <replaceable>filterFile.xml</replaceable></term> 774 <listitem> 775 <para> 776 Report all bug instances except those matching the filter specified by <replaceable>filterFile.xml</replaceable>. 777 See <xref linkend="filter" />. 778 </para> 779 </listitem> 780 </varlistentry> 781 782 <varlistentry> 783 <term><command>-onlyAnalyze</command> <replaceable>com.foobar.MyClass,com.foobar.mypkg.*</replaceable></term> 784 <listitem> 785 <para> 786 Restrict analysis to find bugs to given comma-separated list of 787 classes and packages. 788 Unlike filtering, this option avoids running analysis on 789 classes and packages that are not explicitly matched: 790 for large projects, this may greatly reduce the amount of time 791 needed to run the analysis. (However, some detectors may produce 792 inaccurate results if they aren't run on the entire application.) 793 Classes should be specified using their full classnames (including 794 package), and packages should be specified in the same way 795 they would in a Java <literal>import</literal> statement to 796 import all classes in the package (i.e., add <literal>.*</literal> 797 to the full name of the package). 798 Replace <literal>.*</literal> with <literal>.-</literal> to also 799 analyze all subpackages. 800 </para> 801 </listitem> 802 </varlistentry> 803 804 <varlistentry> 805 <term><command>-low</command></term> 806 <listitem> 807 <para> 808 Report all bugs. 809 </para> 810 </listitem> 811 </varlistentry> 812 813 <varlistentry> 814 <term><command>-medium</command></term> 815 <listitem> 816 <para> 817 Report medium and high priority bugs. This is the default setting. 818 </para> 819 </listitem> 820 </varlistentry> 821 822 <varlistentry> 823 <term><command>-high</command></term> 824 <listitem> 825 <para> 826 Report only high priority bugs. 827 </para> 828 </listitem> 829 </varlistentry> 830 831 <varlistentry> 832 <term><command>-relaxed</command></term> 833 <listitem> 834 <para> 835 Relaxed reporting mode. For many detectors, this option 836 suppresses the heuristics used to avoid reporting false positives. 837 </para> 838 </listitem> 839 </varlistentry> 840 841 <varlistentry> 842 <term><command>-xml</command></term> 843 <listitem> 844 <para> 845 Produce the bug reports as XML. The XML data produced may be 846 viewed in the GUI at a later time. You may also specify this 847 option as <command>-xml:withMessages</command>; when this variant 848 of the option is used, the XML output will contain human-readable 849 messages describing the warnings contained in the file. 850 XML files generated this way are easy to transform into reports. 851 </para> 852 </listitem> 853 </varlistentry> 854 855 <varlistentry> 856 <term><command>-html</command></term> 857 <listitem> 858 <para> 859 Generate HTML output. By default, &FindBugs; will use the <filename>default.xsl</filename> 860 <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink> 861 stylesheet to generate the HTML: you can find this file in <filename>findbugs.jar</filename>, 862 or in the &FindBugs; source or binary distributions. Variants of this option include 863 <command>-html:plain.xsl</command>, <command>-html:fancy.xsl</command> and <command>-html:fancy-hist.xsl</command>. 864 The <filename>plain.xsl</filename> stylesheet does not use Javascript or DOM, 865 and may work better with older web browsers, or for printing. The <filename>fancy.xsl</filename> 866 stylesheet uses DOM and Javascript for navigation and CSS for 867 visual presentation. The <command>fancy-hist.xsl</command> an evolution of <command>fancy.xsl</command> stylesheet. 868 It makes an extensive use of DOM and Javascript for dynamically filtering the lists of bugs. 869 </para> 870 871 <para> 872 If you want to specify your own 873 XSLT stylesheet to perform the transformation to HTML, specify the option as 874 <command>-html:<replaceable>myStylesheet.xsl</replaceable></command>, 875 where <replaceable>myStylesheet.xsl</replaceable> is the filename of the 876 stylesheet you want to use. 877 </para> 878 </listitem> 879 </varlistentry> 880 881 <varlistentry> 882 <term><command>-emacs</command></term> 883 <listitem> 884 <para> 885 Produce the bug reports in Emacs format. 886 </para> 887 </listitem> 888 </varlistentry> 889 890 <varlistentry> 891 <term><command>-xdocs</command></term> 892 <listitem> 893 <para> 894 Produce the bug reports in xdoc XML format for use with Apache Maven. 895 </para> 896 </listitem> 897 </varlistentry> 898 899 <varlistentry> 900 <term><command>-output</command> <replaceable>filename</replaceable></term> 901 <listitem> 902 <para> 903 Produce the output in the specified file. 904 </para> 905 </listitem> 906 </varlistentry> 907 908 <varlistentry> 909 <term><command>-outputFile</command> <replaceable>filename</replaceable></term> 910 <listitem> 911 <para> 912 This argument is deprecated. Use <command>-output</command> instead. 913 </para> 914 </listitem> 915 </varlistentry> 916 917 <varlistentry> 918 <term><command>-nested</command><replaceable>[:true|false]</replaceable></term> 919 <listitem> 920 <para> 921 This option enables or disables scanning of nested jar and zip files found in 922 the list of files and directories to be analyzed. 923 By default, scanning of nested jar/zip files is enabled. 924 To disable it, add <command>-nested:false</command> to the command line 925 arguments. 926 </para> 927 </listitem> 928 </varlistentry> 929 930 <varlistentry> 931 <term><command>-auxclasspath</command> <replaceable>classpath</replaceable></term> 932 <listitem> 933 <para> 934 Set the auxiliary classpath for analysis. This classpath should include all 935 jar files and directories containing classes that are part of the program 936 being analyzed but you do not want to have analyzed for bugs. 937 </para> 938 </listitem> 939 </varlistentry> 940 941 <varlistentry> 942 <term><command>-userPrefs</command> <replaceable>edu.umd.cs.findbugs.core.prefs</replaceable></term> 943 <listitem> 944 <para> 945 Set the path of the user preferences file to use, which might override some of the options abobe. 946 Specifying <literal>userPrefs</literal> as first argument would mean some later 947 options will override them, as last argument would mean they will override some previous options). 948 This rationale behind this option is to reuse FindBugs Eclipse project settings for command 949 line execution. 950 </para> 951 </listitem> 952 </varlistentry> 953 954 <!-- 955 <varlistentry> 956 <term><command></command> <replaceable></replaceable></term> 957 <listitem> 958 <para> 959 </para> 960 </listitem> 961 </varlistentry> 962 --> 963 964 </variablelist> 965 966 </sect2> 967 </sect1> 968 969 970 </chapter> 971 972 <chapter id="gui"> 973 <title>Using the &FindBugs; GUI</title> 974 975 <para> 976 This chapter describes how to use the &FindBugs; graphical user interface (GUI). 977 </para> 978 979 <sect1> 980 <title>Creating a Project</title> 981 <para> 982 After you have started &FindBugs; using the <command>findbugs</command> command, 983 choose the <menuchoice><guimenu>File</guimenu><guimenuitem>New Project</guimenuitem></menuchoice> 984 menu item. You will see a dialog which looks like this: 985 <mediaobject> 986 <imageobject> 987 <imagedata fileref="project-dialog.png" /> 988 </imageobject> 989 </mediaobject> 990 </para> 991 992 <para> 993 Use the "Add" button next to "Classpath to analyze" to select a Java archive 994 file (zip, jar, ear, or war file) or directory containing java classes to analyze for bugs. You may add multiple 995 archives/directories. 996 </para> 997 998 <para> 999 You can also add the source directories which contain 1000 the source code for the Java archives you are analyzing. This will enable 1001 &FindBugs; to highlight the source code which contains a possible error. 1002 The source directories you add should be the roots of the Java 1003 package hierarchy. For example, if your application is contained in the 1004 <varname>org.foobar.myapp</varname> package, you should add the 1005 parent directory of the <filename class="directory">org</filename> directory 1006 to the source directory list for the project. 1007 </para> 1008 1009 <para> 1010 Another optional step is to add additional Jar files or directories as 1011 "Auxiliary classpath locations" entries. You should do this if the archives and directories you are analyzing 1012 have references to other classes which are not included in the analyzed 1013 archives/directories and are not in the standard runtime classpath. Some of the bug 1014 pattern detectors in &FindBugs; make use of class hierarchy information, 1015 so you will get more accurate results if the entire class hierarchy is 1016 available which &FindBugs; performs its analysis. 1017 </para> 1018 1019 </sect1> 1020 1021 <sect1> 1022 <title>Running the Analysis</title> 1023 <para> 1024 Once you have added all of the archives, directories, and source directories, 1025 click the "Analyze" button to analyze the classes contained in the 1026 Jar files. Note that for a very large program on an older computer, 1027 this may take quite a while (tens of minutes). A recent computer with 1028 ample memory will typically be able to analyze a large program in only a 1029 few minutes. 1030 </para> 1031 </sect1> 1032 1033 <sect1> 1034 <title>Browsing Results</title> 1035 1036 <para> 1037 When the analysis completes, you will see a screen like the following: 1038 <mediaobject> 1039 <imageobject> 1040 <imagedata fileref="example-details.png" /> 1041 </imageobject> 1042 </mediaobject> 1043 </para> 1044 1045 <para> 1046 The upper left-hand pane of the window shows the bug tree; this is a hierarchical 1047 representation of all of the potential bugs detected in the analyzed 1048 Jar files. 1049 </para> 1050 1051 <para> 1052 When you select a particular bug instance in the top pane, you will 1053 see a description of the bug in the "Details" tab of the bottom pane. 1054 In addition, the source code pane on the upper-right will show the 1055 program source code where the potential bug occurs, if source is available. 1056 In the above example, the bug is a stream object that is not closed. The 1057 source code window highlights the line where the stream object is created. 1058 </para> 1059 1060 <para> 1061 You may add a textual annotations to bug instances. To do so, type them 1062 into the text box just below the hierarchical view. You can type any 1063 information which you would like to record. When you load and save bug 1064 results files, the annotations are preserved. 1065 </para> 1066 1067 </sect1> 1068 1069 <sect1> 1070 <title>Saving and Opening</title> 1071 1072 <para> 1073 You may use the <menuchoice><guimenu>File</guimenu><guimenuitem>Save as...</guimenuitem></menuchoice> 1074 menu option to save your work. To save your work, including the jar 1075 file lists you specified and all bug results, choose 1076 "FindBugs analysis results (.xml)" from the drop-down list in the 1077 "Save as..." dialog. There are also options for saving just the jar 1078 file lists ("FindBugs project file (.fbp)") or just the results 1079 ("FindBugs analysis file (.fba)"). 1080 A saved file may be loaded with the 1081 <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> 1082 menu option. 1083 </para> 1084 1085 </sect1> 1086 1087 <!-- 1088 <sect1 id="textui"> 1089 <title>Using the &FindBugs;™ Command Line Interface</title> 1090 1091 <para> 1092 The &FindBugs; Command Line Interface (or Text UI) can be used to 1093 analyze an application for bugs non-interactively. Each bug instance will be 1094 reported on a single line. All output is written to the standard output file descriptor. 1095 <xref linkend="filter" /> explains how bug reports may be filtered in order 1096 to get only the output you're interested in. 1097 </para> 1098 1099 <para> 1100 See <xref linkend="commandLineOptions" /> for a description of how to invoke the 1101 Command Line Interface. 1102 </para> 1103 </sect1> 1104 --> 1105 1106 </chapter> 1107 1108 <!-- 1109 ************************************************************************** 1110 Using the FindBugs Ant task 1111 ************************************************************************** 1112 --> 1113 1114 <chapter id="anttask"> 1115 <title>Using the &FindBugs;™ &Ant; task</title> 1116 1117 <para> 1118 This chapter describes how to integrate &FindBugs; into a build script 1119 for <ulink url="http://ant.apache.org/">&Ant;</ulink>, which is a popular Java build 1120 and deployment tool. Using the &FindBugs; &Ant; task, your build script can 1121 automatically run &FindBugs; on your Java code. 1122 </para> 1123 1124 <para> 1125 The &Ant; task was generously contributed by Mike Fagan. 1126 </para> 1127 1128 <sect1> 1129 <title>Installing the &Ant; task</title> 1130 1131 <para> 1132 To install the &Ant; task, simply copy <filename>&FBHome;/lib/findbugs-ant.jar</filename> 1133 into the <filename>lib</filename> subdirectory of your &Ant; installation. 1134 1135 <note> 1136 <para>It is strongly recommended that you use the &Ant; task with the version 1137 of &FindBugs; it was included with. We do not guarantee that the &Ant; task Jar file 1138 will work with any version of &FindBugs; other than the one it was included with.</para> 1139 </note> 1140 </para> 1141 1142 </sect1> 1143 1144 <sect1> 1145 <title>Modifying build.xml</title> 1146 1147 <para> 1148 To incorporate &FindBugs; into <filename>build.xml</filename> (the build script 1149 for &Ant;), you first need to add a task definition. This should appear as follows: 1150 1151 <screen> 1152 <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/> 1153 </screen> 1154 1155 The task definition specifies that when a <literal>findbugs</literal> element is 1156 seen in <filename>build.xml</filename>, it should use the indicated class to execute the task. 1157 </para> 1158 1159 <para> 1160 After you have added the task definition, you can define a target 1161 which uses the <literal>findbugs</literal> task. Here is an example 1162 which could be added to the <filename>build.xml</filename> for the 1163 Apache <ulink url="http://jakarta.apache.org/bcel/">BCEL</ulink> library. 1164 1165 <screen> 1166 <property name="findbugs.home" value="/export/home/daveho/work/findbugs" /> 1167 1168 <target name="findbugs" depends="jar"> 1169 <findbugs home="${findbugs.home}" 1170 output="xml" 1171 outputFile="bcel-fb.xml" > 1172 <auxClasspath path="${basedir}/lib/Regex.jar" /> 1173 <sourcePath path="${basedir}/src/java" /> 1174 <class location="${basedir}/bin/bcel.jar" /> 1175 </findbugs> 1176 </target> 1177 </screen> 1178 1179 The <literal>findbugs</literal> element must have the <literal>home</literal> 1180 attribute set to the directory in which &FindBugs; is installed; in other words, 1181 &FBHome;. See <xref linkend="installing" />. 1182 </para> 1183 1184 <para> 1185 This target will execute &FindBugs; on <filename>bcel.jar</filename>, which is the 1186 Jar file produced by BCEL's build script. (By making it depend on the "jar" 1187 target, we ensure that the library is fully compiled before running &FindBugs; on it.) 1188 The output of &FindBugs; will be saved in XML format to a file called 1189 <filename>bcel-fb.xml</filename>. 1190 An auxiliary Jar file, <filename>Regex.jar</filename>, is added to the aux classpath, 1191 because it is referenced by the main BCEL library. A source path is specified 1192 so that the saved bug data will have accurate references to the BCEL source code. 1193 </para> 1194 </sect1> 1195 1196 <sect1> 1197 <title>Executing the task</title> 1198 1199 <para> 1200 Here is an example of invoking &Ant; from the command line, using the <literal>findbugs</literal> 1201 target defined above. 1202 1203 <screen> 1204 <prompt>[daveho@noir]$</prompt> <command>ant findbugs</command> 1205 Buildfile: build.xml 1206 1207 init: 1208 1209 compile: 1210 1211 examples: 1212 1213 jar: 1214 1215 findbugs: 1216 [findbugs] Running FindBugs... 1217 [findbugs] Bugs were found 1218 [findbugs] Output saved to bcel-fb.xml 1219 1220 BUILD SUCCESSFUL 1221 Total time: 35 seconds 1222 </screen> 1223 1224 In this case, because we saved the bug results in an XML file, we can 1225 use the &FindBugs; GUI to view the results; see <xref linkend="running"/>. 1226 </para> 1227 1228 </sect1> 1229 1230 <sect1> 1231 <title>Parameters</title> 1232 1233 <para>This section describes the parameters that may be specified when 1234 using the &FindBugs; task. 1235 1236 <variablelist> 1237 1238 <varlistentry> 1239 <term><literal>class</literal></term> 1240 <listitem> 1241 <para> 1242 A optional nested element specifying which classes to analyze. The <literal>class</literal> 1243 element must specify a <literal>location</literal> attribute which names the 1244 archive file (jar, zip, etc.), directory, or class file to be analyzed. Multiple <literal>class</literal> 1245 elements may be specified as children of a single <literal>findbugs</literal> element. 1246 </para> 1247 <para>In addition to or instead of specifying a <literal>class</literal> element, 1248 the &FindBugs; task can contain one or more <literal>fileset</literal> element(s) that 1249 specify files to be analyzed. 1250 For example, you might use a fileset to specify that all of the jar files in a directory 1251 should be analyzed. 1252 </para> 1253 </listitem> 1254 </varlistentry> 1255 1256 <varlistentry> 1257 <term><literal>auxClasspath</literal></term> 1258 <listitem> 1259 <para> 1260 An optional nested element which specifies a classpath (Jar files or directories) 1261 containing classes used by the analyzed library or application, but which 1262 you don't want to analyze. It is specified the same way as 1263 &Ant;'s <literal>classpath</literal> element for the Java task. 1264 </para> 1265 </listitem> 1266 </varlistentry> 1267 1268 <varlistentry> 1269 <term><literal>sourcePath</literal></term> 1270 <listitem> 1271 <para> 1272 An optional nested element which specifies a source directory path 1273 containing source files used to compile the Java code being analyzed. 1274 By specifying a source path, any generated XML bug output will have 1275 complete source information, which allows later viewing in the 1276 GUI. 1277 </para> 1278 </listitem> 1279 </varlistentry> 1280 1281 <varlistentry> 1282 <term><literal>home</literal></term> 1283 <listitem> 1284 <para> 1285 A required attribute. 1286 It must be set to the name of the directory where &FindBugs; is installed. 1287 </para> 1288 </listitem> 1289 </varlistentry> 1290 1291 <varlistentry> 1292 <term><literal>quietErrors</literal></term> 1293 <listitem> 1294 <para> 1295 An optional boolean attribute. 1296 If true, reports of serious analysis errors and missing classes will 1297 be suppressed in the &FindBugs; output. Default is false. 1298 </para> 1299 </listitem> 1300 </varlistentry> 1301 1302 <varlistentry> 1303 <term><literal>reportLevel</literal></term> 1304 <listitem> 1305 <para> 1306 An optional attribute. It specifies 1307 the confidence/priority threshold for reporting issues. If set to "low", confidence is not used to filter bugs. 1308 If set to "medium" (the default), low confidence issues are supressed. 1309 If set to "high", only high confidence bugs are reported. 1310 </para> 1311 </listitem> 1312 </varlistentry> 1313 1314 <varlistentry> 1315 <term><literal>output</literal></term> 1316 <listitem> 1317 <para> 1318 Optional attribute. 1319 It specifies the output format. If set to "xml" (the default), output 1320 is in XML format. 1321 If set to "xml:withMessages", output is in XML format augmented with 1322 human-readable messages. (You should use this format if you plan 1323 to generate a report using an XSL stylesheet.) 1324 If set to "html", output is in HTML formatted (default stylesheet is default.xsl). 1325 If set to "text", output is in ad-hoc text format. 1326 If set to "emacs", output is in <ulink url="http://www.gnu.org/software/emacs/">Emacs</ulink> error message format. 1327 If set to "xdocs", output is xdoc XML for use with Apache Maven. 1328 </para> 1329 </listitem> 1330 </varlistentry> 1331 <varlistentry> 1332 <term><literal>stylesheet</literal></term> 1333 <listitem> 1334 <para> 1335 Optional attribute. 1336 It specifies the stylesheet to use to generate html output when the output is set to html. 1337 Stylesheets included in the FindBugs distribution include default.xsl, fancy.xsl, fancy-hist.xsl, plain.xsl, and summary.xsl. 1338 The default value, if no stylesheet attribute is provided, is default.xsl. 1339 1340 </para> 1341 </listitem> 1342 </varlistentry> 1343 1344 <varlistentry> 1345 <term><literal>sort</literal></term> 1346 <listitem> 1347 <para> 1348 Optional attribute. If the <literal>output</literal> attribute 1349 is set to "text", then the <literal>sort</literal> attribute specifies 1350 whether or not reported bugs are sorted by class. Default is true. 1351 </para> 1352 </listitem> 1353 </varlistentry> 1354 1355 <varlistentry> 1356 <term><literal>outputFile</literal></term> 1357 <listitem> 1358 <para> 1359 Optional attribute. If specified, names the output file in which the 1360 &FindBugs; output will be saved. By default, the output is displayed 1361 directly by &Ant;. 1362 </para> 1363 </listitem> 1364 </varlistentry> 1365 1366 <varlistentry> 1367 <term><literal>debug</literal></term> 1368 <listitem> 1369 <para> 1370 Optional boolean attribute. If set to true, &FindBugs; prints diagnostic 1371 information about which classes are being analyzed, and which bug pattern 1372 detectors are being run. Default is false. 1373 </para> 1374 </listitem> 1375 </varlistentry> 1376 1377 <varlistentry> 1378 <term><literal>effort</literal></term> 1379 <listitem> 1380 <para> 1381 Set the analysis effort level. The value specified should be 1382 one of <literal>min</literal>, <literal>default</literal>, 1383 or <literal>max</literal>. See <xref linkend="commandLineOptions"/> 1384 for more information about setting the analysis level. 1385 </para> 1386 </listitem> 1387 </varlistentry> 1388 1389 <varlistentry> 1390 <term><literal>conserveSpace</literal></term> 1391 <listitem> 1392 <para>Synonym for effort="min".</para> 1393 </listitem> 1394 </varlistentry> 1395 1396 <varlistentry> 1397 <term><literal>workHard</literal></term> 1398 <listitem> 1399 <para>Synonym for effort="max".</para> 1400 </listitem> 1401 </varlistentry> 1402 1403 <varlistentry> 1404 <term><literal>visitors</literal></term> 1405 <listitem> 1406 <para> 1407 Optional attribute. It specifies a comma-separated list of bug detectors 1408 which should be run. The bug detectors are specified by their class names, 1409 without any package qualification. By default, all detectors which are 1410 not disabled by default are run. 1411 </para> 1412 </listitem> 1413 </varlistentry> 1414 1415 <varlistentry> 1416 <term><literal>omitVisitors</literal></term> 1417 <listitem> 1418 <para> 1419 Optional attribute. It is like the <literal>visitors</literal> attribute, 1420 except it specifies detectors which will <emphasis>not</emphasis> be run. 1421 </para> 1422 </listitem> 1423 </varlistentry> 1424 1425 <varlistentry> 1426 <term><literal>excludeFilter</literal></term> 1427 <listitem> 1428 <para> 1429 Optional attribute. It specifies the filename of a filter specifying bugs 1430 to exclude from being reported. See <xref linkend="filter" />. 1431 </para> 1432 </listitem> 1433 </varlistentry> 1434 1435 <varlistentry> 1436 <term><literal>includeFilter</literal></term> 1437 <listitem> 1438 <para> 1439 Optional attribute. It specifies the filename of a filter specifying 1440 which bugs are reported. See <xref linkend="filter" />. 1441 </para> 1442 </listitem> 1443 </varlistentry> 1444 1445 <varlistentry> 1446 <term><literal>projectFile</literal></term> 1447 <listitem> 1448 <para> 1449 Optional attribute. It specifies the name of a project file. 1450 Project files are created by the &FindBugs; GUI, and specify classes, 1451 aux classpath entries, and source directories. By naming a project, 1452 you don't need to specify any <literal>class</literal> elements, 1453 nor do you need to specify <literal>auxClasspath</literal> or 1454 <literal>sourcePath</literal> attributes. 1455 See <xref linkend="running"/> for how to create a project. 1456 </para> 1457 </listitem> 1458 </varlistentry> 1459 1460 <varlistentry> 1461 <term><literal>jvmargs</literal></term> 1462 <listitem> 1463 <para> 1464 Optional attribute. It specifies any arguments that should be passed 1465 to the Java virtual machine used to run &FindBugs;. You may need to 1466 use this attribute to specify flags to increase the amount of memory 1467 the JVM may use if you are analyzing a very large program. 1468 </para> 1469 </listitem> 1470 </varlistentry> 1471 1472 <varlistentry> 1473 <term><literal>systemProperty</literal></term> 1474 <listitem> 1475 <para> 1476 Optional nested element. If specified, defines a system property. 1477 The <literal>name</literal> attribute specifies the name of the 1478 system property, and the <literal>value</literal> attribute specifies 1479 the value of the system property. 1480 </para> 1481 </listitem> 1482 </varlistentry> 1483 1484 <varlistentry> 1485 <term><literal>timeout</literal></term> 1486 <listitem> 1487 <para> 1488 Optional attribute. It specifies the amount of time, in milliseconds, 1489 that the Java process executing &FindBugs; may run before it is 1490 assumed to be hung and is terminated. The default is 600,000 1491 milliseconds, which is ten minutes. Note that for very large 1492 programs, &FindBugs; may require more than ten minutes to complete its 1493 analysis. 1494 </para> 1495 </listitem> 1496 </varlistentry> 1497 1498 <varlistentry> 1499 <term><literal>failOnError</literal></term> 1500 <listitem> 1501 <para> 1502 Optional boolean attribute. Whether to abort the build process if there is an 1503 error running &FindBugs;. Defaults to "false" 1504 </para> 1505 </listitem> 1506 </varlistentry> 1507 1508 <varlistentry> 1509 <term><literal>errorProperty</literal></term> 1510 <listitem> 1511 <para> 1512 Optional attribute which specifies the name of a property that 1513 will be set to "true" if an error occurs while running &FindBugs;. 1514 </para> 1515 </listitem> 1516 </varlistentry> 1517 1518 <varlistentry> 1519 <term><literal>warningsProperty</literal></term> 1520 <listitem> 1521 <para> 1522 Optional attribute which specifies the name of a property 1523 that will be set to "true" if any warnings are reported by 1524 &FindBugs; on the analyzed program. 1525 </para> 1526 </listitem> 1527 </varlistentry> 1528 1529 <varlistentry> 1530 <term><literal>userPreferencesFile</literal></term> 1531 <listitem> 1532 <para> 1533 Optional attribute. Set the path of the user preferences file to use, which might override some of the options abobe. 1534 Specifying <literal>userPreferencesFile</literal> as first argument would mean some later 1535 options will override them, as last argument would mean they will override some previous options). 1536 This rationale behind this option is to reuse FindBugs Eclipse project settings for command 1537 line execution. 1538 </para> 1539 </listitem> 1540 </varlistentry> 1541 1542 </variablelist> 1543 1544 1545 </para> 1546 1547 <!-- 1548 1549 --> 1550 1551 </sect1> 1552 1553 </chapter> 1554 1555 <!-- 1556 ************************************************************************** 1557 Using the FindBugs Eclipse plugin 1558 ************************************************************************** 1559 --> 1560 1561 <chapter id="eclipse"> 1562 <title>Using the &FindBugs;™ Eclipse plugin</title> 1563 1564 <para> 1565 The FindBugs Eclipse plugin allows &FindBugs; to be used within 1566 the <ulink url="http://www.eclipse.org/">Eclipse</ulink> IDE. 1567 The FindBugs Eclipse plugin was generously contributed by Peter Friese. 1568 Phil Crosby and Andrei Loskutov contributed major improvements 1569 to the plugin. 1570 </para> 1571 1572 <sect1> 1573 <title>Requirements</title> 1574 1575 <para> 1576 To use the &FindBugs; Plugin for Eclipse, you need Eclipse 3.3 or later, 1577 and JRE/JDK 1.5 or later. 1578 </para> 1579 1580 </sect1> 1581 1582 <sect1> 1583 <title>Installation</title> 1584 1585 <para> 1586 We provide update sites that allow you to automatically install FindBugs into Eclipse and also query and install updates. 1587 There are three different update sites</para> 1588 1589 <variablelist><title>FindBugs Eclipse update sites</title> 1590 <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse/">http://findbugs.cs.umd.edu/eclipse/</ulink></term> 1591 1592 <listitem> 1593 <para> 1594 Only provides official releases of FindBugs. 1595 </para> 1596 </listitem> 1597 </varlistentry> 1598 1599 <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-candidate/">http://findbugs.cs.umd.edu/eclipse-candidate/</ulink></term> 1600 1601 <listitem> 1602 <para> 1603 Provides official releases and release candidates of FindBugs. 1604 </para> 1605 </listitem> 1606 </varlistentry> 1607 1608 <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-daily/">http://findbugs.cs.umd.edu/eclipse-daily/</ulink></term> 1609 1610 <listitem> 1611 <para> 1612 Provides the daily build of FindBugs. No testing other than that it compiles. 1613 </para> 1614 </listitem> 1615 </varlistentry> 1616 </variablelist> 1617 1618 <para>You can also manually 1619 download the plugin from the following link: 1620 <ulink url="http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download" 1621 >http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122.zip?download</ulink>. 1622 Extract it in Eclipse's "plugins" subdirectory. 1623 (So <eclipse_install_dir>/plugins/edu.umd.cs.findbugs.plugin.eclipse_2.0.3.20131122/findbugs.png 1624 should be the path to the &FindBugs; logo.) 1625 1626 </para> 1627 1628 <para> 1629 Once the plugin is extracted, start Eclipse and choose 1630 <menuchoice> 1631 <guimenu>Help</guimenu> 1632 <guimenuitem>About Eclipse Platform</guimenuitem> 1633 <guimenuitem>Plug-in Details</guimenuitem> 1634 </menuchoice>. 1635 You should find a plugin called "FindBugs Plug-in" provided by "FindBugs Project". 1636 </para> 1637 </sect1> 1638 1639 <sect1> 1640 <title>Using the Plugin</title> 1641 1642 <para> 1643 To get started, right click on a Java project in Package Explorer, 1644 and select the option labeled "Find Bugs". 1645 &FindBugs; will run, and problem markers (displayed in source 1646 windows, and also in the Eclipse Problems view) will point to 1647 locations in your code which have been identified as potential instances 1648 of bug patterns. 1649 </para> 1650 <para> 1651 You can also run &FindBugs; on existing java archives (jar, ear, zip, war etc). Simply 1652 create an empty Java project and attach archives to the project classpath. Having that, you 1653 can now right click the archive node in Package Explorer and select the option labeled 1654 "Find Bugs". If you additionally configure the source code locations for the binaries, 1655 &FindBugs; will also link the generated warnings to the right source files. 1656 </para> 1657 <para> 1658 You may customize how &FindBugs; runs by opening the Properties 1659 dialog for a Java project, and choosing the "Findbugs" property page. 1660 Options you may choose include: 1661 </para> 1662 1663 <itemizedlist> 1664 <listitem> 1665 <para> 1666 Enable or disable the "Run FindBugs Automatically" checkbox. 1667 When enabled, FindBugs will run every time you modify a Java class 1668 within the project. 1669 </para> 1670 </listitem> 1671 1672 <listitem> 1673 <para> 1674 Choose minimum warning priority and enabled bug categories. 1675 These options will choose which warnings are shown. 1676 For example, if you select the "Medium" warning priority, 1677 only Medium and High priority warnings will be shown. 1678 Similarly, if you uncheck the "Style" checkbox, no warnings 1679 in the Style category will be displayed. 1680 </para> 1681 </listitem> 1682 1683 <listitem> 1684 <para> 1685 Select detectors. The table allows you to select which detectors 1686 you want to enable for your project. 1687 </para> 1688 </listitem> 1689 </itemizedlist> 1690 1691 </sect1> 1692 1693 <sect1> 1694 <title>Extending the Eclipse Plugin (since 2.0.0)</title> 1695 <para> 1696 Eclipse plugin supports contribution of custom &FindBugs; detectors (see also 1697 <ulink url="http://code.google.com/p/findbugs/source/browse/trunk/findbugs/src/doc/AddingDetectors.txt">AddingDetectors.txt</ulink> 1698 for more information). There are two ways to contribute custom plugins to the Eclipse: 1699 </para> 1700 <itemizedlist> 1701 <listitem> 1702 <para> 1703 Existing standard &FindBugs; detector packages can be configured via 1704 <menuchoice> 1705 <guimenu>Window</guimenu> 1706 <guimenuitem>Preferences</guimenuitem> 1707 <guimenuitem>Java</guimenuitem> 1708 <guimenuitem>&FindBugs;</guimenuitem> 1709 <guimenuitem>Misc. Settings</guimenuitem> 1710 <guimenuitem>Custom Detectors</guimenuitem> 1711 </menuchoice>. 1712 Simply specify there locations of any additional plugin libraries. 1713 </para> 1714 1715 <para> 1716 The benefit of this solution is that already existing detector packages can be 1717 used "as is", and that you can quickly verify the quality of third party detectors. 1718 The drawback is that you have to apply this settings in each 1719 new Eclipse workspace, and this settings can't be shared between team members. 1720 </para> 1721 </listitem> 1722 1723 <listitem> 1724 <para> 1725 It is possible to contribute custom detectors via standard Eclipse extensions mechanism. 1726 </para> 1727 1728 <para> 1729 Please check the documentation of the 1730 <ulink url="http://code.google.com/p/findbugs/source/browse/trunk/eclipsePlugin/schema/detectorPlugins.exsd"> 1731 findBugsEclipsePlugin/schema/detectorPlugins.exsd</ulink> 1732 extension point how to update the plugin.xml. Existing &FindBugs; detector plugins can 1733 be easily "extended" to be full featured &FindBugs; AND Eclipse detector plugins. 1734 Usually you only need to add META-INF/MANIFEST.MF and plugin.xml to the jar and 1735 update your build scripts to not to override the MANIFEST.MF during the build. 1736 </para> 1737 1738 <para> 1739 The benefit of this solution is that for given (shared) Eclipse installation 1740 each team member has exactly same detectors set, and there is no need to configure 1741 anything anymore. The (really small) precondition 1742 is that you have to convert your existing detectors package to the valid 1743 Eclipse plugin. You can do this even for third-party detector packages. 1744 Another major differentiator is the ability to extend the default FindBugs 1745 classpath at runtime with required third party libraries (see 1746 <ulink url="http://code.google.com/p/findbugs/source/browse/trunk/findbugs/src/doc/AddingDetectors.txt">AddingDetectors.txt</ulink> 1747 for more information). 1748 </para> 1749 </listitem> 1750 1751 </itemizedlist> 1752 1753 </sect1> 1754 1755 <sect1> 1756 <title>Troubleshooting</title> 1757 1758 <para> 1759 This section lists common problems with the plugin and (if known) how to resolve them. 1760 </para> 1761 1762 <itemizedlist> 1763 <listitem> 1764 <para> 1765 If you see OutOfMemory error dialogs after starting &FindBugs; analysis in Eclipse, 1766 please increase JVM available memory: change eclipse.ini and add the lines below 1767 to the end of the file: 1768 <programlisting> 1769 -vmargs 1770 -Xmx1000m 1771 </programlisting> 1772 Important: the configuration arguments starting with the line "-vmargs" must 1773 be last lines in the eclipse.ini file, and only one argument per line is allowed! 1774 </para> 1775 </listitem> 1776 <listitem> 1777 <para> 1778 If you do not see any &FindBugs; problem markers (in your source 1779 windows or in the Problems View), you may need to change your 1780 Problems View filter settings. See 1781 <ulink url="http://findbugs.sourceforge.net/FAQ.html#q7">http://findbugs.sourceforge.net/FAQ.html#q7</ulink> for more information. 1782 </para> 1783 </listitem> 1784 1785 </itemizedlist> 1786 1787 </sect1> 1788 1789 1790 </chapter> 1791 1792 1793 <!-- 1794 ************************************************************************** 1795 Filter files 1796 ************************************************************************** 1797 --> 1798 1799 <chapter id="filter"> 1800 <title>Filter Files</title> 1801 1802 <para> 1803 Filter files may be used to include or exclude bug reports for particular classes 1804 and methods. This chapter explains how to use filter files. 1805 1806 <note> 1807 <title>Planned Features</title> 1808 <para> 1809 Filters are currently only supported by the Command Line interface. 1810 Eventually, filter support will be added to the GUI. 1811 </para> 1812 </note> 1813 </para> 1814 1815 1816 <sect1> 1817 <title>Introduction to Filter Files</title> 1818 1819 <para> 1820 Conceptually, a filter matches bug instances against a set of criteria. 1821 By defining a filter, you can select bug instances for special treatment; 1822 for example, to exclude or include them in a report. 1823 </para> 1824 1825 <para> 1826 A filter file is an <ulink url="http://www.w3.org/XML/">XML</ulink> document with a top-level <literal>FindBugsFilter</literal> element 1827 which has some number of <literal>Match</literal> elements as children. Each <literal>Match</literal> 1828 element represents a predicate which is applied to generated bug instances. 1829 Usually, a filter will be used to exclude bug instances. For example: 1830 1831 <screen> 1832 <prompt>$ </prompt><command>findbugs -textui -exclude <replaceable>myExcludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command> 1833 </screen> 1834 1835 However, a filter could also be used to select bug instances to specifically 1836 report: 1837 1838 <screen> 1839 <prompt>$ </prompt><command>findbugs -textui -include <replaceable>myIncludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command> 1840 </screen> 1841 </para> 1842 1843 <para> 1844 <literal>Match</literal> elements contain children, which are conjuncts of the predicate. 1845 In other words, each of the children must be true for the predicate to be true. 1846 </para> 1847 1848 </sect1> 1849 1850 <sect1> 1851 <title>Types of Match clauses</title> 1852 1853 <variablelist> 1854 <varlistentry> 1855 <term><literal><Bug></literal></term> 1856 <listitem><para> 1857 This element specifies a particular bug pattern or patterns to match. 1858 The <literal>pattern</literal> attribute is a comma-separated list of 1859 bug pattern types. You can find the bug pattern types for particular 1860 warnings by looking at the output produced by the <command>-xml</command> 1861 output option (the <literal>type</literal> attribute of <literal>BugInstance</literal> 1862 elements), or from the <ulink url="../bugDescriptions.html">bug 1863 descriptions document</ulink>. 1864 </para><para> 1865 For more coarse-grained matching, use <literal>code</literal> attribute. It takes 1866 a comma-separated list of bug abbreviations. For most-coarse grained matching use 1867 <literal>category</literal> attriute, that takes a comma separated list of bug category names: 1868 <literal>CORRECTNESS</literal>, <literal>MT_CORRECTNESS</literal>, 1869 <literal>BAD_PRACTICICE</literal>, <literal>PERFORMANCE</literal>, <literal>STYLE</literal>. 1870 </para><para> 1871 If more than one of the attributes mentioned above are specified on the same 1872 <literal><Bug></literal> element, all bug patterns that match either one of specified 1873 pattern names, or abreviations, or categories will be matched. 1874 </para><para> 1875 As a backwards compatibility measure, <literal><BugPattern></literal> and 1876 <literal><BugCode></literal> elements may be used instead of 1877 <literal><Bug></literal> element. Each of these uses a 1878 <literal>name</literal> attribute for specifying accepted values list. Support for these 1879 elements may be removed in a future release. 1880 </para></listitem> 1881 </varlistentry> 1882 1883 <varlistentry> 1884 <term><literal><Confidence></literal></term> 1885 <listitem> 1886 <para> 1887 This element matches warnings with a particular bug confidence. 1888 The <literal>value</literal> attribute should be an integer value: 1889 1 to match high-confidence warnings, 2 to match normal-confidence warnings, 1890 or 3 to match low-confidence warnings. <Confidence> replaced 1891 <Priority> in 2.0.0 release. 1892 </para> 1893 </listitem> 1894 </varlistentry> 1895 1896 <varlistentry> 1897 <term><literal><Priority></literal></term> 1898 <listitem> 1899 <para> 1900 Same as <literal><Confidence></literal>, exists for backward compatibility. 1901 </para> 1902 </listitem> 1903 </varlistentry> 1904 1905 <varlistentry> 1906 <term><literal><Rank></literal></term> 1907 <listitem> 1908 <para> 1909 This element matches warnings with a particular bug rank. 1910 The <literal>value</literal> attribute should be an integer value 1911 between 1 and 20, where 1 to 4 are scariest, 5 to 9 scary, 10 to 14 troubling, 1912 and 15 to 20 of concern bugs. 1913 </para> 1914 </listitem> 1915 </varlistentry> 1916 1917 <varlistentry> 1918 <term><literal><Package></literal></term> 1919 <listitem> 1920 <para> 1921 This element matches warnings associated with classes within the package specified 1922 using <literal>name</literal> attribute. Nested packages are not included (along the 1923 lines of Java import statement). However matching multiple packages can be achieved 1924 easily using regex name match. 1925 </para> 1926 </listitem> 1927 </varlistentry> 1928 1929 <varlistentry> 1930 <term><literal><Class></literal></term> 1931 <listitem> 1932 <para> 1933 This element matches warnings associated with a particular class. The 1934 <literal>name</literal> attribute is used to specify the exact or regex match pattern 1935 for the class name. 1936 </para> 1937 1938 <para> 1939 As a backward compatibility measure, instead of element of this type, you can use 1940 <literal>class</literal> attribute on a <literal>Match</literal> element to specify 1941 exact an class name or <literal>classregex</literal> attribute to specify a regular 1942 expression to match the class name against. 1943 </para> 1944 1945 <para> 1946 If the <literal>Match</literal> element contains neither a <literal>Class</literal> element, 1947 nor a <literal>class</literal> / <literal>classregex</literal> attribute, the predicate will apply 1948 to all classes. Such predicate is likely to match more bug instances than you want, unless it is 1949 refined further down with apropriate method or field predicates. 1950 </para> 1951 </listitem> 1952 </varlistentry> 1953 1954 <varlistentry> 1955 <term><literal><Method></literal></term> 1956 1957 <listitem><para>This element specifies a method. The <literal>name</literal> is used to specify 1958 the exact or regex match pattern for the method name. 1959 The <literal>params</literal> attribute is a comma-separated list 1960 of the types of the method's parameters. The <literal>returns</literal> attribute is 1961 the method's return type. In <literal>params</literal> and <literal>returns</literal>, class names 1962 must be fully qualified. (E.g., "java.lang.String" instead of just 1963 "String".) If one of the latter attributes is specified the other is required for creating a method signature. 1964 Note that you can provide either <literal>name</literal> attribute or <literal>params</literal> 1965 and <literal>returns</literal> attributes or all three of them. This way you can provide various kinds of 1966 name and signature based matches. 1967 </para></listitem> 1968 </varlistentry> 1969 1970 <varlistentry> 1971 <term><literal><Field></literal></term> 1972 1973 <listitem><para>This element specifies a field. The <literal>name</literal> attribute is is used to specify 1974 the exact or regex match pattern for the field name. You can also filter fields according to their signature - 1975 use <literal>type</literal> attribute to specify fully qualified type of the field. You can specify eiter or both 1976 of these attributes in order to perform name / signature based matches. 1977 </para></listitem> 1978 </varlistentry> 1979 1980 <varlistentry> 1981 <term><literal><Local></literal></term> 1982 1983 <listitem><para>This element specifies a local variable. The <literal>name</literal> attribute is is used to specify 1984 the exact or regex match pattern for the local variable name. Local variables are variables defined within a method. 1985 </para></listitem> 1986 </varlistentry> 1987 1988 <varlistentry> 1989 <term><literal><Or></literal></term> 1990 <listitem><para> 1991 This element combines <literal>Match</literal> clauses as disjuncts. I.e., you can put two 1992 <literal>Method</literal> elements in an <literal>Or</literal> clause in order to match either method. 1993 </para></listitem> 1994 </varlistentry> 1995 <varlistentry> 1996 <term><literal><And></literal></term> 1997 <listitem><para> 1998 This element combines <literal>Match</literal> clauses which both must evaluate to true. I.e., you can put 1999 <literal>Bug</literal> and <literal>Priority</literal> elements in an <literal>And</literal> clause in order 2000 to match specific bugs with given priority only. 2001 </para></listitem> 2002 </varlistentry> 2003 <varlistentry> 2004 <term><literal><Not></literal></term> 2005 <listitem><para> 2006 This element inverts the included child <literal>Match</literal>. I.e., you can put a 2007 <literal>Bug</literal> element in a <literal>Not</literal> clause in order to match any bug 2008 excluding the given one. 2009 </para></listitem> 2010 </varlistentry> 2011 </variablelist> 2012 2013 </sect1> 2014 2015 <sect1> 2016 <title>Java element name matching</title> 2017 2018 <para> 2019 If the <literal>name</literal> attribute of <literal>Class</literal>, <literal>Method</literal> or 2020 <literal>Field</literal> starts with the ~ character the rest of attribute content is interpreted as 2021 a Java regular expression that is matched against the names of the Java element in question. 2022 </para> 2023 2024 <para> 2025 Note that the pattern is matched against whole element name and therefore .* clauses need to be used 2026 at pattern beginning and/or end to perform substring matching. 2027 </para> 2028 2029 <para> 2030 See <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html"><literal>java.util.regex.Pattern</literal></ulink> 2031 documentation for pattern syntax. 2032 </para> 2033 </sect1> 2034 2035 <sect1> 2036 <title>Caveats</title> 2037 2038 <para> 2039 <literal>Match</literal> clauses can only match information that is actually contained in the 2040 bug instances. Every bug instance has a class, so in general, excluding 2041 bugs by class will work. 2042 </para> 2043 2044 <para> 2045 Some bug instances have two (or more) classes. For example, the DE (dropped exception) 2046 bugs report both the class containing the method where the dropped exception 2047 happens, and the class which represents the type of the dropped exception. 2048 Only the <emphasis>first</emphasis> (primary) class is matched against <literal>Match</literal> clauses. 2049 So, for example, if you want to suppress IC (initialization circularity) 2050 reports for classes "com.foobar.A" and "com.foobar.B", you would use 2051 two <literal>Match</literal> clauses: 2052 2053 <programlisting> 2054 <Match> 2055 <Class name="com.foobar.A" /> 2056 <Bug code="IC" /> 2057 </Match> 2058 2059 <Match> 2060 <Class name="com.foobar.B" /> 2061 <Bug code="IC" /> 2062 </Match> 2063 </programlisting> 2064 2065 By explicitly matching both classes, you ensure that the IC bug instance will be 2066 matched regardless of which class involved in the circularity happens to be 2067 listed first in the bug instance. (Of course, this approach might accidentally 2068 supress circularities involving "com.foobar.A" or "com.foobar.B" and a third 2069 class.) 2070 </para> 2071 2072 <para> 2073 Many kinds of bugs report what method they occur in. For those bug instances, 2074 you can put <literal>Method</literal> clauses in the <literal>Match</literal> element and they should work 2075 as expected. 2076 </para> 2077 2078 </sect1> 2079 2080 <sect1> 2081 <title>Examples</title> 2082 2083 <para> 2084 1. Match all bug reports for a class. 2085 2086 <programlisting> 2087 <![CDATA[ 2088 <Match> 2089 <Class name="com.foobar.MyClass" /> 2090 </Match> 2091 ]]> 2092 </programlisting> 2093 2094 </para> 2095 2096 <para> 2097 2. Match certain tests from a class by specifying their abbreviations. 2098 <programlisting> 2099 <![CDATA[ 2100 <Match> 2101 <Class name="com.foobar.MyClass"/ > 2102 <Bug code="DE,UrF,SIC" /> 2103 </Match> 2104 ]]> 2105 </programlisting> 2106 </para> 2107 2108 <para> 2109 3. Match certain tests from all classes by specifying their abbreviations. 2110 2111 <programlisting> 2112 <![CDATA[ 2113 <Match> 2114 <Bug code="DE,UrF,SIC" /> 2115 </Match> 2116 ]]> 2117 </programlisting> 2118 </para> 2119 2120 <para> 2121 4. Match certain tests from all classes by specifying their category. 2122 2123 <programlisting> 2124 <![CDATA[ 2125 <Match> 2126 <Bug category="PERFORMANCE" /> 2127 </Match> 2128 ]]> 2129 </programlisting> 2130 </para> 2131 2132 <para> 2133 5. Match bug types from specified methods of a class by their abbreviations. 2134 2135 <programlisting> 2136 <![CDATA[ 2137 <Match> 2138 <Class name="com.foobar.MyClass" /> 2139 <Or> 2140 <Method name="frob" params="int,java.lang.String" returns="void" /> 2141 <Method name="blat" params="" returns="boolean" /> 2142 </Or> 2143 <Bug code="DC" /> 2144 </Match> 2145 ]]> 2146 </programlisting> 2147 </para> 2148 2149 <para> 2150 6. Match a particular bug pattern in a particular method. 2151 2152 <programlisting> 2153 <![CDATA[ 2154 <!-- A method with an open stream false positive. --> 2155 <Match> 2156 <Class name="com.foobar.MyClass" /> 2157 <Method name="writeDataToFile" /> 2158 <Bug pattern="OS_OPEN_STREAM" /> 2159 </Match> 2160 ]]> 2161 </programlisting> 2162 </para> 2163 2164 <para> 2165 7. Match a particular bug pattern with a given priority in a particular method. 2166 2167 <programlisting> 2168 <![CDATA[ 2169 <!-- A method with a dead local store false positive (medium priority). --> 2170 <Match> 2171 <Class name="com.foobar.MyClass" /> 2172 <Method name="someMethod" /> 2173 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 2174 <Priority value="2" /> 2175 </Match> 2176 ]]> 2177 </programlisting> 2178 </para> 2179 2180 <para> 2181 8. Match minor bugs introduced by AspectJ compiler (you are probably not interested in these unless 2182 you are an AspectJ developer). 2183 2184 <programlisting> 2185 <![CDATA[ 2186 <Match> 2187 <Class name="~.*\$AjcClosure\d+" /> 2188 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 2189 <Method name="run" /> 2190 </Match> 2191 <Match> 2192 <Bug pattern="UUF_UNUSED_FIELD" /> 2193 <Field name="~ajc\$.*" /> 2194 </Match> 2195 ]]> 2196 </programlisting> 2197 </para> 2198 2199 <para> 2200 9. Match bugs in specific parts of the code base 2201 2202 <programlisting> 2203 <![CDATA[ 2204 <!-- match unused fields warnings in Messages classes in all packages --> 2205 <Match> 2206 <Class name="~.*\.Messages" /> 2207 <Bug code="UUF" /> 2208 </Match> 2209 <!-- match mutable statics warnings in all internal packages --> 2210 <Match> 2211 <Package name="~.*\.internal" /> 2212 <Bug code="MS" /> 2213 </Match> 2214 <!-- match anonymoous inner classes warnings in ui package hierarchy --> 2215 <Match> 2216 <Package name="~com\.foobar\.fooproject\.ui.*" /> 2217 <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" /> 2218 </Match> 2219 ]]> 2220 </programlisting> 2221 </para> 2222 2223 <para> 2224 10. Match bugs on fields or methods with specific signatures 2225 <programlisting> 2226 <![CDATA[ 2227 <!-- match System.exit(...) usage warnings in void main(String[]) methods in all classes --> 2228 <Match> 2229 <Method returns="void" name="main" params="java.lang.String[]" /> 2230 <Bug pattern="DM_EXIT" /> 2231 </Match> 2232 <!-- match UuF warnings on fields of type com.foobar.DebugInfo on all classes --> 2233 <Match> 2234 <Field type="com.foobar.DebugInfo" /> 2235 <Bug code="UuF" /> 2236 </Match> 2237 ]]> 2238 </programlisting> 2239 </para> 2240 2241 2242 <para> 2243 11. Match bugs using the Not filter operator 2244 <programlisting> 2245 <![CDATA[ 2246 <!-- ignore all bugs in test classes, except for those bugs specifically relating to JUnit tests --> 2247 <!-- i.e. filter bug if ( classIsJUnitTest && ! bugIsRelatedToJUnit ) --> 2248 <Match> 2249 <!-- the Match filter is equivalent to a logical 'And' --> 2250 2251 <Class name="~.*\.*Test" /> 2252 <!-- test classes are suffixed by 'Test' --> 2253 2254 <Not> 2255 <Bug code="IJU" /> <!-- 'IJU' is the code for bugs related to JUnit test code --> 2256 </Not> 2257 </Match> 2258 ]]> 2259 </programlisting> 2260 </para> 2261 2262 </sect1> 2263 2264 <sect1> 2265 <title>Complete Example</title> 2266 2267 <programlisting> 2268 <![CDATA[ 2269 <FindBugsFilter> 2270 <Match> 2271 <Class name="com.foobar.ClassNotToBeAnalyzed" /> 2272 </Match> 2273 2274 <Match> 2275 <Class name="com.foobar.ClassWithSomeBugsMatched" /> 2276 <Bug code="DE,UrF,SIC" /> 2277 </Match> 2278 2279 <!-- Match all XYZ violations. --> 2280 <Match> 2281 <Bug code="XYZ" /> 2282 </Match> 2283 2284 <!-- Match all doublecheck violations in these methods of "AnotherClass". --> 2285 <Match> 2286 <Class name="com.foobar.AnotherClass" /> 2287 <Or> 2288 <Method name="nonOverloadedMethod" /> 2289 <Method name="frob" params="int,java.lang.String" returns="void" /> 2290 <Method name="blat" params="" returns="boolean" /> 2291 </Or> 2292 <Bug code="DC" /> 2293 </Match> 2294 2295 <!-- A method with a dead local store false positive (medium priority). --> 2296 <Match> 2297 <Class name="com.foobar.MyClass" /> 2298 <Method name="someMethod" /> 2299 <Bug pattern="DLS_DEAD_LOCAL_STORE" /> 2300 <Priority value="2" /> 2301 </Match> 2302 2303 <!-- All bugs in test classes, except for JUnit-specific bugs --> 2304 <Match> 2305 <Class name="~.*\.*Test" /> 2306 <Not> 2307 <Bug code="IJU" /> 2308 </Not> 2309 </Match> 2310 2311 </FindBugsFilter> 2312 ]]> 2313 </programlisting> 2314 2315 </sect1> 2316 2317 2318 </chapter> 2319 2320 2321 <!-- 2322 ************************************************************************** 2323 Analysis properties 2324 ************************************************************************** 2325 --> 2326 2327 <chapter id="analysisprops"> 2328 <title>Analysis Properties</title> 2329 2330 <para> 2331 &FindBugs; allows several aspects of the analyses it performs to be 2332 customized. System properties are used to configure these options. 2333 This chapter describes the configurable analysis options. 2334 </para> 2335 2336 <para> 2337 The analysis options have two main purposes. First, they allow you 2338 to inform &FindBugs; about the meaning of methods in your application, 2339 so that it can produce more accurate results, or produce fewer 2340 false warnings. Second, they allow you to configure the precision 2341 of the analysis performed. Reducing analysis precision can save 2342 memory and analysis time, at the expense of missing some real bugs, 2343 or producing more false warnings. 2344 </para> 2345 2346 <para> 2347 The analysis options are set using the <command>-property</command> 2348 command line option. For example: 2349 <screen> 2350 <prompt>$ </prompt><command>findbugs -textui -property "cfg.noprune=true" <replaceable>myApp.jar</replaceable></command> 2351 </screen> 2352 </para> 2353 2354 <para> 2355 The list of configurable analysis properties is shown in 2356 <xref linkend="analysisproptable"/>. 2357 </para> 2358 2359 <table id="analysisproptable"> 2360 <title>Configurable Analysis Properties</title> 2361 <tgroup cols="3" align="left"> 2362 <thead> 2363 <row> 2364 <entry>Property Name</entry> 2365 <entry>Value</entry> 2366 <entry>Meaning</entry> 2367 </row> 2368 </thead> 2369 <tbody> 2370 <!-- 2371 <row> 2372 <entry>cfg.noprune</entry> 2373 <entry>true or false</entry> 2374 <entry>If true, infeasible exception edges are not pruned from 2375 the control flow graphs of analyzed methods. This option 2376 increases the speed of the analysis (by about 20%-30%), 2377 but causes some detectors to produce more false warnings.</entry> 2378 </row> 2379 --> 2380 <row> 2381 <entry>findbugs.assertionmethods</entry> 2382 <entry>Comma-separated list of fully qualified method names: 2383 e.g., "com.foo.MyClass.checkAssertion"</entry> 2384 <entry>This property specifies the names of methods that are used 2385 to check program assertions. Specifying these methods allows 2386 the null pointer dereference bug detector to avoid reporting 2387 false warnings for values which are checked by assertion 2388 methods.</entry> 2389 </row> 2390 <row> 2391 <entry>findbugs.de.comment</entry> 2392 <entry>true or false</entry> 2393 <entry>If true, the DroppedException detector scans source code 2394 for empty catch blocks for a comment, and if one is found, does 2395 not report a warning.</entry> 2396 </row> 2397 <row> 2398 <entry>findbugs.maskedfields.locals</entry> 2399 <entry>true or false</entry> 2400 <entry>If true, emit low priority warnings for local variables 2401 which obscure fields. Default is false.</entry> 2402 </row> 2403 <row> 2404 <entry>findbugs.nullderef.assumensp</entry> 2405 <entry>true or false</entry> 2406 <entry>not used 2407 (intention: If true, the null dereference detector assumes that any 2408 reference value returned from a method or passed to a method 2409 in a parameter might be null. Default is false. Note that 2410 enabling this property will very likely cause a large number 2411 of false warnings to be produced.)</entry> 2412 </row> 2413 <row> 2414 <entry>findbugs.refcomp.reportAll</entry> 2415 <entry>true or false</entry> 2416 <entry>If true, all suspicious reference comparisons 2417 using the == and != operators are reported. If false, 2418 only one such warning is issued per method. Default 2419 is false.</entry> 2420 </row> 2421 <row> 2422 <entry>findbugs.sf.comment</entry> 2423 <entry>true or false</entry> 2424 <entry>If true, the SwitchFallthrough detector will only report 2425 warnings for cases where the source code does not have a comment 2426 containing the words "fall" or "nobreak". (An accurate source 2427 path must be used for this feature to work correctly.) 2428 This helps find cases where the switch fallthrough is likely 2429 to be unintentional.</entry> 2430 </row> 2431 <!-- see others at src/doc/manual/sysprops.html 2432 <row> 2433 <entry></entry> 2434 <entry></entry> 2435 <entry></entry> 2436 </row> 2437 --> 2438 </tbody> 2439 </tgroup> 2440 </table> 2441 2442 </chapter> 2443 2444 <!-- 2445 ************************************************************************** 2446 Annotations 2447 *************************************************************************** 2448 --> 2449 2450 <chapter id="annotations"> 2451 <title>Annotations</title> 2452 2453 <para> 2454 &FindBugs; supports several annotations to express the developer's intent 2455 so that FindBugs can issue warnings more appropriately. You need to use 2456 Java 5 to use annotations, and must place the annotations.jar and jsr305.jar 2457 files in the classpath while compiling your program. 2458 </para> 2459 2460 <variablelist> 2461 <varlistentry> 2462 <term><command>edu.umd.cs.findbugs.annotations.CheckForNull</command></term> 2463 <listitem> 2464 <command>[Target]</command> Field, Method, Parameter 2465 </listitem> 2466 <listitem> 2467 <para> 2468 The annotated element might be null, and uses of the element should check for null. 2469 When this annotation is applied to a method it applies to the method return value. 2470 </para> 2471 </listitem> 2472 </varlistentry> 2473 2474 <varlistentry> 2475 <term><command>edu.umd.cs.findbugs.annotations.CheckReturnValue</command></term> 2476 <listitem> 2477 <command>[Target]</command> Method, Constructor 2478 </listitem> 2479 <listitem> 2480 <variablelist> 2481 <varlistentry> 2482 <term><command>[Parameter]</command></term> 2483 <listitem> 2484 <para> 2485 <command>priority:</command>The priority of the warning (HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 2486 </para> 2487 </listitem> 2488 <listitem> 2489 <para> 2490 <command>explanation:</command>A textual explaination of why the return value should be checked. Default value:"". 2491 </para> 2492 </listitem> 2493 </varlistentry> 2494 </variablelist> 2495 </listitem> 2496 <listitem> 2497 <para> 2498 This annotation is used to denote a method whose return value should always be checked after invoking the method. 2499 </para> 2500 </listitem> 2501 </varlistentry> 2502 2503 <varlistentry> 2504 <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotation</command></term> 2505 <listitem> 2506 <command>[Target]</command> Type, Package 2507 </listitem> 2508 <listitem> 2509 <variablelist> 2510 <varlistentry> 2511 <term><command>[Parameter]</command></term> 2512 <listitem> 2513 <para> 2514 <command>value:</command>Annotation class objects. More than one class can be specified. 2515 </para> 2516 </listitem> 2517 <listitem> 2518 <para> 2519 <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 2520 </para> 2521 </listitem> 2522 </varlistentry> 2523 </variablelist> 2524 </listitem> 2525 <listitem> 2526 <para> 2527 Indicates that all members of the class or package should be annotated with the default 2528 value of the supplied annotation classes. This would be used for behavior annotations 2529 such as @NonNull, @CheckForNull, or @CheckReturnValue. In particular, you can use 2530 @DefaultAnnotation(NonNull.class) on a class or package, and then use @Nullable only 2531 on those parameters, methods or fields that you want to allow to be null. 2532 </para> 2533 </listitem> 2534 </varlistentry> 2535 2536 <varlistentry> 2537 <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForFields</command></term> 2538 <listitem> 2539 <command>[Target]</command> Type, Package 2540 </listitem> 2541 <listitem> 2542 <variablelist> 2543 <varlistentry> 2544 <term><command>[Parameter]</command></term> 2545 <listitem> 2546 <para> 2547 <command>value:</command>Annotation class objects. More than one class can be specified. 2548 </para> 2549 </listitem> 2550 <listitem> 2551 <para> 2552 <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 2553 </para> 2554 </listitem> 2555 </varlistentry> 2556 </variablelist> 2557 </listitem> 2558 <listitem> 2559 <para> 2560 This is same as the DefaultAnnotation except it only applys to fields. 2561 </para> 2562 </listitem> 2563 </varlistentry> 2564 2565 <varlistentry> 2566 <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForMethods</command></term> 2567 <listitem> 2568 <command>[Target]</command> Type, Package 2569 </listitem> 2570 <listitem> 2571 <variablelist> 2572 <varlistentry> 2573 <term><command>[Parameter]</command></term> 2574 <listitem> 2575 <para> 2576 <command>value:</command>Annotation class objects. More than one class can be specified. 2577 </para> 2578 </listitem> 2579 <listitem> 2580 <para> 2581 <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 2582 </para> 2583 </listitem> 2584 </varlistentry> 2585 </variablelist> 2586 </listitem> 2587 <listitem> 2588 <para> 2589 This is same as the DefaultAnnotation except it only applys to methods. 2590 </para> 2591 </listitem> 2592 </varlistentry> 2593 2594 <varlistentry> 2595 <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters</command></term> 2596 <listitem> 2597 <command>[Target]</command> Type, Package 2598 </listitem> 2599 <listitem> 2600 <variablelist> 2601 <varlistentry> 2602 <term><command>[Parameter]</command></term> 2603 <listitem> 2604 <para> 2605 <command>value:</command>Annotation class objects. More than one class can be specified. 2606 </para> 2607 </listitem> 2608 <listitem> 2609 <para> 2610 <command>priority:</command>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 2611 </para> 2612 </listitem> 2613 </varlistentry> 2614 </variablelist> 2615 </listitem> 2616 <listitem> 2617 <para> 2618 This is same as the DefaultAnnotation except it only applys to method parameters. 2619 </para> 2620 </listitem> 2621 </varlistentry> 2622 2623 <varlistentry> 2624 <term><command>edu.umd.cs.findbugs.annotations.NonNull</command></term> 2625 <listitem> 2626 <command>[Target]</command> Field, Method, Parameter 2627 </listitem> 2628 <listitem> 2629 <para> 2630 The annotated element must not be null. 2631 Annotated fields must not be null after construction has completed. Annotated methods must have non-null return values. 2632 </para> 2633 </listitem> 2634 </varlistentry> 2635 2636 <varlistentry> 2637 <term><command>edu.umd.cs.findbugs.annotations.Nullable</command></term> 2638 <listitem> 2639 <command>[Target]</command> Field, Method, Parameter 2640 </listitem> 2641 <listitem> 2642 <para> 2643 The annotated element could be null under some circumstances. In general, this means 2644 developers will have to read the documentation to determine when a null value is 2645 acceptable and whether it is neccessary to check for a null value. FindBugs will 2646 treat the annotated items as though they had no annotation. 2647 </para> 2648 <para> 2649 In pratice this annotation is useful only for overriding an overarching NonNull 2650 annotation. 2651 </para> 2652 </listitem> 2653 </varlistentry> 2654 2655 <varlistentry> 2656 <term><command>edu.umd.cs.findbugs.annotations.OverrideMustInvoke</command></term> 2657 <listitem> 2658 <command>[Target]</command> Method 2659 </listitem> 2660 <listitem> 2661 <variablelist> 2662 <varlistentry> 2663 <term><command>[Parameter]</command></term> 2664 <listitem> 2665 <para> 2666 <command>value:</command>Specify when the super invocation should be 2667 performed (FIRST, ANYTIME, LAST). Default value:ANYTIME. 2668 </para> 2669 </listitem> 2670 </varlistentry> 2671 </variablelist> 2672 </listitem> 2673 <listitem> 2674 <para> 2675 Used to annotate a method that, if overridden, must (or should) be invoke super 2676 in the overriding method. Examples of such methods include finalize() and clone(). 2677 The argument to the method indicates when the super invocation should occur: 2678 at any time, at the beginning of the overriding method, or at the end of the overriding method. 2679 (This anotation is not implmemented in FindBugs as of September 8, 2006). 2680 </para> 2681 </listitem> 2682 </varlistentry> 2683 2684 <varlistentry> 2685 <term><command>edu.umd.cs.findbugs.annotations.PossiblyNull</command></term> 2686 <listitem> 2687 <para> 2688 This annotation is deprecated. Use CheckForNull instead. 2689 </para> 2690 </listitem> 2691 </varlistentry> 2692 2693 <varlistentry> 2694 <term><command>edu.umd.cs.findbugs.annotations.SuppressWarnings</command></term> 2695 <listitem> 2696 <command>[Target]</command> Type, Field, Method, Parameter, Constructor, Package 2697 </listitem> 2698 <listitem> 2699 <variablelist> 2700 <varlistentry> 2701 <term><command>[Parameter]</command></term> 2702 <listitem> 2703 <para> 2704 <command>value:</command>The name of the warning. More than one name can be specified. 2705 </para> 2706 </listitem> 2707 <listitem> 2708 <para> 2709 <command>justification:</command>Reason why the warning should be ignored. Default value:"". 2710 </para> 2711 </listitem> 2712 </varlistentry> 2713 </variablelist> 2714 </listitem> 2715 <listitem> 2716 <para> 2717 The set of warnings that are to be suppressed by the compiler in the annotated element. 2718 Duplicate names are permitted. The second and successive occurrences of a name are ignored. 2719 The presence of unrecognized warning names is <emphasis>not</emphasis> an error: Compilers 2720 must ignore any warning names they do not recognize. They are, however, free to emit a 2721 warning if an annotation contains an unrecognized warning name. Compiler vendors should 2722 document the warning names they support in conjunction with this annotation type. They 2723 are encouraged to cooperate to ensure that the same names work across multiple compilers. 2724 </para> 2725 </listitem> 2726 </varlistentry> 2727 2728 <varlistentry> 2729 <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term> 2730 <listitem> 2731 <command>[Target]</command> Field, Method, Parameter 2732 </listitem> 2733 <listitem> 2734 <para> 2735 Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. 2736 </para> 2737 </listitem> 2738 </varlistentry> 2739 2740 <varlistentry> 2741 <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term> 2742 <listitem> 2743 <command>[Target]</command> Field, Method, Parameter 2744 </listitem> 2745 <listitem> 2746 <para> 2747 Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. 2748 </para> 2749 </listitem> 2750 </varlistentry> 2751 </variablelist> 2752 2753 <para> 2754 &FindBugs; also supports the following annotations: 2755 <itemizedlist> 2756 <listitem>net.jcip.annotations.GuardedBy</listitem> 2757 <listitem>net.jcip.annotations.Immutable</listitem> 2758 <listitem>net.jcip.annotations.NotThreadSafe</listitem> 2759 <listitem>net.jcip.annotations.ThreadSafe</listitem> 2760 </itemizedlist> 2761 </para> 2762 <para> 2763 You can refer the JCIP annotation <ulink url="http://jcip.net/annotations/doc/index.html"> 2764 API documentation</ulink> at <ulink url="http://jcip.net/">Java Concurrency in Practice</ulink>. 2765 </para> 2766 </chapter> 2767 2768 <!-- 2769 ************************************************************************** 2770 Using rejarForAnalysis 2771 ************************************************************************** 2772 --> 2773 2774 <chapter id="rejarForAnalysis"> 2775 <title>Using rejarForAnalysis</title> 2776 2777 <para> 2778 If your project consists of many jarfiles or the jarfiles are scattered 2779 over many directories, you may wish to use the <command>rejarForAnalysis 2780 </command> script to make 2781 FindBugs invocation easier. The script collects many jarfiles and combines them 2782 into a single, large jarfile that can then be easily passed to FindBugs for 2783 analysis. This can be particularly useful in combination with the 'find' command 2784 on unix systems; e.g. <command>find . -name '*.jar' | xargs rejarForAnalysis 2785 </command>. 2786 </para> 2787 2788 <para> 2789 The <command>rejarForAnalysis</command> script 2790 can also be used to split a very large project up into a set of jarfiles with 2791 the project classfiles evenly divided between them. This is useful when running 2792 FindBugs on the entire project is not practical due to time or memory consumption. 2793 Instead of running FindBugs on the entire project, you may use <command> 2794 rejarForAnalysis</command> build one large, all-inclusive jarfile 2795 containing all classes, invoke <command>rejarForAnalysis</command> 2796 again to split the project into multiple jarfiles, then run FindBugs 2797 on each divided jarfiles in turn, specifying the the all-inclusive jarfile in 2798 the <command>-auxclasspath</command>. 2799 </para> 2800 2801 <para> 2802 These are the options accepted by the <command>rejarForAnalysis</command> script: 2803 </para> 2804 2805 <variablelist> 2806 <varlistentry> 2807 <term><command>-maxAge</command> <replaceable>days</replaceable></term> 2808 <listitem> 2809 <para> 2810 Maximum age in days (ignore jar files older than this). 2811 </para> 2812 </listitem> 2813 </varlistentry> 2814 <varlistentry> 2815 <term><command>-inputFileList</command> <replaceable>filename</replaceable></term> 2816 <listitem> 2817 <para> 2818 Text file containing names of jar files. 2819 </para> 2820 </listitem> 2821 </varlistentry> 2822 <varlistentry> 2823 <term><command>-maxClasses</command> <replaceable>num</replaceable></term> 2824 <listitem> 2825 <para> 2826 Maximum number of classes per analysis*.jar file. 2827 </para> 2828 </listitem> 2829 </varlistentry> 2830 <varlistentry> 2831 <term><command>-prefix</command> <replaceable>class name prefix</replaceable></term> 2832 <listitem> 2833 <para> 2834 Prefix of class names that should be analyzed (e.g., edu.umd.cs.). 2835 </para> 2836 </listitem> 2837 </varlistentry> 2838 </variablelist> 2839 </chapter> 2840 2841 <!-- 2842 ************************************************************************** 2843 Data mining 2844 ************************************************************************** 2845 --> 2846 2847 <chapter id="datamining"> 2848 <title>Data mining of bugs with &FindBugs;™</title> 2849 2850 <para> 2851 FindBugs incorporates an ability to perform sophisticated queries on bug 2852 databases and track warnings across multiple versions of code being 2853 studied, allowing you to do things such as seeing when a bug was first introduced, examining 2854 just the warnings that have been introduced since the last release, or graphing the number 2855 of infinite recursive loops in your code over time.</para> 2856 2857 <para> 2858 These techniques all depend upon the XML format used by FindBugs for storing warnings. 2859 These XML files usually contain just the warnings from one particular analysis run, but 2860 they can also store the results from analyzing a sequence of software builds or versions. 2861 </para> 2862 2863 <para> 2864 Any FindBugs XML bug database contains a version name and timestamp. 2865 FindBugs tries to compute a timestamp from the timestamps of the files that 2866 are analyzed (e.g., the timestamp is intended to be the time the class files 2867 were generated, not analyzed). Each bug database also contains a version name. 2868 Both the version name and timestamp can be set manually using the 2869 <command>setBugDatabaseInfo</command> (<xref linkend="setBugDatabaseInfo" />) command. 2870 </para> 2871 2872 <para>A multiversion bug database assigns a sequence number to each version of 2873 the analyzed code. These sequence numbers are simply successive integers, 2874 starting at 0 (e.g., a bug database for 4 versions of the code will contain 2875 versions 0..3). The bug database will also record the name and timestamp for 2876 each version. The <command>filterBugs</command> command allows you to refer 2877 to a version by sequence number, name or timestamp.</para> 2878 2879 <para> 2880 You can take a sequence (or pair) of single version bug databases and create 2881 from them a multiversion bug database, or combine a multiversion bug database 2882 with a sequence of later single-version bug databases.</para> 2883 2884 <para> 2885 Some of these commands can be invoked as ant tasks. See below for specifics 2886 on how to invoke them and what attributes and arguments they take. All of 2887 the examples assume that the <literal>findbugs.lib</literal> 2888 <literal>refid</literal> is set correctly. Here is one way to set it: 2889 </para> 2890 2891 <programlisting> 2892 <![CDATA[ 2893 <!-- findbugs task definition --> 2894 <property name="findbugs.home" value="/your/path/to/findbugs" /> 2895 <path id="findbugs.lib"> 2896 <fileset dir="${findbugs.home}/lib"> 2897 <include name="findbugs-ant.jar"/> 2898 </fileset> 2899 </path> 2900 ]]> 2901 </programlisting> 2902 2903 <sect1 id="commands"> 2904 <title>Commands</title> 2905 2906 <para> 2907 All tools for FindBugs data mining are can be invoked from the command line, 2908 and some of the more useful tools can also be invoked from an 2909 ant build file.</para> 2910 2911 <para> 2912 Briefly, the command-line tools are:</para> 2913 2914 <variablelist> 2915 <varlistentry> 2916 <term><command><link linkend="unionBugs">unionBugs</link></command></term> 2917 <listitem> 2918 <para> 2919 combine the results from separate analysis of disjoint 2920 classes 2921 </para> 2922 </listitem> 2923 </varlistentry> 2924 <varlistentry> 2925 <term><command><link linkend="computeBugHistory">computeBugHistory</link></command></term> 2926 <listitem> 2927 <para>Merge bug warnings from multiple versions of 2928 analyzed code into 2929 a single multiversion bug database. This can either be used 2930 to add more versions to an existing multiversion database, 2931 or to create a multiversion database from a sequence of single version 2932 bug warning databases.</para> 2933 </listitem> 2934 </varlistentry> 2935 <varlistentry> 2936 <term><command><link linkend="setBugDatabaseInfo">setBugDatabaseInfo</link></command></term> 2937 <listitem> 2938 <para>Set information such as the revision name or 2939 timestamp in an XML bug database</para> 2940 </listitem> 2941 </varlistentry> 2942 <varlistentry> 2943 <term><command><link linkend="listBugDatabaseInfo">listBugDatabaseInfo</link></command></term> 2944 <listitem> 2945 <para>List information such as the revision name and 2946 timestamp for a list of XML bug databases</para> 2947 </listitem> 2948 </varlistentry> 2949 <varlistentry> 2950 <term><command><link linkend="filterBugs">filterBugs</link></command></term> 2951 <listitem> 2952 <para>Select a subset of a bug database</para> 2953 </listitem> 2954 </varlistentry> 2955 <varlistentry> 2956 <term><command><link linkend="mineBugHistory">mineBugHistory</link></command></term> 2957 <listitem> 2958 <para>Generate a tabular listing of the number of warnings in each 2959 version of a multiversion bug database</para> 2960 </listitem> 2961 </varlistentry> 2962 <varlistentry> 2963 <term><command><link linkend="defectDensity">defectDensity</link></command></term> 2964 <listitem> 2965 <para>List information about defect density 2966 (warnings per 1000 NCSS) 2967 for the entire project and each class and package</para> 2968 </listitem> 2969 </varlistentry> 2970 <varlistentry> 2971 <term><command><link linkend="convertXmlToText">convertXmlToText</link></command></term> 2972 <listitem> 2973 <para>Convert bug warnings in XML format to 2974 a textual one-line-per-bug format, or to HTML</para> 2975 </listitem> 2976 </varlistentry> 2977 </variablelist> 2978 2979 2980 <sect2 id="unionBugs"> 2981 <title>unionBugs</title> 2982 2983 <para> 2984 If you have, for example, separately analyzing each jar file used in an application, 2985 you can use this command to combine the separately generated xml bug warning files into 2986 a single file containing all of the warnings.</para> 2987 2988 <para>Do <emphasis>not</emphasis> use this command to combine results from analyzing different versions of the same 2989 file; use <command>computeBugHistory</command> instead.</para> 2990 2991 <para>Specify the xml files on the command line. The result is sent to standard output.</para> 2992 </sect2> 2993 2994 <sect2 id="computeBugHistory"> 2995 <title>computeBugHistory</title> 2996 2997 <para>Use this command to generate a bug database containing information from different builds or versions 2998 of software you are analyzing. 2999 History is taken from the first file provided as input; any following 3000 files should be single version bug databases (if they contain history, the history in those 3001 files will be ignored).</para> 3002 <para>By default, output is written to the standard output. 3003 </para> 3004 3005 <para>This functionality may also can be accessed from ant. 3006 First create a taskdef for <command>computeBugHistory</command> in your 3007 build file: 3008 </para> 3009 3010 <programlisting> 3011 <![CDATA[ 3012 <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask"> 3013 <classpath refid="findbugs.lib" /> 3014 </taskdef> 3015 ]]> 3016 </programlisting> 3017 3018 <para>Attributes for this ant task are listed in the following table. 3019 To specify input files, nest them inside with a 3020 <literal><datafile></literal> element. For example: 3021 </para> 3022 3023 <programlisting> 3024 <![CDATA[ 3025 <computeBugHistory home="${findbugs.home}" ...> 3026 <datafile name="analyze1.xml"/> 3027 <datafile name="analyze2.xml"/> 3028 </computeBugHistory> 3029 ]]> 3030 </programlisting> 3031 3032 <table id="computeBugHistoryTable"> 3033 <title>Options for computeBugHistory command</title> 3034 <tgroup cols="3" align="left"> 3035 <thead> 3036 <row> 3037 <entry>Command-line option</entry> 3038 <entry>Ant attribute</entry> 3039 <entry>Meaning</entry> 3040 </row> 3041 </thead> 3042 <tbody> 3043 <row><entry>-output <file></entry> <entry>output="<file>"</entry> <entry>save output in the named file (may also be an input file)</entry></row> 3044 <row><entry>-overrideRevisionNames[:truth]</entry> <entry>overrideRevisionNames="[true|false]"</entry><entry>override revision names for each version with names computed from the filenames</entry></row> 3045 <row><entry>-noPackageMoves[:truth]</entry> <entry>noPackageMoves="[true|false]"</entry><entry>if a class has moved to another package, treat warnings in that class as seperate</entry></row> 3046 <row><entry>-preciseMatch[:truth]</entry> <entry>preciseMatch="[true|false]"</entry><entry>require bug patterns to match precisely</entry></row> 3047 <row><entry>-precisePriorityMatch[:truth]</entry> <entry>precisePriorityMatch="[true|false]"</entry><entry>consider two warnings as the same only if priorities match exactly</entry></row> 3048 <row><entry>-quiet[:truth]</entry> <entry>quiet="[true|false]"</entry><entry>don't generate any output to standard out unless there is an error</entry></row> 3049 <row><entry>-withMessages[:truth]</entry> <entry>withMessages="[true|false]"</entry><entry>include human-readable messages describing the warnings in XML output</entry></row> 3050 </tbody> 3051 </tgroup> 3052 </table> 3053 3054 </sect2> 3055 <sect2 id="filterBugs"> 3056 <title>filterBugs</title> 3057 <para>This command is used to select a subset of warnings from a FindBugs XML warning file 3058 and write the selected subset to a new FindBugs warning file.</para> 3059 <para> 3060 This command takes a sequence of options, and either zero, one or two 3061 filenames of findbugs xml bug files on the command line.</para> 3062 <para>If no file names are provided, the command reads from standard input 3063 and writes to standard output. If one file name is provided, 3064 it reads from the file and writes to standard output. 3065 If two file names are provided, it reads from the first and writes the output 3066 to the second file name.</para> 3067 3068 <para>This functionality may also can be accessed from ant. 3069 First create a taskdef for <command>filterBugs</command> in your 3070 build file: 3071 </para> 3072 3073 <programlisting> 3074 <![CDATA[ 3075 <taskdef name="filterBugs" classname="edu.umd.cs.findbugs.anttask.FilterBugsTask"> 3076 <classpath refid="findbugs.lib" /> 3077 </taskdef> 3078 ]]> 3079 </programlisting> 3080 3081 <para>Attributes for this ant task are listed in the following table. 3082 To specify an input file either use the input attribute or nest it inside 3083 the ant call with a <literal><datafile></literal> element. For example: 3084 </para> 3085 3086 <programlisting> 3087 <![CDATA[ 3088 <filterBugs home="${findbugs.home}" ...> 3089 <datafile name="analyze.xml"/> 3090 </filterBugs> 3091 ]]> 3092 </programlisting> 3093 3094 <table id="filterOptionsTable"> 3095 <title>Options for filterBugs command</title> 3096 <tgroup cols="3" align="left"> 3097 <thead> 3098 <row> 3099 <entry>Command-line option</entry> 3100 <entry>Ant attribute</entry> 3101 <entry>Meaning</entry> 3102 </row> 3103 </thead> 3104 <tbody> 3105 <row><entry></entry> <entry>input="<file>"</entry> <entry>use file as input</entry></row> 3106 <row><entry></entry> <entry>output="<file>"</entry> <entry>output results to file</entry></row> 3107 <row><entry>-not</entry> <entry>not="[true|false]"</entry> <entry>reverse (all) switches for the filter</entry></row> 3108 <row><entry>-withSource[:truth]</entry> <entry>withSource="[true|false]"</entry> <entry>only warnings for switch source is available</entry></row> 3109 <row><entry>-exclude <filter file></entry><entry>exclude="<filter file>"</entry> <entry>exclude bugs matching given filter</entry></row> 3110 <row><entry>-include <filter file></entry><entry>include="<filter file>"</entry> <entry>include only bugs matching given filter</entry></row> 3111 <row><entry>-annotation <text></entry> <entry>annotation="<text>"</entry> <entry>allow only warnings containing this text in a manual annotation</entry></row> 3112 <row><entry>-after <when></entry> <entry>after="<when>"</entry> <entry>allow only warnings that first occurred after this version</entry></row> 3113 <row><entry>-before <when></entry> <entry>before="<when>"</entry> <entry>allow only warnings that first occurred before this version</entry></row> 3114 <row><entry>-first <when></entry> <entry>first="<when>"</entry> <entry>allow only warnings that first occurred in this version</entry></row> 3115 <row><entry>-last <when></entry> <entry>last="<when>"</entry> <entry>allow only warnings that last occurred in this version</entry></row> 3116 <row><entry>-fixed <when></entry> <entry>fixed="<when>"</entry> <entry>allow only warnings that last occurred in the previous version (clobbers <option>-last</option>)</entry></row> 3117 <row><entry>-present <when></entry> <entry>present="<when>"</entry> <entry>allow only warnings present in this version</entry></row> 3118 <row><entry>-absent <when></entry> <entry>absent="<when>"</entry> <entry>allow only warnings absent in this version</entry></row> 3119 <row><entry>-active[:truth]</entry> <entry>active="[true|false]"</entry> <entry>allow only warnings alive in the last sequence number</entry></row> 3120 <row><entry>-introducedByChange[:truth]</entry> <entry>introducedByChange="[true|false]"</entry><entry>allow only warnings introduced by a change of an existing class</entry></row> 3121 <row><entry>-removedByChange[:truth]</entry> <entry>removedByChange="[true|false]"</entry> <entry>allow only warnings removed by a change of a persisting class</entry></row> 3122 <row><entry>-newCode[:truth]</entry> <entry>newCode="[true|false]"</entry> <entry>allow only warnings introduced by the addition of a new class</entry></row> 3123 <row><entry>-removedCode[:truth]</entry> <entry>removedCode="[true|false]"</entry> <entry>allow only warnings removed by removal of a class</entry></row> 3124 <row><entry>-priority <level></entry> <entry>priority="<level>"</entry> <entry>allow only warnings with this priority or higher</entry></row> 3125 <row><entry>-maxRank <rank></entry> <entry>rank="[1..20]"</entry> <entry>allow only warnings with this rank or lower</entry></row> 3126 <row><entry>-class <pattern></entry> <entry>class="<class>"</entry> <entry>allow only bugs whose primary class name matches this pattern</entry></row> 3127 <row><entry>-bugPattern <pattern></entry> <entry>bugPattern="<pattern>"</entry> <entry>allow only bugs whose type matches this pattern</entry></row> 3128 <row><entry>-category <category></entry> <entry>category="<category>"</entry> <entry>allow only warnings with a category that starts with this string</entry></row> 3129 <row><entry>-designation <designation></entry> <entry>designation="<designation>"</entry> <entry>allow only warnings with this designation (e.g., -designation SHOULD_FIX)</entry></row> 3130 <row><entry>-withMessages[:truth] </entry> <entry>withMessages="[true|false]"</entry> <entry>the generated XML should contain textual messages</entry></row> 3131 </tbody> 3132 </tgroup> 3133 </table> 3134 3135 </sect2> 3136 3137 <sect2 id="mineBugHistory"> 3138 <title>mineBugHistory</title> 3139 <para>This command generates a table containing counts of the numbers of warnings 3140 in each version of a multiversion bug database.</para> 3141 3142 3143 <para>This functionality may also can be accessed from ant. 3144 First create a taskdef for <command>mineBugHistory</command> in your 3145 build file: 3146 </para> 3147 3148 <programlisting> 3149 <![CDATA[ 3150 <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask"> 3151 <classpath refid="findbugs.lib" /> 3152 </taskdef> 3153 ]]> 3154 </programlisting> 3155 3156 <para>Attributes for this ant task are listed in the following table. 3157 To specify an input file either use the <literal>input</literal> 3158 attribute or nest it inside the ant call with a 3159 <literal><datafile></literal> element. For example: 3160 </para> 3161 3162 <programlisting> 3163 <![CDATA[ 3164 <mineBugHistory home="${findbugs.home}" ...> 3165 <datafile name="analyze.xml"/> 3166 </mineBugHistory> 3167 ]]> 3168 </programlisting> 3169 3170 <table id="mineBugHistoryOptionsTable"> 3171 <title>Options for mineBugHistory command</title> 3172 <tgroup cols="3" align="left"> 3173 <thead> 3174 <row> 3175 <entry>Command-line option</entry> 3176 <entry>Ant attribute</entry> 3177 <entry>Meaning</entry> 3178 </row> 3179 </thead> 3180 <tbody> 3181 <row><entry></entry> <entry>input="<file>"</entry> <entry>use file as input</entry></row> 3182 <row><entry></entry> <entry>output="<file>"</entry> <entry>write output to file</entry></row> 3183 <row><entry>-formatDates</entry> <entry>formatDates="[true|false]"</entry> <entry>render dates in textual form</entry></row> 3184 <row><entry>-noTabs</entry> <entry>noTabs="[true|false]"</entry> <entry>delimit columns with groups of spaces instead of tabs (see below)</entry></row> 3185 <row><entry>-summary</entry> <entry>summary="[true|false]"</entry> <entry>output terse summary of changes over the last ten entries</entry></row> 3186 </tbody> 3187 </tgroup> 3188 </table> 3189 3190 <para> 3191 The <option>-noTabs</option> output can be easier to read from a shell 3192 with a fixed-width font. 3193 Because numeric columns are right-justified, spaces may precede the 3194 first column value. This option also causes <option>-formatDates</option> 3195 to render dates in terser format without embedded whitespace. 3196 </para> 3197 3198 <para>The table is a tab-separated (barring <option>-noTabs</option>) 3199 table with the following columns:</para> 3200 3201 <table id="mineBugHistoryColumns"> 3202 <title>Columns in mineBugHistory output</title> 3203 <tgroup cols="2" align="left"> 3204 <thead> 3205 <row> 3206 <entry>Title</entry> 3207 <entry>Meaning</entry> 3208 </row> 3209 </thead> 3210 <tbody> 3211 <row><entry>seq</entry><entry>Sequence number (successive integers, starting at 0)</entry></row> 3212 <row><entry>version</entry><entry>Version name</entry></row> 3213 <row><entry>time</entry><entry>Release timestamp</entry></row> 3214 <row><entry>classes</entry><entry>Number of classes analyzed</entry></row> 3215 <row><entry>NCSS</entry><entry>Non Commenting Source Statements</entry></row> 3216 <row><entry>added</entry><entry>Count of new warnings for a class that existed in the previous version</entry></row> 3217 <row><entry>newCode</entry><entry>Count of new warnings for a class that did not exist in the previous version</entry></row> 3218 <row><entry>fixed</entry><entry>Count of warnings removed from a class that remains in the current version</entry></row> 3219 <row><entry>removed</entry><entry>Count of warnings in the previous version for a class that is not present in the current version</entry></row> 3220 <row><entry>retained</entry><entry>Count of warnings that were in both the previous and current version</entry></row> 3221 <row><entry>dead</entry><entry>Warnings that were present in earlier versions but in neither the current version or the immediately preceeding version</entry></row> 3222 <row><entry>active</entry><entry>Total warnings present in the current version</entry></row> 3223 </tbody> 3224 </tgroup> 3225 </table> 3226 </sect2> 3227 3228 <sect2 id="defectDensity"> 3229 <title>defectDensity</title> 3230 <para> 3231 This command lists information about defect density (warnings per 1000 NCSS) for the entire project and each class and package. 3232 It can either be invoked with no files specified on the command line (in which case it reads from standard input) 3233 or with one file specified on the command line.</para> 3234 <para>It generates a table with the following columns, and with one 3235 row for the entire project, and one row for each package or class that contains at least 3236 4 warnings.</para> 3237 <table id="defectDensityColumns"> 3238 <title>Columns in defectDensity output</title> 3239 <tgroup cols="2" align="left"> 3240 <thead> 3241 <row> 3242 <entry>Title</entry> 3243 <entry>Meaning</entry> 3244 </row> 3245 </thead> 3246 <tbody> 3247 <row><entry>kind</entry><entry>project, package or class</entry></row> 3248 <row><entry>name</entry><entry>The name of the project, package or class</entry></row> 3249 <row><entry>density</entry><entry>Number of warnings generated per 1000 lines of NCSS.</entry></row> 3250 <row><entry>bugs</entry><entry>Number of warnings</entry></row> 3251 <row><entry>NCSS</entry><entry>Calculated number of NCSS</entry></row> 3252 </tbody> 3253 </tgroup> 3254 </table> 3255 </sect2> 3256 3257 <sect2 id="convertXmlToText"> 3258 <title>convertXmlToText</title> 3259 3260 <para> 3261 This command converts a warning collection in XML format to a text 3262 format with one line per warning, or to HTML. 3263 </para> 3264 3265 <para>This functionality may also can be accessed from ant. 3266 First create a taskdef for <command>convertXmlToText</command> in your 3267 build file: 3268 </para> 3269 3270 <programlisting> 3271 <![CDATA[ 3272 <taskdef name="convertXmlToText" classname="edu.umd.cs.findbugs.anttask.ConvertXmlToTextTask"> 3273 <classpath refid="findbugs.lib" /> 3274 </taskdef> 3275 ]]> 3276 </programlisting> 3277 3278 <para>Attributes for this ant task are listed in the following table.</para> 3279 3280 <table id="convertXmlToTextTable"> 3281 <title>Options for convertXmlToText command</title> 3282 <tgroup cols="3" align="left"> 3283 <thead> 3284 <row> 3285 <entry>Command-line option</entry> 3286 <entry>Ant attribute</entry> 3287 <entry>Meaning</entry> 3288 </row> 3289 </thead> 3290 <tbody> 3291 <row><entry></entry> <entry>input="<filename>"</entry> <entry>use file as input</entry></row> 3292 <row><entry></entry> <entry>output="<filename>"</entry> <entry>output results to file</entry></row> 3293 <row><entry>-longBugCodes</entry> <entry>longBugCodes="[true|false]"</entry> <entry>use the full bug pattern code instead of two-letter abbreviation</entry></row> 3294 <row><entry></entry> <entry>format="text"</entry> <entry>generate plain text output with one bug per line (command-line default)</entry></row> 3295 <row><entry>-html[:stylesheet]</entry> <entry>format="html:<stylesheet>"</entry> <entry>generate output with specified stylesheet (see below), or default.xsl if unspecified</entry></row> 3296 </tbody> 3297 </tgroup> 3298 </table> 3299 3300 <para> 3301 You may specify plain.xsl, default.xsl, fancy.xsl, fancy-hist.xsl, 3302 or your own XSL stylesheet for the -html/format option. 3303 Despite the name of this option, you may specify 3304 a stylesheet that emits something other than html. 3305 When applying a stylesheet other than those included 3306 with FindBugs (listed above), the -html/format option should be used 3307 with a path or URL to the stylesheet. 3308 </para> 3309 </sect2> 3310 3311 <sect2 id="setBugDatabaseInfo"> 3312 <title>setBugDatabaseInfo</title> 3313 3314 <para> 3315 This command sets meta-information in a specified warning collection. 3316 It takes the following options: 3317 </para> 3318 3319 <para>This functionality may also can be accessed from ant. 3320 First create a taskdef for <command>setBugDatabaseInfo</command> in your 3321 build file: 3322 </para> 3323 3324 <programlisting> 3325 <![CDATA[ 3326 <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask"> 3327 <classpath refid="findbugs.lib" /> 3328 </taskdef> 3329 ]]> 3330 </programlisting> 3331 3332 <para>Attributes for this ant task are listed in the following table. 3333 To specify an input file either use the <literal>input</literal> 3334 attribute or nest it inside the ant call with a 3335 <literal><datafile></literal> element. For example: 3336 </para> 3337 3338 <programlisting> 3339 <![CDATA[ 3340 <setBugDatabaseInfo home="${findbugs.home}" ...> 3341 <datafile name="analyze.xml"/> 3342 </setBugDatabaseInfo> 3343 ]]> 3344 </programlisting> 3345 3346 <table id="setBugDatabaseInfoOptions"> 3347 <title>setBugDatabaseInfo Options</title> 3348 <tgroup cols="3" align="left"> 3349 <thead> 3350 <row> 3351 <entry>Command-line option</entry> 3352 <entry>Ant attribute</entry> 3353 <entry>Meaning</entry> 3354 </row> 3355 </thead> 3356 <tbody> 3357 <row><entry></entry> <entry>input="<file>"</entry> <entry>use file as input</entry></row> 3358 <row><entry></entry> <entry>output="<file>"</entry> <entry>write output to file</entry></row> 3359 <row><entry>-name <name></entry> <entry>name="<name>"</entry> <entry>set name for (last) revision</entry></row> 3360 <row><entry>-timestamp <when></entry> <entry>timestamp="<when>"</entry> <entry>set timestamp for (last) revision</entry></row> 3361 <row><entry>-source <directory></entry> <entry>source="<directory>"</entry> <entry>add specified directory to the source search path</entry></row> 3362 <row><entry>-findSource <directory></entry> <entry>findSource="<directory>"</entry> <entry>find and add all relevant source directions contained within specified directory</entry></row> 3363 <row><entry>-suppress <filter file></entry> <entry>suppress="<filter file>"</entry> <entry>suppress warnings matched by this file (replaces previous suppressions)</entry></row> 3364 <row><entry>-withMessages</entry> <entry>withMessages="[true|false]"</entry> <entry>add textual messages to XML</entry></row> 3365 <row><entry>-resetSource</entry> <entry>resetSource="[true|false]"</entry> <entry>remove all source search paths</entry></row> 3366 </tbody> 3367 </tgroup> 3368 </table> 3369 </sect2> 3370 3371 <sect2 id="listBugDatabaseInfo"> 3372 <title>listBugDatabaseInfo</title> 3373 3374 <para>This command takes a list of zero or more xml bug database filenames on the command line. 3375 If zero file names are provided, it reads from standard input and does not generate 3376 a table header.</para> 3377 3378 <para>There is only one option: <option>-formatDates</option> renders dates 3379 in textual form. 3380 </para> 3381 3382 <para>The output is a table one row per bug database and the following columns:</para> 3383 <table id="listBugDatabaseInfoColumns"> 3384 <title>listBugDatabaseInfo Columns</title> 3385 <tgroup cols="2" align="left"> 3386 <thead> 3387 <row> 3388 <entry>Column</entry> 3389 <entry>Meaning</entry> 3390 </row> 3391 </thead> 3392 <tbody> 3393 <row><entry>version</entry><entry>version name</entry></row> 3394 <row><entry>time</entry><entry>Release timestamp</entry></row> 3395 <row><entry>classes</entry><entry>Number of classes analyzed</entry></row> 3396 <row><entry>NCSS</entry><entry>Non Commenting Source Statements analyzed</entry></row> 3397 <row><entry>total</entry><entry>Total number of warnings of all kinds</entry></row> 3398 <row><entry>high</entry><entry>Total number of high priority warnings of all kinds</entry></row> 3399 <row><entry>medium</entry><entry>Total number of medium/normal priority warnings of all kinds</entry></row> 3400 <row><entry>low</entry><entry>Total number of low priority warnings of all kinds</entry></row> 3401 <row><entry>filename</entry><entry>filename of database</entry></row> 3402 <!-- 3403 <row><entry></entry><entry></entry></row> 3404 <row><entry></entry><entry></entry></row> 3405 <row><entry></entry><entry></entry></row> 3406 <row><entry></entry><entry></entry></row> 3407 <row><entry></entry><entry></entry></row> 3408 <row><entry></entry><entry></entry></row> 3409 --> 3410 </tbody> 3411 </tgroup> 3412 </table> 3413 3414 </sect2> 3415 3416 </sect1> 3417 3418 <sect1 id="examples"> 3419 <title>Examples</title> 3420 <sect2 id="unixscriptsexamples"> 3421 <title>Mining history using proveded shell scrips</title> 3422 <para>In all of the following, the commands are given in a directory that contains 3423 directories jdk1.6.0-b12, jdk1.6.0-b13, ..., jdk1.6.0-b60.</para> 3424 3425 <para>You can use the command:</para> 3426 <screen> 3427 computeBugHistory jdk1.6.0-b* | filterBugs -bugPattern IL_ | mineBugHistory -formatDates 3428 </screen> 3429 <para>to generate the following output:</para> 3430 3431 <screen> 3432 seq version time classes NCSS added newCode fixed removed retained dead active 3433 0 jdk1.6.0-b12 "Thu Nov 11 09:07:20 EST 2004" 13128 811569 0 4 0 0 0 0 4 3434 1 jdk1.6.0-b13 "Thu Nov 18 06:02:06 EST 2004" 13128 811570 0 0 0 0 4 0 4 3435 2 jdk1.6.0-b14 "Thu Dec 02 06:12:26 EST 2004" 13145 811786 0 0 2 0 2 0 2 3436 3 jdk1.6.0-b15 "Thu Dec 09 06:07:04 EST 2004" 13174 811693 0 0 1 0 1 2 1 3437 4 jdk1.6.0-b16 "Thu Dec 16 06:21:28 EST 2004" 13175 811715 0 0 0 0 1 3 1 3438 5 jdk1.6.0-b17 "Thu Dec 23 06:27:22 EST 2004" 13176 811974 0 0 0 0 1 3 1 3439 6 jdk1.6.0-b19 "Thu Jan 13 06:41:16 EST 2005" 13176 812011 0 0 0 0 1 3 1 3440 7 jdk1.6.0-b21 "Thu Jan 27 05:57:52 EST 2005" 13177 812173 0 0 0 0 1 3 1 3441 8 jdk1.6.0-b23 "Thu Feb 10 05:44:36 EST 2005" 13179 812188 0 0 0 0 1 3 1 3442 9 jdk1.6.0-b26 "Thu Mar 03 06:04:02 EST 2005" 13199 811770 0 0 0 0 1 3 1 3443 10 jdk1.6.0-b27 "Thu Mar 10 04:48:38 EST 2005" 13189 812440 0 0 0 0 1 3 1 3444 11 jdk1.6.0-b28 "Thu Mar 17 02:54:22 EST 2005" 13185 812056 0 0 0 0 1 3 1 3445 12 jdk1.6.0-b29 "Thu Mar 24 03:09:20 EST 2005" 13117 809468 0 0 0 0 1 3 1 3446 13 jdk1.6.0-b30 "Thu Mar 31 02:53:32 EST 2005" 13118 809501 0 0 0 0 1 3 1 3447 14 jdk1.6.0-b31 "Thu Apr 07 03:00:14 EDT 2005" 13117 809572 0 0 0 0 1 3 1 3448 15 jdk1.6.0-b32 "Thu Apr 14 02:56:56 EDT 2005" 13169 811096 0 0 0 0 1 3 1 3449 16 jdk1.6.0-b33 "Thu Apr 21 02:46:22 EDT 2005" 13187 811942 0 0 0 0 1 3 1 3450 17 jdk1.6.0-b34 "Thu Apr 28 02:49:00 EDT 2005" 13195 813488 0 1 0 0 1 3 2 3451 18 jdk1.6.0-b35 "Thu May 05 02:49:04 EDT 2005" 13457 829837 0 0 0 0 2 3 2 3452 19 jdk1.6.0-b36 "Thu May 12 02:59:46 EDT 2005" 13462 831278 0 0 0 0 2 3 2 3453 20 jdk1.6.0-b37 "Thu May 19 02:55:08 EDT 2005" 13464 831971 0 0 0 0 2 3 2 3454 21 jdk1.6.0-b38 "Thu May 26 03:08:16 EDT 2005" 13564 836565 0 0 0 0 2 3 2 3455 22 jdk1.6.0-b39 "Fri Jun 03 03:10:48 EDT 2005" 13856 849992 0 1 0 0 2 3 3 3456 23 jdk1.6.0-b40 "Thu Jun 09 03:30:28 EDT 2005" 15972 959619 0 2 0 0 3 3 5 3457 24 jdk1.6.0-b41 "Thu Jun 16 03:19:22 EDT 2005" 15972 959619 0 0 0 0 5 3 5 3458 25 jdk1.6.0-b42 "Fri Jun 24 03:38:54 EDT 2005" 15966 958581 0 0 0 0 5 3 5 3459 26 jdk1.6.0-b43 "Thu Jul 14 03:09:34 EDT 2005" 16041 960544 0 0 0 0 5 3 5 3460 27 jdk1.6.0-b44 "Thu Jul 21 03:05:54 EDT 2005" 16041 960547 0 0 0 0 5 3 5 3461 28 jdk1.6.0-b45 "Thu Jul 28 03:26:10 EDT 2005" 16037 960606 0 0 1 0 4 3 4 3462 29 jdk1.6.0-b46 "Thu Aug 04 03:02:48 EDT 2005" 15936 951355 0 0 0 0 4 4 4 3463 30 jdk1.6.0-b47 "Thu Aug 11 03:18:56 EDT 2005" 15964 952387 0 0 1 0 3 4 3 3464 31 jdk1.6.0-b48 "Thu Aug 18 08:10:40 EDT 2005" 15970 953421 0 0 0 0 3 5 3 3465 32 jdk1.6.0-b49 "Thu Aug 25 03:24:38 EDT 2005" 16048 958940 0 0 0 0 3 5 3 3466 33 jdk1.6.0-b50 "Thu Sep 01 01:52:40 EDT 2005" 16287 974937 1 0 0 0 3 5 4 3467 34 jdk1.6.0-b51 "Thu Sep 08 01:55:36 EDT 2005" 16362 979377 0 0 0 0 4 5 4 3468 35 jdk1.6.0-b52 "Thu Sep 15 02:04:08 EDT 2005" 16477 979399 0 0 0 0 4 5 4 3469 36 jdk1.6.0-b53 "Thu Sep 22 02:00:28 EDT 2005" 16019 957900 0 0 1 0 3 5 3 3470 37 jdk1.6.0-b54 "Thu Sep 29 01:54:34 EDT 2005" 16019 957900 0 0 0 0 3 6 3 3471 38 jdk1.6.0-b55 "Thu Oct 06 01:54:14 EDT 2005" 16051 959014 0 0 0 0 3 6 3 3472 39 jdk1.6.0-b56 "Thu Oct 13 01:54:12 EDT 2005" 16211 970835 0 0 0 0 3 6 3 3473 40 jdk1.6.0-b57 "Thu Oct 20 01:55:26 EDT 2005" 16279 971627 0 0 0 0 3 6 3 3474 41 jdk1.6.0-b58 "Thu Oct 27 01:56:30 EDT 2005" 16283 971945 0 0 0 0 3 6 3 3475 42 jdk1.6.0-b59 "Thu Nov 03 01:56:58 EST 2005" 16232 972193 0 0 0 0 3 6 3 3476 43 jdk1.6.0-b60 "Thu Nov 10 01:54:18 EST 2005" 16235 972346 0 0 0 0 3 6 3 3477 </screen> 3478 3479 <para> 3480 We could also generate that information directly, without creating an intermediate db.xml file, using the command 3481 </para> 3482 3483 <screen> 3484 computeBugHistory jdk1.6.0-b*/jre/lib/rt.xml | filterBugs -bugPattern IL_ db.xml | mineBugHistory -formatDates 3485 </screen> 3486 3487 <para>We can then use that information to display a graph showing the number of infinite recursive loops 3488 found by FindBugs in each build of Sun's JDK1.6.0. The blue area indicates the number of infinite 3489 recursive loops in that build, the red area above it indicates the number of infinite recursive loops that existed 3490 in some previous version but not in the current version (thus, the combined height of the red and blue areas 3491 is guaranteed to never decrease, and goes up whenever a new infinite recursive loop bug is introduced). The height 3492 of the red area is computed as the sum of the fixed, removed and dead values for each version. 3493 The reductions in builds 13 and 14 came after Sun was notified about the bugs found by FindBugs in the JDK. 3494 </para> 3495 <mediaobject> 3496 <imageobject> 3497 <imagedata fileref="infiniteRecursiveLoops.png" /> 3498 </imageobject> 3499 </mediaobject> 3500 3501 <para> 3502 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: 3503 </para> 3504 3505 <screen> 3506 filterBugs -priority M -category C db.xml | mineBugHistory -formatDates 3507 </screen> 3508 3509 <para> 3510 generating the table: 3511 </para> 3512 3513 <screen> 3514 seq version time classes NCSS added newCode fixed removed retained dead active 3515 0 jdk1.6.0-b12 "Thu Nov 11 09:07:20 EST 2004" 13128 811569 0 1075 0 0 0 0 1075 3516 1 jdk1.6.0-b13 "Thu Nov 18 06:02:06 EST 2004" 13128 811570 0 0 0 0 1075 0 1075 3517 2 jdk1.6.0-b14 "Thu Dec 02 06:12:26 EST 2004" 13145 811786 3 0 6 0 1069 0 1072 3518 3 jdk1.6.0-b15 "Thu Dec 09 06:07:04 EST 2004" 13174 811693 2 1 3 0 1069 6 1072 3519 4 jdk1.6.0-b16 "Thu Dec 16 06:21:28 EST 2004" 13175 811715 0 0 1 0 1071 9 1071 3520 5 jdk1.6.0-b17 "Thu Dec 23 06:27:22 EST 2004" 13176 811974 0 0 1 0 1070 10 1070 3521 6 jdk1.6.0-b19 "Thu Jan 13 06:41:16 EST 2005" 13176 812011 0 0 0 0 1070 11 1070 3522 7 jdk1.6.0-b21 "Thu Jan 27 05:57:52 EST 2005" 13177 812173 0 0 1 0 1069 11 1069 3523 8 jdk1.6.0-b23 "Thu Feb 10 05:44:36 EST 2005" 13179 812188 0 0 0 0 1069 12 1069 3524 9 jdk1.6.0-b26 "Thu Mar 03 06:04:02 EST 2005" 13199 811770 0 0 2 1 1066 12 1066 3525 10 jdk1.6.0-b27 "Thu Mar 10 04:48:38 EST 2005" 13189 812440 1 0 1 1 1064 15 1065 3526 11 jdk1.6.0-b28 "Thu Mar 17 02:54:22 EST 2005" 13185 812056 0 0 0 0 1065 17 1065 3527 12 jdk1.6.0-b29 "Thu Mar 24 03:09:20 EST 2005" 13117 809468 3 0 8 26 1031 17 1034 3528 13 jdk1.6.0-b30 "Thu Mar 31 02:53:32 EST 2005" 13118 809501 0 0 0 0 1034 51 1034 3529 14 jdk1.6.0-b31 "Thu Apr 07 03:00:14 EDT 2005" 13117 809572 0 0 0 0 1034 51 1034 3530 15 jdk1.6.0-b32 "Thu Apr 14 02:56:56 EDT 2005" 13169 811096 1 1 0 1 1033 51 1035 3531 16 jdk1.6.0-b33 "Thu Apr 21 02:46:22 EDT 2005" 13187 811942 3 0 2 1 1032 52 1035 3532 17 jdk1.6.0-b34 "Thu Apr 28 02:49:00 EDT 2005" 13195 813488 0 1 0 0 1035 55 1036 3533 18 jdk1.6.0-b35 "Thu May 05 02:49:04 EDT 2005" 13457 829837 0 36 2 0 1034 55 1070 3534 19 jdk1.6.0-b36 "Thu May 12 02:59:46 EDT 2005" 13462 831278 0 0 0 0 1070 57 1070 3535 20 jdk1.6.0-b37 "Thu May 19 02:55:08 EDT 2005" 13464 831971 0 1 1 0 1069 57 1070 3536 21 jdk1.6.0-b38 "Thu May 26 03:08:16 EDT 2005" 13564 836565 1 7 2 6 1062 58 1070 3537 22 jdk1.6.0-b39 "Fri Jun 03 03:10:48 EDT 2005" 13856 849992 6 39 5 0 1065 66 1110 3538 23 jdk1.6.0-b40 "Thu Jun 09 03:30:28 EDT 2005" 15972 959619 7 147 11 0 1099 71 1253 3539 24 jdk1.6.0-b41 "Thu Jun 16 03:19:22 EDT 2005" 15972 959619 0 0 0 0 1253 82 1253 3540 25 jdk1.6.0-b42 "Fri Jun 24 03:38:54 EDT 2005" 15966 958581 3 0 1 2 1250 82 1253 3541 26 jdk1.6.0-b43 "Thu Jul 14 03:09:34 EDT 2005" 16041 960544 5 11 15 8 1230 85 1246 3542 27 jdk1.6.0-b44 "Thu Jul 21 03:05:54 EDT 2005" 16041 960547 0 0 0 0 1246 108 1246 3543 28 jdk1.6.0-b45 "Thu Jul 28 03:26:10 EDT 2005" 16037 960606 19 0 2 0 1244 108 1263 3544 29 jdk1.6.0-b46 "Thu Aug 04 03:02:48 EDT 2005" 15936 951355 13 1 1 32 1230 110 1244 3545 30 jdk1.6.0-b47 "Thu Aug 11 03:18:56 EDT 2005" 15964 952387 163 8 7 20 1217 143 1388 3546 31 jdk1.6.0-b48 "Thu Aug 18 08:10:40 EDT 2005" 15970 953421 0 0 0 0 1388 170 1388 3547 32 jdk1.6.0-b49 "Thu Aug 25 03:24:38 EDT 2005" 16048 958940 1 11 1 0 1387 170 1399 3548 33 jdk1.6.0-b50 "Thu Sep 01 01:52:40 EDT 2005" 16287 974937 19 27 16 7 1376 171 1422 3549 34 jdk1.6.0-b51 "Thu Sep 08 01:55:36 EDT 2005" 16362 979377 1 15 3 0 1419 194 1435 3550 35 jdk1.6.0-b52 "Thu Sep 15 02:04:08 EDT 2005" 16477 979399 0 0 1 1 1433 197 1433 3551 36 jdk1.6.0-b53 "Thu Sep 22 02:00:28 EDT 2005" 16019 957900 13 12 16 20 1397 199 1422 3552 37 jdk1.6.0-b54 "Thu Sep 29 01:54:34 EDT 2005" 16019 957900 0 0 0 0 1422 235 1422 3553 38 jdk1.6.0-b55 "Thu Oct 06 01:54:14 EDT 2005" 16051 959014 1 4 7 0 1415 235 1420 3554 39 jdk1.6.0-b56 "Thu Oct 13 01:54:12 EDT 2005" 16211 970835 6 8 37 0 1383 242 1397 3555 40 jdk1.6.0-b57 "Thu Oct 20 01:55:26 EDT 2005" 16279 971627 0 0 0 0 1397 279 1397 3556 41 jdk1.6.0-b58 "Thu Oct 27 01:56:30 EDT 2005" 16283 971945 0 1 1 0 1396 279 1397 3557 42 jdk1.6.0-b59 "Thu Nov 03 01:56:58 EST 2005" 16232 972193 6 0 5 0 1392 280 1398 3558 43 jdk1.6.0-b60 "Thu Nov 10 01:54:18 EST 2005" 16235 972346 0 0 0 0 1398 285 1398 3559 44 jdk1.6.0-b61 "Thu Nov 17 01:58:42 EST 2005" 16202 971134 2 0 4 0 1394 285 1396 3560 </screen> 3561 </sect2> 3562 3563 <sect2 id="incrementalhistory"> 3564 <title>Incremental history maintenance</title> 3565 3566 <para> 3567 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: 3568 </para> 3569 <screen> 3570 computeBugHistory -output db.xml db.xml jdk1.6.0-b61/jre/lib/rt.xml 3571 </screen> 3572 </sect2> 3573 3574 </sect1> 3575 3576 <sect1 id="antexample"> 3577 <title>Ant example</title> 3578 <para> 3579 Here is a complete ant script example for both running findbugs and running a chain of data-mining tools afterward: 3580 </para> 3581 <screen> 3582 <![CDATA[ 3583 <project name="analyze_asm_util" default="findbugs"> 3584 <!-- findbugs task definition --> 3585 <property name="findbugs.home" value="/Users/ben/Documents/workspace/findbugs/findbugs" /> 3586 <property name="jvmargs" value="-server -Xss1m -Xmx800m -Duser.language=en -Duser.region=EN -Dfindbugs.home=${findbugs.home}" /> 3587 3588 <path id="findbugs.lib"> 3589 <fileset dir="${findbugs.home}/lib"> 3590 <include name="findbugs-ant.jar"/> 3591 </fileset> 3592 </path> 3593 3594 <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"> 3595 <classpath refid="findbugs.lib" /> 3596 </taskdef> 3597 3598 <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask"> 3599 <classpath refid="findbugs.lib" /> 3600 </taskdef> 3601 3602 <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask"> 3603 <classpath refid="findbugs.lib" /> 3604 </taskdef> 3605 3606 <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask"> 3607 <classpath refid="findbugs.lib" /> 3608 </taskdef> 3609 3610 <!-- findbugs task definition --> 3611 <target name="findbugs"> 3612 <antcall target="analyze" /> 3613 <antcall target="mine" /> 3614 </target> 3615 3616 <!-- analyze task --> 3617 <target name="analyze"> 3618 <!-- run findbugs against asm-util --> 3619 <findbugs home="${findbugs.home}" 3620 output="xml:withMessages" 3621 timeout="90000000" 3622 reportLevel="experimental" 3623 workHard="true" 3624 effort="max" 3625 adjustExperimental="true" 3626 jvmargs="${jvmargs}" 3627 failOnError="true" 3628 outputFile="out.xml" 3629 projectName="Findbugs" 3630 debug="false"> 3631 <class location="asm-util-3.0.jar" /> 3632 </findbugs> 3633 </target> 3634 3635 <target name="mine"> 3636 3637 <!-- Set info to the latest analysis --> 3638 <setBugDatabaseInfo home="${findbugs.home}" 3639 withMessages="true" 3640 name="asm-util-3.0.jar" 3641 input="out.xml" 3642 output="out-rel.xml"/> 3643 3644 <!-- Checking if history file already exists (out-hist.xml) --> 3645 <condition property="mining.historyfile.available"> 3646 <available file="out-hist.xml"/> 3647 </condition> 3648 <condition property="mining.historyfile.notavailable"> 3649 <not> 3650 <available file="out-hist.xml"/> 3651 </not> 3652 </condition> 3653 3654 <!-- this target is executed if the history file do not exist (first run) --> 3655 <antcall target="history-init"> 3656 <param name="data.file" value="out-rel.xml" /> 3657 <param name="hist.file" value="out-hist.xml" /> 3658 </antcall> 3659 <!-- else this one is executed --> 3660 <antcall target="history"> 3661 <param name="data.file" value="out-rel.xml" /> 3662 <param name="hist.file" value="out-hist.xml" /> 3663 <param name="hist.summary.file" value="out-hist.txt" /> 3664 </antcall> 3665 </target> 3666 3667 <!-- Initializing history file --> 3668 <target name="history-init" if="mining.historyfile.notavailable"> 3669 <copy file="${data.file}" tofile="${hist.file}" /> 3670 </target> 3671 3672 <!-- Computing bug history --> 3673 <target name="history" if="mining.historyfile.available"> 3674 <!-- Merging ${data.file} into ${hist.file} --> 3675 <computeBugHistory home="${findbugs.home}" 3676 withMessages="true" 3677 output="${hist.file}"> 3678 <dataFile name="${hist.file}"/> 3679 <dataFile name="${data.file}"/> 3680 </computeBugHistory> 3681 3682 <!-- Compute history into ${hist.summary.file} --> 3683 <mineBugHistory home="${findbugs.home}" 3684 formatDates="true" 3685 noTabs="true" 3686 input="${hist.file}" 3687 output="${hist.summary.file}"/> 3688 </target> 3689 3690 </project> 3691 ]]> 3692 </screen> 3693 </sect1> 3694 </chapter> 3695 3696 3697 <!-- 3698 ************************************************************************** 3699 License 3700 ************************************************************************** 3701 --> 3702 3703 <chapter id="license"> 3704 <title>License</title> 3705 3706 <para> 3707 The name FindBugs and the FindBugs logo is trademarked by the University 3708 of Maryland. 3709 FindBugs is free software distributed under the terms of the 3710 <ulink url="http://www.gnu.org/licenses/lgpl.html">Lesser GNU Public License</ulink>. 3711 You should have received a copy of the license in the file <filename>LICENSE.txt</filename> 3712 in the &FindBugs; distribution. 3713 </para> 3714 3715 <para> 3716 You can find the latest version of FindBugs, along with its source code, from the 3717 <ulink url="http://findbugs.sourceforge.net">FindBugs web page</ulink>. 3718 </para> 3719 3720 </chapter> 3721 3722 3723 <!-- 3724 ************************************************************************** 3725 Acknowledgments 3726 ************************************************************************** 3727 --> 3728 <chapter id="acknowledgments"> 3729 <title>Acknowledgments</title> 3730 3731 <sect1> 3732 <title>Contributors</title> 3733 3734 <para>&FindBugs; was originally written by Bill Pugh (<email>pugh (a] cs.umd.edu</email>). 3735 David Hovemeyer (<email>daveho (a] cs.umd.edu</email>) implemented some of the 3736 detectors, added the Swing GUI, and is a co-maintainer.</para> 3737 3738 <para>Mike Fagan (<email>mfagan (a] tde.com</email>) contributed the &Ant; build script, 3739 the &Ant; task, and several enhancements and bug fixes to the GUI.</para> 3740 3741 <para>Germano Leichsenring contributed Japanese translations of the bug 3742 summaries.</para> 3743 3744 <para>David Li contributed the Emacs bug report format.</para> 3745 3746 <para>Peter D. Stout contributed recursive detection of Class-Path 3747 attributes in analyzed Jar files, German translations of 3748 text used in the Swing GUI, and other fixes.</para> 3749 3750 <para>Peter Friese wrote the &FindBugs; Eclipse plugin.</para> 3751 3752 <para>Rohan Lloyd contributed several Mac OS X enhancements, 3753 bug detector improvements, 3754 and maintains the Fink package for &FindBugs;.</para> 3755 3756 <para>Hiroshi Okugawa translated the &FindBugs; manual and 3757 more of the bug summaries into Japanese.</para> 3758 3759 <para>Phil Crosby enhanced the Eclipse plugin to add a view 3760 to display the bug details.</para> 3761 3762 <para>Dave Brosius fixed a number of bugs, added user preferences 3763 to the Swing GUI, improved several bug detectors, and 3764 contributed the string concatenation detector.</para> 3765 3766 <para>Thomas Klaeger contributed a number of bug fixes and 3767 bug detector improvements.</para> 3768 3769 <para>Andrei Loskutov made a number of improvements to the 3770 Eclipse plugin.</para> 3771 3772 <para>Brian Goetz contributed a major refactoring of the 3773 visitor classes to improve readability and understandability.</para> 3774 3775 <para> Pete Angstadt fixed several problems in the Swing GUI.</para> 3776 3777 <para>Francis Lalonde provided a task resource file for the 3778 FindBugs Ant task.</para> 3779 3780 <para>Garvin LeClaire contributed support for output in 3781 Xdocs format, for use by Maven.</para> 3782 3783 <para>Holger Stenzhorn contributed improved German translations of items 3784 in the Swing GUI.</para> 3785 3786 <para>Juha Knuutila contributed Finnish translations of items 3787 in the Swing GUI.</para> 3788 3789 <para>Tanel Lebedev contributed Estonian translations of items 3790 in the Swing GUI.</para> 3791 3792 <para>Hanai Shisei (ruimo) contributed full Japanese translations of 3793 bug messages, and text used in the Swing GUI.</para> 3794 3795 <para>David Cotton contributed Fresh translations for bug 3796 messages and for the Swing GUI.</para> 3797 3798 <para>Michael Tamm contributed support for the "errorProperty" attribute 3799 in the Ant task.</para> 3800 3801 <para>Thomas Kuehne improved the German translation of the Swing GUI.</para> 3802 3803 <para>Len Trigg improved source file support for the Emacs output mode.</para> 3804 3805 <para>Greg Bentz provided a fix for the hashcode/equals detector.</para> 3806 3807 <para>K. Hashimoto contributed internationalization fixes and several other 3808 bug fixes.</para> 3809 3810 <para> 3811 Glenn Boysko contributed support for ignoring specified local 3812 variables in the dead local store detector. 3813 </para> 3814 3815 <para> 3816 Jay Dunning contributed a detector to find equality comparisons 3817 of floating-point values, and overhauled the analysis summary 3818 report and its representation in the saved XML format. 3819 </para> 3820 3821 <para> 3822 Olivier Parent contributed updated French translations for bug descriptions and 3823 Swing GUI. 3824 </para> 3825 3826 <para> 3827 Chris Nappin contributed the <filename>plain.xsl</filename> 3828 stylesheet. 3829 </para> 3830 3831 <para> 3832 Etienne Giraudy contributed the <filename>fancy.xsl</filename> and <filename>fancy-hist.xsl</filename> 3833 stylesheets, and made improvements to the <command>-xml:withMessages</command> 3834 option. 3835 </para> 3836 3837 <para> 3838 Takashi Okamoto fixed bugs in the project preferences dialog 3839 in the Eclipse plugin, and contributed to its internationalization and localization. 3840 </para> 3841 3842 <para>Thomas Einwaller fixed bugs in the project preferences dialog in the Eclipse plugin.</para> 3843 3844 <para>Jeff Knox contributed support for the warningsProperty attribute 3845 in the Ant task.</para> 3846 3847 <para>Peter Hendriks extended the Eclipse plugin preferences, 3848 and fixed a bug related to renaming the Eclipse plugin ID.</para> 3849 3850 <para>Mark McKay contributed an Ant task to launch the findbugs frame.</para> 3851 3852 <para>Dieter von Holten (dvholten) contributed 3853 some German improvements to findbugs_de.properties.</para> 3854 3855 3856 <para>If you have contributed to &FindBugs;, but aren't mentioned above, 3857 please send email to <email>findbugs (a] cs.umd.edu</email> (and also accept 3858 our humble apologies).</para> 3859 3860 </sect1> 3861 3862 <sect1> 3863 <title>Software Used</title> 3864 3865 <para>&FindBugs; uses several open-source software packages, without which its 3866 development would have been much more difficult.</para> 3867 3868 <sect2> 3869 <title>BCEL</title> 3870 <para>&FindBugs; includes software developed by the Apache Software Foundation 3871 (<ulink url="http://www.apache.org/">http://www.apache.org/</ulink>). 3872 Specifically, it uses the <ulink url="http://jakarta.apache.org/bcel/">Byte Code 3873 Engineering Library</ulink>.</para> 3874 </sect2> 3875 3876 <sect2> 3877 <title>ASM</title> 3878 <para>&FindBugs; uses the <ulink url="http://asm.objectweb.org/">ASM</ulink> 3879 bytecode framework, which is distributed under the following license:</para> 3880 3881 <blockquote> 3882 <para> 3883 Copyright (c) 2000-2005 INRIA, France Telecom 3884 All rights reserved. 3885 </para> 3886 3887 <para> 3888 Redistribution and use in source and binary forms, with or without 3889 modification, are permitted provided that the following conditions 3890 are met: 3891 </para> 3892 3893 <orderedlist numeration="arabic"> 3894 <listitem><para> 3895 Redistributions of source code must retain the above copyright 3896 notice, this list of conditions and the following disclaimer. 3897 </para></listitem> 3898 <listitem><para> 3899 Redistributions in binary form must reproduce the above copyright 3900 notice, this list of conditions and the following disclaimer in the 3901 documentation and/or other materials provided with the distribution. 3902 </para></listitem> 3903 <listitem><para> 3904 Neither the name of the copyright holders nor the names of its 3905 contributors may be used to endorse or promote products derived from 3906 this software without specific prior written permission. 3907 </para></listitem> 3908 </orderedlist> 3909 3910 <para> 3911 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 3912 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 3913 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 3914 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 3915 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 3916 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 3917 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 3918 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 3919 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 3920 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 3921 THE POSSIBILITY OF SUCH DAMAGE. 3922 </para> 3923 </blockquote> 3924 </sect2> 3925 3926 <sect2> 3927 <title>DOM4J</title> 3928 <para>&FindBugs; uses <ulink url="http://dom4j.org">DOM4J</ulink>, which is 3929 distributed under the following license:</para> 3930 3931 <blockquote> 3932 <para> 3933 Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved. 3934 </para> 3935 3936 <para> 3937 Redistribution and use of this software and associated documentation 3938 ("Software"), with or without modification, are permitted provided that 3939 the following conditions are met: 3940 </para> 3941 3942 <orderedlist numeration="arabic"> 3943 <listitem><para> 3944 Redistributions of source code must retain copyright statements and 3945 notices. Redistributions must also contain a copy of this document. 3946 </para></listitem> 3947 <listitem><para> 3948 Redistributions in binary form must reproduce the above copyright 3949 notice, this list of conditions and the following disclaimer in the 3950 documentation and/or other materials provided with the distribution. 3951 </para></listitem> 3952 <listitem><para> 3953 The name "DOM4J" must not be used to endorse or promote products 3954 derived from this Software without prior written permission 3955 of MetaStuff, Ltd. For written permission, please contact 3956 <email>dom4j-info (a] metastuff.com</email>. 3957 </para></listitem> 3958 <listitem><para> 3959 Products derived from this Software may not be called "DOM4J" nor may 3960 "DOM4J" appear in their names without prior written permission of 3961 MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd. 3962 </para></listitem> 3963 <listitem><para> 3964 Due credit should be given to the DOM4J Project (<ulink url="http://dom4j.org/">http://dom4j.org/</ulink>). 3965 </para></listitem> 3966 </orderedlist> 3967 3968 <para> 3969 THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' 3970 AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 3971 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 3972 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS 3973 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 3974 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 3975 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 3976 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 3977 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 3978 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 3979 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3980 </para> 3981 </blockquote> 3982 3983 </sect2> 3984 3985 </sect1> 3986 3987 </chapter> 3988 3989 3990 </book> 3991
