PPA Tutorial - Part 4 - Going Headless

In this tutorial, you will learn how to invoke the code of your plug-in from the command line without displaying the Eclipse GUI or requiring any user input.

To be able to invoke your code from the command line, you need to create an Eclipse Application and the best way to do this is to create a new Eclipse plug-in that will depend on the plug-in (MyFirstPlugin) you created in the previous part of this tutorial.

This tutorial assumes that you have completed the first three parts of the tutorial and that you are now familiar with the main menus, views and editors of the Eclipse environment.

Configuring MyFirstPlugin

  1. You need to configure the plug-in you created (MyFirstPlugin) so that other plug-ins can depend on it and use the classes you created.
  2. Open the Plug-in editor (e.g., by double-clicking on the plugin.xml file in the Package Explorer) and go to the Runtime tab.
  3. In the Exported Packages section, add the packages of your plug-in, myfirstplugin and myfirstplugin.actions:
    Runtime Tab

Creating the headless plug-in

  1. Create an Eclipse plug-in project (right-click in the Package Explorer, select New / Project..., then Plug-in Development / Plug-in Project)
  2. Use the name MyHeadlessPlugin, then on the next page, ensure that all the checkboxes are unchecked and that you have selected yes to the question "Would you like to create a rich client application?":
    Runtime Tab
  3. On the next screen, select the template Headless Hello RCP, accept the default options and flick on Finish.
  4. Open the plug-in editor of MyHeadlessPlugin and navigate to the Dependencies tab. Add the following plug-ins to your dependencies: MyFirstPlugin, org.eclipse.core.resources, org.eclipse.jdt.core, and ca.mcgill.cs.swevo.ppa.ui:
    Dependencies
  5. Navigate to the Extensions tab, and select the org.eclipse.core.runtime.applications extension point. Change ID for myapp:
    Extensions
  6. Open the Application class that has been created in myheadlessplugin package. Modify the code of the start(IApplicationContext context) method:
    public Object start(IApplicationContext context) throws Exception {
    File javaFile = new File("/home/barthelemy/A.java");
    // CompilationUnit contains the AST of the partial program
    // PPAOptions is a wrapper and contains various configuration options:
    // most options are still not implemented, so the default options are
    // usually fine.
    CompilationUnit cu = PPAUtil.getCU(javaFile, new PPAOptions());
    PPATypeVisitor visitor = new PPATypeVisitor(System.out);
    cu.accept(visitor);
    return IApplication.EXIT_OK;
}
  7. If the import statements are not added automatically, just press on Ctrl+Shift+O. The code that you just wrote should look familiar. Basically, you are using the PPATypeVisitor class you created in MyFirstPlugin. If you had not added the package of this class in the Exported Packages of MyFirstPlugin and if you had not added MyFirstPlugin to the dependencies of MyHeadlessPlugin, you would not be able to access PPATypeVisitor.

Testing the headless plug-in

  1. You will now test if you can invoke the plug-in without displaying the Eclipse GUI. Go to the Run Configurations dialog (select Run / Run Configurations...).
  2. Create a new Eclipse Application that you will call Headless.
  3. Under the Program to Run section, select Run an application: and MyHeadlessPlugin.myapp.
  4. Apply the changes and click on the Run button. The code should be executed and you should see in your console the types of the expressions in the abstract syntax tree of file A.java:
    Testing Headless

Installing your plug-in in Eclipse

  1. To be able to invoke your code from the command line, you need to execute an Eclipse instance that has your plug-in installed. In this part of the tutorial, you will export your plug-in and you will install them in Eclipse.
  2. In the Plug-in editor of MyFirstPlugin, navigate to the Overview tab.
  3. Click on the Export Wizard link at the bottom right.
  4. Select the two plug-ins you created so far (MyFirstPlugin and MyHeadlessPlugin), and put the path of the dropins directory of your current Eclipse installation. This tutorial assumes that you have installed Eclipse under /home/barthelemy/eclipse_prog/eclipse3.5.1:
    Export Plug-ins
  5. When you start Eclipse, Eclipse always look in the dropins directory to see if there are new plug-ins to install. Close and re-open Eclipse so that your two plug-ins are installed in your Eclipse development environment. You should see an Eclipse button in your toolbar:
    Toolbar

Executing the headless plug-in

  1. You are now ready to execute your program from the command line. Close Eclipse.
  2. Then navigate to the installation directory of your Eclipse installation (e.g., /home/barthelemy/eclipse_prog/eclipse3.5.1) and enter on the command line:
    ./eclipse -data "/home/barthelemy/workspaces/runtime-New_configuration(1)" -nosplash -application MyHeadlessPlugin.myapp
  3. You should now see the types of the expressions in the abstract syntax tree of A.java.
  4. The -nosplash flag tells Eclipse to hide the spash screen.
  5. The -data flag tells Eclipse which workspace to use. This tutorial assumes that the workspace you use to test your plug-in is located at /home/barthelemy/workspaces/runtime-New_configuration(1).
  6. The -application flag tells Eclipse to run a custom application.

Next steps

You can try to pass additional arguments to the command line. They should be accessible through the IApplicationContext object in the start() method of your application.

This concludes the tutorial on PPA. If you have any question or comment, do not hesitate to contact me, Barthélémy at bart at cs dot mcgill dot ca.