14.4. RFRS Considerations

The "Build" section of the RFRS Requirements includes six itemsthree requirements and three best practicesdealing with builders.

14.4.1. Use builders to convert resources (RFRS 3.8.1)

Requirement #1 states:

Any extension that converts resources from one format into another where the resources are synchronized, such as compilers, must use the build APIs and org.eclipse.core.resources.builders extension point.

To pass this requirement, start by showing your builder in action. Describe how it is invoked and what resources it transforms. Turn off the Build automatically preference on the General > Workspace preference page and show that your builder does not run. Invoke the Project > Rebuild Project command to show that your builder correctly processes any accumulated changes.

14.4.2. Do not replace existing builders (RFRS 3.8.3)

Requirement #2 states:

Extensions cannot replace the builders associated with project natures provided by the workbench, or by other vendors.

Start by configuring a project to use your builder. Open the project's .project file to show that your builder has been added and that none of the existing builders, such as org.eclipse.jdt.core.javabuilder, have been removed.

14.4.3. Do not misuse the term "build" (RFRS 5.3.8.1)

Best Practice #3 states:

The term "build" should not be overloaded to have a meaning other than build processing triggered using the Eclipse build APIs. That is, do not use the term "build" in your product implementation or documentation to describe a process that is not implemented as a builder in the workbench.

Show any places in your product documentation where the term "build" is used and confirm that any such uses are related to your plug-in's builders.

14.4.4. Mark created resources as "derived" (RFRS 5.3.8.2)

Best Practice #4 states:

Resources created by builders should be identified as derived when they are not source (as in .java), or some other type of artifact that can be or will be modified by the user, or are required for deployment to a runtime platform.

For this test, demonstrate that any resources created by your builder are marked as derived. In the case of a .class file created by the Java compiler, you would open the Properties dialog and show that the Derived option has been checked (see Figure 14-14).

Figure 14-14. The Properties dialog for the HelloWorld.class file.

[View full size image]

14.4.5. Respond to clean-build requests (RFRS 5.3.8.3)

Best Practice #5 states:

Builders should respond to CLEAN_BUILD requests. A CLEAN_ BUILD request asks the builder to forget any additional build state it has maintained privately using an overridden version of the clean() method. A user-invoked clean request is followed by a FULL_BUILD request.

For this test, check that the outputs of the builder in question exist and note their timestamp using the Properties view. Invoke a CLEAN_BUILD request (Projects > Clean...). Verify that the outputs of the builder being tested have been recreated (check timestamps) and that the builder ran to completion without errors (check the error log).

14.4.6. Use IResourceProxy when possible (RFRS 5.3.8.4)

Best Practice #6 states:

Builders often need to process all the resources in a project when an IncrementalProjectBuilder.FULL_BUILD has been requested. There is an improved technique available starting with Eclipse 2.1. An IResourceProxyVisitor should be used in place of an IResourceVisitor. The proxy visitor provides access to lightweight IResourceProxy objects. These can return a real IResource object when required, but when not required, they result in improved overall builder performance for full builds.

To pass this test, you should avoid using IResourceVisitor objects and use IResourceProxyVistor objects instead. Search your plug-in source code for references to IResourceVisitor and explain why IResourceProxyVisitor could not be used instead.

14.4.7. Builders must be added by natures (RFRS 5.3.8.5)

Best Practice #7 states:

A builder must be added to a project by a nature. The nature implementation, as identified in the org.eclipse.core.resources.natures extension, will add any builders required as part of the configure() method.

For this test, show your nature definition in the plugin.xml file. Create a project with your nature and demonstrate that the builder is automatically configured. Add your nature to an existing project's .project file and show that your builder is invoked as soon as the file is saved.