| Adding Detectors to FindBugs |
| May 12, 2003 |
| Updated June 6, 2003 (detector meta-information, cleanups) |
| |
| =============== |
| 1. Introduction |
| =============== |
| |
| FindBugs uses a plugin-based approach to adding detectors. |
| This makes it easy for users to add their own detectors alongside |
| the ones that come built in. |
| |
| Basic idea: FindBugs has some Jar files in a "plugins" directory. |
| At startup, each of those jar files is checked for a "findbugs.xml" |
| file. That XML file registers instances of Detectors, as well |
| as particular "bug patterns" that the detector reports. |
| |
| Additionally to the findbugs.xml, bugrank.txt and messages.xml files are |
| required for each FindBugs detector plugin. |
| |
| At startup, FindBugs loads all plugin Jar files. At analysis time, |
| all detectors named in the findbugs.xml files from those plugins |
| are instantiated and applied to analyzed class files. |
| |
| In order to format reported BugInstances as text for display, |
| a messages file is loaded from the plugin. In order to support multiple |
| language translations, a locale search is performed in a manner |
| similar to the handling of resource bundles. For example, if the |
| locale is "pt_BR", then the files |
| |
| messages_pt_BR.xml |
| messages_pt.xml |
| messages.xml |
| |
| are tried, in that order. |
| |
| The "findbugs.xml" and "messages.xml" files used by the standard FindBugs |
| bug pattern detectors (coreplugin.jar) can be found in the "etc" directory |
| of the findbugs source distribution. Both files must be UTF-8 encoded. |
| |
| |
| ============================ |
| 2. Example findbugs.xml file |
| ============================ |
| |
| <DetectorPlugin> |
| |
| <Detector class="org.foobar.findbugs.FindUnreleasedLocks" speed="slow" /> |
| <Detector class="org.foobar.findbugs.ExperimentalDetector" speed="fast" disabled="true" /> |
| |
| <!-- More Detector elements would go here... --> |
| |
| <BugPattern type="UBL_UNRELEASED_LOCK" abbrev="UL" category="MT_CORRECTNESS" /> |
| |
| <!-- More BugPattern elements would go here... --> |
| |
| </DetectorPlugin> |
| |
| |
| ====================================== |
| 3. Meaning of elements in findbugs.xml |
| ====================================== |
| |
| <DetectorPlugin> a collection of <Detector> and <BugPattern> elements. |
| Each plugin Jar file can (and usually will) provide multiple detectors |
| and define multiple bug patterns. |
| |
| <Detector> specifies a class which implements the edu.umd.cs.findbugs.Detector |
| interface and has a constructor that takes a single parameter of type |
| edu.umd.cs.findbugs.BugReporter. This element has three possible attributes: |
| |
| 1. The required "class" attribute specifies the Detector class. |
| |
| 2. The optional "disabled" attribute, if set to "true", means |
| that by default, the detector will be disabled at runtime. |
| This is useful for detectors that aren't quite ready for prime time. |
| |
| 3. The required "speed" attribute supplies a value to be shown in the |
| "Settings->Configure Detectors" dialog. It gives the user an idea of |
| how expensive the analysis will be to perform. The value of this |
| attribute should be one of "fast", "moderate", or "slow". |
| |
| <BugPattern> specifies a kind of bug that will be reported. |
| It has three required attributes: |
| |
| 1. "type" is a unique code identifying the bug. Only one BugPattern |
| can have a a particular type. |
| |
| 2. "abbrev" is a short alphanumeric code for the bug. |
| Note that multiple BugPatterns can use the same abbreviation |
| if they are related. (See the BugCode element in messages.xml). |
| |
| 3. "category" can be one of categories defined in the core plugin's messages.xml: |
| |
| CORRECTNESS - code that was probably not what the developer intended |
| BAD_PRACTICE - violations of recommended and essential coding practice |
| STYLE - code that is confusing, anomalous, or written in a way that that leads itself to errors |
| MT_CORRECTNESS - multithreaded correctness issues |
| MALICIOUS_CODE - a potential vulnerability if exposed to malicious code |
| PERFORMANCE - a performance issue |
| I18N - internationalization and locale |
| |
| or you may create your own category, in which case you should define |
| it in a <BugCategory> element in _your_ messages.xml file. |
| |
| ============================ |
| 4. Example messages.xml file |
| ============================ |
| |
| <MessageCollection> |
| |
| <Detector class="org.foobar.findbugs.FindUnreleasedLocks" > |
| <Details> |
| <![CDATA[ |
| <p> This detector looks for JSR-166 locks that are not released on all paths |
| out of a method. Because it performs dataflow analysis, it is fairly slow. |
| ]]> |
| </Details> |
| </Detector> |
| |
| <!-- More Detector nodes would go here... --> |
| |
| <BugPattern type="UBL_UNRELEASED_LOCK"> |
| <ShortDescription>Lock not released on all paths out of method</ShortDescription> |
| |
| <LongDescription>{1} does not release lock on all paths out of method</LongDescription> |
| |
| <Details> |
| <![CDATA[ |
| <p> A JSR-166 lock acquired in this method is not released on all paths |
| out of the method. This could result in a deadlock if another thread |
| tries to acquire the lock. Generally, you should use a finally |
| block to ensure that acquired locks are always released. |
| ]]> |
| </Details> |
| </BugPattern> |
| |
| <!-- More BugPattern nodes would go here... --> |
| |
| <BugCode abbrev="UL">Unreleased locks</BugCode> |
| |
| <!-- More BugCode nodes would go here... --> |
| |
| </MessageCollection> |
| |
| |
| ====================================== |
| 5. Meaning of elements in messages.xml |
| ====================================== |
| |
| <MessageCollection> is the top level element |
| |
| <BugCategory> elements optionally describe any categories you |
| may have created for your bug patterns. You can skip these if |
| you are using only the categories defined by the core plugin. |
| |
| The <Description> child element has a brief (a word or three) |
| description of the category. The <Abbreviation> child element |
| is typically a single capital latter. The optional <Details> |
| child element may describe it in more detail (but no markup). |
| |
| <Detector> holds meta-information about a Detector in the plugin. |
| The required "class" attribute specifies the Detector class. |
| Detector elements much have the following child elements: |
| |
| The <Details> child element has a brief HTML description of the Detector. |
| It should have HTML markup that would be valid in a BODY element. |
| It should be specified in a CDATA section so that the HTML |
| tags are not misinterpreted as XML. |
| |
| <BugPattern> holds all of the human-readable messages for the bug pattern |
| identified by the "type" attribute. The type corresponds to the |
| type attribute of the BugPattern elements described in findbugs.xml. |
| BugPattern elements must have the following child elements: |
| |
| <ShortDescription> this is used for when "View->Full Descriptions" |
| is turned off in the GUI, and it's also used as the title for |
| descriptions in the Details window. |
| |
| <LongDescription> this is used for when "View->Full Descriptions" |
| is turned on in the GUI, and for output using the command line UI. |
| The placeholders in the long description ({0}, {1}, etc.) |
| refer to BugAnnotations attached to the BugInstances reported by |
| the detector for this bug pattern. You may also use constructs |
| like {1.name} or {1.returnType}. |
| |
| <Details> this is the descriptive text to be used in the Details |
| window. It consists of HTML markup to appear in the BODY element of an HTML |
| document. It should be specified in a CDATA section so that the HTML |
| tags are not misinterpreted as XML. |
| |
| <BugCode> is the text which describes the common characteristic of all |
| of the BugPatterns which share an abbreviation. In the example above, |
| the abbreviation "UL" is for bugs in which a lock is not released. |
| The text of a BugCode element is shown for tree nodes in the GUI |
| which group bug instances by "bug type". |
| |
| ====================================== |
| 6. Meaning of elements in bugrank.txt |
| ====================================== |
| |
| For the detailed and up to date information, please read the javadoc of the |
| edu.umd.cs.findbugs.BugRanker class. |
| |
| ============================================ |
| 7. Using 3rd party libraries in the detector |
| ============================================ |
| |
| FindBugs plugins may extend the default FindBugs classpath and use custom 3rd party |
| libraries during the analysis. This libraries must be part of standard jar class path |
| specified via "ClassPath" attribute in the META-INF/MANIFEST.MF file. |
| |
| ====================================== |
| 8. Adding detectors to Eclipse plugin |
| ====================================== |
| |
| Since version 2.0.0 Eclipse plugin allows to configure or contribute custom detectors. |
| |
| 7.1. It is possible to contribute custom detectors via standard Eclipse extensions mechanism. |
| Please check the documentation of the "findBugsEclipsePlugin/schema/detectorPlugins.exsd" |
| extension point how to update the plugin.xml. Existing FindBugs detector plugins can |
| be easily "extended" to be full featured FindBugs & Eclipse detector plugins. |
| Usually you only need to add META-INF/MANIFEST.MF and plugin.xml to the jar and |
| update your build scripts to not to override the MANIFEST.MF during the build. |
| |
| 7.2 It is possible to configure custom detectors via Eclipse workspace preferences. |
| Go to "Window->Preferences->Java->FindBugs->Misc. Settings->Custom Detectors" |
| and specify there locations of any additional plugin libraries. |
| |
| 7.3 Plugins contributed via standard Eclipse extensions mechanism (see 7.1) |
| may extend the default FindBugs classpath and use custom libraries during the analysis. |
| This libraries must be part of standard Eclipse plugin dependencies specified via |
| either "Require-Bundle" or "Bundle-ClassPath" attributes in the MANIFEST.MF file. |
| In case custom detectors need access to this custom libraries at runtime, an |
| extra line must be added to the MANIFEST.MF (without quotation marks): |
| "Eclipse-RegisterBuddy: edu.umd.cs.findbugs.plugin.eclipse". |
| |