| % XYZ Language Plug-in README |
| |
| The org.eclipse.photran.xyzsamplelang project demonstrates |
| how to use the \texttt{AdditionalLanguages} extension point. |
| It is just the sample XML editor plug-in that gets created when you choose |
| to create a new plug-in project and select the ``plug-in with an editor'' |
| template. However, it has been modified to integrate with the CDT. |
| Here is the README from that project, which is a cursory description of |
| how the CDT was modified and how the XYZ language was integrated. The |
| specific changes to the editor are documented in its code, so be sure |
| to read that too! |
| |
| \begin{verbatim} |
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
| |
| |
| HOW TO TIE A NEW SOURCE FILE TYPE, PARSER, AND MODEL BUILDER INTO THE CDT |
| (AND HOW TO MAKE THE CDT ALLOW IT) |
| |
| |
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
| |
| If you create your own editor, model builder, and ICElement-derived elements, |
| some simple changes to the CDT source code will make the CDT |
| integrate your parser and the elements it produces into its model. |
| |
| We add an AdditionalLanguages extension point to the CDT Core and change a |
| couple of methods to make use of it. |
| |
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
| |
| NOTE ON INCLUDED SOURCE CODE: |
| |
| All files in the CDT Integration Proof-of-Concept - Phase 1 source folder were |
| generated by the New Plug-In wizard EXCEPT: |
| |
| - Several changes were made to the editor's main class (XyzLanguageEditor) and |
| are commented there |
| - I added FortranContentOutlinePage |
| - I added the ToyElement and ToyModelBuilder classes (based on Photran's |
| FortranElement hierarchy and its (hidden) ToyModelBuilder) |
| - I added XyzLanguagePerspective, which gives us our own perspective and adds |
| a shortcut for our new file wizard to the New File menu |
| |
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
| |
| This is NOT well-written, and it is NOT a tutorial. It assumes you have some |
| idea of how the CDT works (e.g., what the Model is), and it assumes that you |
| will look at my code to see all the details. |
| |
| The XYZ Sample Language code is documented, so that should be read in addition |
| to this README. |
| |
| * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
| |
| First, I checked out the CDT source (most of it, anyway) from CVS. |
| |
| I created a basic editor and a New wizard to complement it |
| using the New Plugin wizard. I just called it XyzLanguageEditor |
| rather than XMLEditor or whatever the default is. The filename extension |
| is .xyz. |
| |
| I added the CDT Core and UI plugins as dependencies of my new plugin. |
| |
| After the wizard finished, I declared an xyzSource content type (text) to |
| match the .xyz filename extension that the editor uses. |
| |
| (I also created an XYZ Language perspective by subclassing CPerspective, although |
| that has only cosmetic value and isn't necessary for what I describe below.) |
| |
| ----- |
| |
| Before we can add additional languages to the CDT, we must make the following |
| changes to the CDT itself: |
| |
| Add an AdditionalLanguages extension point to the Core's plugin.xml |
| Add AdditionalLanguages.exsd to the Core's schema folder |
| Add org.eclipse.cdt.core.addl_langs package to the Core's src folder, containing: |
| IAdditionalLanguage -- Each extension language must implement this |
| AdditionalLanguagesExtension.java -- Provides access to extension point; iterable |
| AdditionalLanguagesIterator.java -- Iterates through contributed IAdditionalLanguages |
| IAdditionalLanguageCallback -- For performing an action on each contributed language |
| IModelBuilder -- Extension languages provide their model builder this way |
| IAdditionalLanguageElement -- ICElement extensions must implement this |
| |
| Now we need to make the CDT recognize our additional content types as |
| valid TranslationUnits in its model. |
| |
| These changes make sure CoreModel#getRegistedContentTypeId works for |
| additional content types. This function is called by CContainer |
| and, if it returns a valid (registerd-with-the-CDT) content type, |
| makes a TranslationUnit out of the file being processed. |
| |
| Essentially, we just add a line or two to each of the following which asks the |
| AdditionalLanguagesExtension to check whether some extension plug-in (like our |
| XYZ Language Plug-in) supports a given content type. |
| |
| 1. CoreModel#getRegistedContentTypeIds |
| 2. CCorePlugin#getContentType |
| 3. TranslationUnit#isSourceUnit |
| 4. CoreModel#isValidSourceUnitName |
| 5. CoreModel#isValidTranslationUnitName |
| |
| NOTE: |
| The following are places where the CCorePlugin.CONTENT_TYPE_CSOURCE |
| content type is checked for but I elected not to check for |
| extension content types: |
| TranslationUnit#isCLanguage |
| CoreModel#isValidCSourceUnitName |
| AbstractIndexerRunner#shouldIndex |
| ...the following two methods are identical... |
| DOMSearchUtil#getLanguage |
| InternalASTServiceProvider#getLanguage |
| |
| Next, we want to allow additional languages to be parsed by their own parser, |
| and they should be able to build their own models for the Outline and Make |
| Projects views. |
| |
| The CModelBuilder is called by TranslationUnit#parse. We will make |
| TranslationUnit#parse call our own model builder (ToyModelBuilder), which |
| will use some special ICElements (base class ToyElement) to extend the C Model. |
| Again, this is done through the extension point, so it can apply to any language. |
| |
| - CModelBuilder changed to implement IModelBuilder |
| - Added extension point checking to TranslationUnit#parse |
| - Made CElementInfo public (rather than default) |
| - Made CElementInfo#setIsStructureKnown public (rather than protected) |
| - Added extension point checking to CElementImageProvider#getBaseImageDescriptor |
| |
| The last point is important. Additional languages can reuse the CDT's model elements |
| (for functions, classes, etc. -- all the things that show up in the Outline), or |
| they can create their own (e.g., Fortran has Modules and Block Data, neither of |
| which have direct analogs in C/C++). These new elements can be created by implementing |
| IAdditionalLanguageElement. IAdditionalLanguageElements must implement a |
| method getBaseImageDescriptor() which provides an Outline icon for that element. |
| |
| ----- |
| |
| To integrate our XYZ language into the CDT... |
| |
| First, we add the following to our plugin.xml: |
| |
| <extension point="org.eclipse.cdt.core.AdditionalLanguages"> |
| <language class="addl_langs.XYZLanguage"/> |
| </extension> |
| |
| We provide a class addl_langs.XYZLanguage which implements IAdditionalLanguage. |
| See the JavaDoc for IAdditionalLanguage. Essentially, we claim to support |
| the XyzLanguagePlugIn.xyzSource content type, and we provide a ToyModelBuilder |
| which will provide a (static, and very boring) Outline of XYZ Language source files. |
| |
| Next, I added Outline support to the editor by making a tiny subclass of |
| CContentOutlinePage. See several relevant notes in XyzLanguageEditor.java. |
| See also FortranContentOutlinePage. We are telling CContentOutlinePage |
| its editor is null, since it doesn't do anything useful with it. |
| \end{verbatim} |