Difference between revisions of "Developing Fiji in Eclipse"

(Convert {{arrow}} usage to {{bc}})
(Add instructions for installing into existing ImageJ from maven)
Line 93: Line 93:
 
}
 
}
 
</source>
 
</source>
 +
 +
==Testing your plugin in an existing installation==
 +
 +
When you run your plugin from Eclipse, you're only testing with the classpath ''of this project'' - which may or may not reflect the environment of an actual user's installation. To test your plugin in an existing installation you can either simply copy the jar, or use Maven to install your plugin and its dependencies.
 +
[[File:MavenRunConfig.png|thumb|right|450px|Setting up a new Maven Build configuration]]
 +
===Option 1: Copying the jar===
 +
 +
All modern Eclipse installations have the m2e plugin, so you can simply tell Maven to [http://www.vogella.com/tutorials/EclipseMaven/article.html#example_eclipsemavenproject_runningthebuild build the project]. This creates a <code>.jar</code> in the <code>/target</code> subdirectory, which you can then copy to an <code>ImageJ.app/jars/</code> directory.
 +
 +
This is a simple option that makes minimal changes to the existing installation.
 +
 +
===Option 2: Install dependencies===
 +
 +
All mavenized ImageJ projects have built-in support for installing directly into an existing installation, overwriting previous versions of any components, and pulling in up-to-date versions of any dependencies. This is the most robust way to test your plugin, but note that it may make additional changes to your existing ImageJ installation.
 +
 +
Steps are as follows:
 +
# Right-click your project in Eclipse and select {{bc|Run As|Run Configurations...}}
 +
# Scroll down to Maven Build. If you've built this project with Maven via Eclipse before there will already be a configuration for it. Otherwise you can double-click "Maven Build" to create a new run configuration.
 +
# Add a parameter: <code>imagej.app.directory</code> with value: <code><path/to/ImageJ.app></code> (e.g. <code>/home/hinerm/Fiji.app</code>)
 +
# Add a parameter: <code>delete.other.versions</code> with value: <code>true</code>
 +
# Click <code>Apply</code>
 +
 +
You can now run the project from this dialog. You only need to perform this configuration once though - future uses of the [http://www.vogella.com/tutorials/EclipseMaven/article.html#example_eclipsemavenproject_runningthebuild Maven Build] option will automatically copy your plugin and its dependencies to the specified ImageJ app.
  
 
==Adding new plugins==
 
==Adding new plugins==

Revision as of 10:19, 2 December 2015

Template:Development

Remember: if in doubt, be part of the community by asking and answering questions on the Mailing Lists.

Purpose

The purpose of this tutorial is to get you started hacking on Fiji's source code (i.e., the core Fiji plugins) inside the Eclipse IDE. If what you need is to develop a new plugin for ImageJ, you do not actually need Fiji's source. Rather, see these resources:

See also Developing Fiji for a more general tutorial unspecific to the Eclipse IDE.

Introduction

Eclipse is a powerful Integrated Development Environment (a so-called IDE) primarily intended to develop Java projects. It is similar to NetBeans and IntelliJ.

The advantages of using an IDE like Eclipse for developing:

  1. it is easy to access documentation about classes (i.e. javadocs): just point your cursor over the name of the class and hit Shift+F2.
  2. you can use code-completion: just type the start of the class name, variable, method, etc you want to use and hit ^ Ctrl+Space.
  3. compile errors are listed in a concise list; double-clicking on a line in that list will move the cursor to the problem.
  4. you can debug your program interactively: just open the main class (i.e. a class having a public static void main(String[] args) method) and go to Run>Debug As>Java Application. This will switch to a different window layout (the Debug perspective) which offers you a range of views that are useful for debugging such as: local variables, thread stack traces, etc. You can interrupt the program at any time by clicking on the pause symbol and inspect the current state, single-step through the code and even to a limited amount replace code on-the-fly
  5. the most important version control systems can be accessed easily
  6. awesome shortcuts
  7. vrapper - you don't have to abandon the command-line experience

Where there are advantages, there are also disadvantages. For example, Eclipse is quite big a program and requires a lot of resources, RAM and screen size in particular.

One other shortcoming -- Eclipse's unwillingness to let the developer specify that the source code is to be packaged into .jar files automatically -- was fixed by us by using Maven in conjunction with Eclipse (and luckily Netbeans and IntelliJ support Maven projects, too, so we now really only have to support one way to specify dependencies).

Install Eclipse

Install Eclipse using your preferred package manager or download the appropriate binaries of the Eclipse IDE for Java Developers. Launch Eclipse and decide for a workspace location (e.g. ~/workspace). Usually, current Java works just fine, but for some developers, Eclipse is not stable with Sun/Oracle Java 6. That is, you will eventually have to install Java 5 as an alternative JRE and make a custom launcher for Eclipse, e.g.

/usr/lib/jvm/java-1.5.0-sun/bin/java -cp /usr/lib/eclipse/startup.jar org.eclipse.core.launcher.Main

Install Git

Install Git using your preferred package manager or download from the Git website.

Checkout the source code you want to build

Please look at this tutorial to find out how to check out and build individual parts of Fiji.

Create the Eclipse Projects

First, clone your project(s) of interest from https://github.com/fiji. (If you want to clone them en masse, one way is using the myrepos command line tool.)

Once you have the projects cloned, you can import them into Eclipse via the File  › Import  › Maven  › Existing Maven Project command.

After finishing this, Eclipse builds the Fiji projects. There should not be any build errors, but it is normal to see a large number of warnings. These mostly come from Java1.4-style code or unnecessary imports, variables or methods in the sources of authors who do not use an IDE such as Eclipse and thus have no automatic assistance at cleaning up. All these warnings can be ignored, having no effect on the functionality of the code.

Running and Debugging

The major problem when debugging is that ImageJ 1.x expects all the plugins' .jar files to live in a sub-directory plugins/ in the ImageJ root directory. We can trick ImageJ by setting the property ij.dir to the location of the .jar file generated by m2e. The convenience class fiji.Debug in the fiji-lib component lets you do that without any pain:

import fiji.Debug; // requires fiji-lib as a dependency

[...]

public static void main(String[] args) {
    // requires a plugins.config in src/main/resources/ that defines the command name:
    // Plugins, "My shiny new plugin", the.current.PluginClass
    Debug.run("My shiny new plugin", "plugin parameters");
}

The format of plugin parameters can be determined by using the macro recorder, or just pass null if your plugin opens a dialog. For more complex plugins that are not macro recordable, you can pass empty strings to the run method - it will still launch an ImageJ instance with your plugin on the classpath.

If your plugin does not depend on fiji-lib by default, you can add it using maven. Just paste the following block into your pom.xml dependencies:

<dependency>
    <groupId>sc.fiji</groupId>
    <artifactId>fiji-lib</artifactId>
</dependency>

To debug classes of type PlugInFilter, use the Debug.runFilter(imagePath, plugin, parameters) method instead.

Note: if you do not even require ImageJ 1.x to really know about your plugin (i.e. the plugin does not have to show up in the menus for the testing/debugging to work), you can also do something like this instead:

public static void main(String[] args) {
    new ImageJ();
    ImagePlus image = IJ.openImage("/path/to/fiji/samples/clown.jpg");
    IJ.runPlugIn(image, "fiji.My_Beautiful_Plugin", "parameter=Hello");
    image.show();
    WindowManager.addWindow(image.getWindow());
}

Testing your plugin in an existing installation

When you run your plugin from Eclipse, you're only testing with the classpath of this project - which may or may not reflect the environment of an actual user's installation. To test your plugin in an existing installation you can either simply copy the jar, or use Maven to install your plugin and its dependencies.

Setting up a new Maven Build configuration

Option 1: Copying the jar

All modern Eclipse installations have the m2e plugin, so you can simply tell Maven to build the project. This creates a .jar in the /target subdirectory, which you can then copy to an ImageJ.app/jars/ directory.

This is a simple option that makes minimal changes to the existing installation.

Option 2: Install dependencies

All mavenized ImageJ projects have built-in support for installing directly into an existing installation, overwriting previous versions of any components, and pulling in up-to-date versions of any dependencies. This is the most robust way to test your plugin, but note that it may make additional changes to your existing ImageJ installation.

Steps are as follows:

  1. Right-click your project in Eclipse and select Run As › Run Configurations...
  2. Scroll down to Maven Build. If you've built this project with Maven via Eclipse before there will already be a configuration for it. Otherwise you can double-click "Maven Build" to create a new run configuration.
  3. Add a parameter: imagej.app.directory with value: <path/to/ImageJ.app> (e.g. /home/hinerm/Fiji.app)
  4. Add a parameter: delete.other.versions with value: true
  5. Click Apply

You can now run the project from this dialog. You only need to perform this configuration once though - future uses of the Maven Build option will automatically copy your plugin and its dependencies to the specified ImageJ app.

Adding new plugins

The easiest method is to start with a minimal project, renamed to the desired name of your plugin. By convention, the project directory should match the base name of the .jar file to be generated.

The format of such a pom.xml is described briefly on the Maven page.

Most importantly, you will need to adjust the artifactId and the dependencies section. Should you require a dependency that is not used in Fiji yet, you might want to search for the appropriate groupId and version in the ImageJ Maven repository.

Next, you will put your Java sources into src/main/java/ and adjust src/main/resources/plugins.config.

After that, ask Eclipse to import it: File  › Import  › Maven  › Import Existing Maven Project.