Difference between revisions of "Talk:Linux Tools Project/Libhover/Developers Guide"

Latest revision as of 18:33, 5 November 2012

I've been interested in creating libhover help and have been asking a few questions in the linuxtools-dev@eclipse.org mailing list. Thought I'd accumulate answers from Jeff and Alex here, in case others are also interested in this topic.

--Gurce 23:51, 2 November 2012 (UTC)

Looking at examples

You'll probably want to look at examples of the existing libhover xml files (eg, "glibc-2.1.4.xml"), to see how they flow. So you'll need to grab the source via Git. More info on this here:

• Linux_Tools_Project/Git

Building the libhover file

Once you locate the "glibc-2.1.4.xml" file, you can try build the libhover file from it with the command:

java -cp '/youreclipsepath/plugins/*' org.eclipse.linuxtools.cdt.libhover.utils.BuildFunctionInfos glibc-2.14.xml glibc-2.14.libhover

Note the single-quote so your command line doesn't try expanding the * and then complains about not finding any main class: xxxxxx.jar

If successful, it should report:

Built glibc-2.14.libhover from glibc-2.14.xml

Plugin example

As this has been my 1st attempt at writing an Eclipse plug-in, I thought I'd better share the learning-curve experience here too, to remind myself how it's done, and for other newbies to figure it out quickly.

The steps here have been derived from the following page, only tailored for libhover plug-ins:

• http://www.eclipse.org/articles/Article-PDE-does-plugins/PDE-intro.html

Walkthrough

• Create a new "Plug-in Project" via the New Project wizard
  
• Give a project name. Uncheck the "Create a Java project" checkbox, since libhover plugins don't have any java source.
  
• On the "Dependencies" of the manifest, add:
  • org.eclipse.linuxtools.cdt.libhover.library.docs
  • org.eclipse.linuxtools.cdt.libhover
    
• On the "Extensions" of the manifest, add:
  • org.eclipse.linuxtools.cdt.libhover.library
  • org.eclipse.help.toc
    
    
    Note: you will need to uncheck the "Show only extension points from the required plug-ins" setting to find the 2nd extension mentioned above (org.eclipse.help.toc)
    
• Edit the "plugin.xml" file, using the existing copy from the glibc-libhover as a reference
  
• Create a "data" sub-folder. Within it, create and edit your libhover xml file.
  
  As an example, here's one I concocted up for this 1st attempt of mine:

<descriptions>
  <construct id="function-SDLNet_ResolveHost" type="function">
    <function returntype="int">
      <prototype>
        <parameter content="IPaddress *address"/>
        <parameter content="const char *host"/>
        <parameter content="Uint16 port"/>
      </prototype>
      <headers>
        <header filename = "SDL_net.h"/>
      </headers>
        <synopsis>
        blah blah blah
        </synopsis>
    </function>
  </construct>
</descriptions>

Note: Don't forget to add the "function-" prefix to the function-name as highlighted above.

• Build the *.libhover file via the command:

java -cp '/pathtoeclipse/plugins/*' org.eclipse.linuxtools.cdt.libhover.utils.BuildFunctionInfos test.xml test.libhover

• Right-click your project and select "Debug As >> Eclipse Application"
  
• A new instance of eclipse will open. Make a new C-project and add a test c-file with some code that makes use of the function you generated libhover help for.
• Hover the mouse over the function in your test c-code, and you should then see the libhover text appear
  
• After successfully getting your 1st plug-in attempt working, you will probably want to modify your "test.xml" file with more functions to try, re-build the "test.libhover" file with the "BuildFunctionInfos" command mentioned earlier and re-launch the "Debug As >> Eclipse Configuration"
• One gotcha you will run into here is that it will have cached your earlier copy of "test.libhover", so when you hover over your new functions, you won't see anything, but the initial function you had still hovers ok.
• To get around this, go to "Debug As >> Debug Configurations..."
• Locate your "Eclipse Application" launcher in the left-pane and select it
• Go to the "Configuration" tab in the right-pane and check the "Clear the configuration area before launching" checkbox.
• Press "Apply" and "Debug" buttons.
• In future, each time you debug, your latest *.libhover file will be loaded.

• It turns out that wasn't the full story. After your eclipse debug-launcher opens do the following:
  • Go to "Window >> Preferences >> Library Hover"
  • Uncheck the "Cache library hover data in workspace" setting
  • Restart your eclipse-debug launch for the setting to take effect.