| [platform-releng-dev] improved checking for internal references |
Thanks to Jeffrey Liu of the Web Tools Project, we now have an improved tool that will run as part of our builds to help us detect common cases where our APIs are being overstepped or circumvented. Unlike the previous tool, which explicitly checks for references for internal packages in another plug-in, this tool works by check to see whether a reference is to a bona fide API class. The resulting report of violations is the same in either case. What this tool will do is let us (Eclipse Platform project) police our internal cross-component references. More importantly, it will also enable any downstream customer to detect illegal references into the Eclipse Platform components, as well as between their components. And customers can do this even if they adhere to API naming conventions different from those used by Eclipse. The tool takes as input a set of component definition files (component.xml) that provides the following information for each component: - what plug-ins are to be treated as a unit for the purposes of drawing an API boundary; all references between the plug-ins are considered a private matter (even if to internal packages) - a list of packages that are to be considered API packages - a list of classes and interfaces within the API package that have additional constraints on them (e.g., clients are not supposed to implement an API interface, instantiate an API class, or instantiate an API class) Each component definition file is a development-time resource that makes sense being maintained in the root of some plug-in. This means the file is under version control and can be maintained by the team as their component API evolve. (At some point I expect we'll embed this information in the source code using J2SE5 annotations, and dispense with the component.xml file entirely. Someday.) The component.xml file will be picked up in place by the RelEng build script and used to check for APi violations. The component.xml files will not be included in the normal binary for of the plug-in. Rather, they will be treated like other development-time files (e.g., extension point schema files) and included in the special source features/plug-ins we build for the SDK drops. This allows downstream builds to use the component.xml files from there so that they can check their components for references to Eclipse Platform APIs. And so on down the line. As an example, here's a component.xml file I crafted for the Core Resources component: I'd like to ask each of the teams to construct a component definition file for their component. In some cases, it may make sense to lump several plug-ins together as a single component; in other cases, it may make sense to treat otherwise intimate plug-ins as separate components. You're probably in the best position to decide exactly what component boundaries make the most sense (if not, I can help). Once the component boundaries are decided, it's very easy to fill out the information on the API packages and classes. The key thing for downstream customers is that the component API descriptions are created and maintained absolutely faithful to the API specifications at all time, so that they can infer from a clean check that their component are in good shape (within the known limitations of what the tool is capable of checking). Customers like WTP will be running this tool are part of their builds, and so will others. Once a component.xml is in place, I suggest trading with another team to perform an independent cross-check. Remember to add component.xml to the src.includes= line in the build.properties file, so that the file is included in the SDK drops. Sonia is already running the new tool with each build and posting the report (inside the Test Results page). (The tool is currently running against some bogus component.xml files that I had created; these will be superceded by your authentic component.xmls coming from your plug-ins.) The complete details of the component.xml file are here: http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/working/apitools/api-usage-checking-design.html?&cvsroot=WebTools_Project For further details on the tool: http://eclipse.org/webtools/development/apiscanner/apiscanner.html Let me know if you have any questions or concerns. ---jim Jim des Rivieres/Ottawa/IBM 12/10/2004 03:35 PM To platform-releng-dev@xxxxxxxxxxx cc Subject checking for internal references We have a tool that reports suspicious inter-plug-in references to classes in internal packages. I'm proposing that we run this tool as a standard step in each build (takes < 1 minute to run) and post the results along with the build. Like the performance results, this step would be for infomation only; i.e., a less than clean check build would not fail the build. The information will allow everyone to see where we are breaking (bending ?) our own API rules, and motivate us to address them. For 3.1, we should make it our goal to come clean and use our APIs as we expect everyone else to. I realize that some of the cases that are currently being flagged incorrectly, particularly cases where a single component is split across multiple plug-ins (e.g, o.e.ui and o.e.ui.workbench). In time, we can eliminate these false positves by introducing a more sophisticated notion of which plug-ins make up a single component. I'd like to see this new check turned on as soon as possible. Since some plug-ins/teams will be put in the spotlight once the checks start running, I thought I'd give everyone a chance to tidy up their houses before the TV crews arrive<g>, so I'm suggesting we turn it on after 3.1M4. Let me know if you have concerns. ---jim p.s. The tool is named "Internal" and can be found on the JDT Core team's development resources page. Here's a sample of the kind of report it generates (the report dates back to the days of 2.1): http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/jdt-core-home/tools/internal/examples/index.html
Attachment:
component.xml
Description: Binary data