Difference between revisions of "Developing ImageJ in Eclipse"

m (Add Curtis' and Christian's shortcuts.)
m (Adding useful video tutorial for setup)
 
(35 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<div style="float: right">
+
{{DevelopMenu | tutorials}}This article explains how to install, configure and use Eclipse to develop [[ImageJ]] [[components]] and [[plugins]]. Directions correspond to Eclipse 4.4 Luna, and may need adjustment for other versions.
{{Development | source}}
 
<div style="clear: right"></div>
 
{{Windows | '''Avoid permissions issues.''' We recommend installing Eclipse ''outside'' of the <code>Program Files</code> directory. E.g.: '''<code>C:\Users\frood\Programs\eclipse</code>''', where '''<code>C:\Users\frood</code>''' is your user directory.
 
  
'''Configuring Eclipse.''' After installing Eclipse, you will need to configure it to know about your JDK.
+
= Initial setup =
 +
 
 +
== Install the Java Development Kit ==
 +
 
 +
* Download and install the Java Development Kit (JDK) from the [http://www.oracle.com/technetwork/java/javase/downloads/ Java web site].
 +
 
 +
== Install and configure Eclipse ==
 +
 
 +
=== Install Eclipse ===
 +
 
 +
* Download "Eclipse IDE for Java Developers" from the [http://www.eclipse.org/downloads/ Eclipse web site].
 +
{{Warning |  It is '''important''' to choose "Eclipse IDE for Java Developers" because it contains Maven support built-in. Otherwise, you will have to [http://eclipse.org/m2e/ install the M2E plugin manually].}}
 +
 
 +
* Unpack the archive to a location of your choice.
 +
 
 +
=== Configure Eclipse for your platform ===
 +
 
 +
<div style="overflow: hidden">
 +
<tabs>
 +
<tab name="Windows">
 +
[[File:Win.png | x32px]] '''Windows'''
 +
 
 +
'''Avoid permissions issues.''' We recommend installing Eclipse ''outside'' of the <code>Program Files</code> directory. E.g.: '''<code>C:\Users\frood\Programs\eclipse</code>''', where '''<code>C:\Users\frood</code>''' is your user directory.
 +
 
 +
'''Configure Eclipse.''' After installing Eclipse, you will need to configure it to know about your JDK.
  
 
Use Wordpad to edit the <code>eclipse.ini</code> file in your Eclipse installation (e.g., '''<code>C:\Users\frood\Programs\eclipse</code>'''). (Do not use Notepad, because it will not handle the Unix-style line breaks properly.) Carefully follow [http://wiki.eclipse.org/Eclipse.ini#Specifying_the_JVM these instructions] to specify the proper JDK. Then save the file and quit Wordpad.
 
Use Wordpad to edit the <code>eclipse.ini</code> file in your Eclipse installation (e.g., '''<code>C:\Users\frood\Programs\eclipse</code>'''). (Do not use Notepad, because it will not handle the Unix-style line breaks properly.) Carefully follow [http://wiki.eclipse.org/Eclipse.ini#Specifying_the_JVM these instructions] to specify the proper JDK. Then save the file and quit Wordpad.
Line 11: Line 32:
  
 
* Launch Eclipse
 
* Launch Eclipse
* From the menu choose Window {{arrow}} Preferences
+
* From the menu choose {{bc | Window | Preferences}}
* Select Java {{arrow}} Installed JREs
+
* Select {{bc | Java | Installed JREs}}
 
* Click Search..., navigate to your JDK installation folder (e.g., '''<code>C:\Program Files\Java\jdk1.8.0_11</code>''') and click OK
 
* Click Search..., navigate to your JDK installation folder (e.g., '''<code>C:\Program Files\Java\jdk1.8.0_11</code>''') and click OK
 
* Check the box next to the JRE that appears and click OK
 
* Check the box next to the JRE that appears and click OK
}}
+
</tab>
<div style="clear: right"></div>
+
<tab name="OS X">
{{Linux | '''Avoid permissions issues.''' We recommend installing to <code>$HOME/eclipse</code>.
+
[[File:Osx.png | x32px]] '''OS X'''
  
'''Do not use a package manager.''' For several reasons, we do not recommend installing Eclipse from a package manager. You may not get a new enough version of Eclipse (we recommend 4.3+), you will not get the Java Developers version that includes the M2E plugins, and you will likely have trouble installing additional plugins due to the permissions issues with the system-wide installation.
+
'''Understand Java 6 vs. Java 8.''' Eclipse should work on OS X with no further configuration. However, we recommend reading the [[FAQ#Mac_OS_X|OS X section of the FAQ]], as there are several Java-related issues on OS X.
}}
+
</tab>
</div>
+
<tab name="Linux">
This article explains how to install and configure Eclipse for use with [[ImageJ]] development. Directions correspond to Eclipse 4.4 Luna, and may need adjustment for other versions.
+
[[File:Tux.png | x32px]] '''Linux'''
__TOC__
 
  
== Install and configure Eclipse ==
+
'''Avoid permissions issues.''' We recommend installing to <code>$HOME/eclipse</code>.
  
=== Install the Java Development Kit ===
+
'''Do not use a package manager.''' For several reasons, we do not recommend installing Eclipse from a package manager. You may not get a new enough version of Eclipse (we recommend 4.3+), you will not get the Java Developers version that includes the M2E plugins, and you will likely have trouble installing additional plugins due to the permissions issues with the system-wide installation.
  
* Download and install the Java Development Kit (JDK) from the [http://www.oracle.com/technetwork/java/javase/downloads/ Java web site].
+
'''Adjust the Eclipse font size.''' Sometimes it is desirable to change the Eclipse font size. To do so, create a GTK configuration file (e.g. <code>~/.gtkrc-eclipse</code>) and place the following lines there:
 +
style "eclipse" {
 +
    font_name = "Sans Condensed 8"
 +
}
 +
class "GtkWidget" style "eclipse"
  
=== Install Eclipse ===
 
  
* Download "Eclipse IDE for Java Developers" from the [http://www.eclipse.org/downloads/ Eclipse web site].
+
Then run eclipse using this command: <code>GTK2_RC_FILES=~/.gtkrc-eclipse eclipse</code>
{{Warning |  It is '''important''' to choose "Eclipse IDE for Java Developers" because it contains Maven support built-in. Otherwise, you will have to [http://eclipse.org/m2e/ install the M2E plugin manually].}}
+
</tab>
 +
</tabs>
 +
</div>
  
* Unpack the archive to a location of your choice.
+
== Clone the source code ==
 
 
* See the right-hand sidebars for platform-specific notes.
 
  
== Clone the source code ==
+
Using your [http://git-scm.com/downloads/guis Git client of choice], clone the source code which interests you:
  
* Using your [http://git-scm.com/downloads/guis Git client of choice], clone the [[source code]] which interests you.
+
* If you want to work on an existing project, see the [[source code|list of sources]].
 +
* If you are creating your own project, see the [[building a pom]] guide.
  
 
== Import the source code ==
 
== Import the source code ==
  
# Choose File {{arrow}} Import from the Eclipse menu
+
# Choose {{bc | File | Import}} from the Eclipse menu
 
# Select "Existing Maven Projects" and click Next
 
# Select "Existing Maven Projects" and click Next
 
# Browse to the folder where you cloned the project source code
 
# Browse to the folder where you cloned the project source code
 
# Click Finish
 
# Click Finish
  
== Launching ImageJ ==
+
Eclipse will import and automatically build the project(s). There should not be any build errors, but it is normal to see a large number (often hundreds) of warnings. These mostly come from Java-1.4-style code or unnecessary imports, variables or methods in the sources of authors who do not use an IDE and thus have no automatic assistance at cleaning up. All these warnings can be ignored, having no effect on the functionality of the code.
 +
 
 +
If you're having trouble, how to import and build your Maven + Eclipse project, follow this video: [https://www.youtube.com/watch?v=YIWpoBnnLio How To Setup and Make a Fiji Plugin]
 +
 
 +
= The Run-Debug cycle =
 +
<div style="float: right;
 +
        width: 400px;
 +
        border: 1px solid #ccc;
 +
        padding: 15px !important;
 +
        margin-top: 1em;
 +
        margin-bottom: 2em;
 +
        background-color: #ffefbe;
 +
        {{border-radius|0.75em}} {{box-shadow}}">
 +
== Keyboard shortcuts ==
 +
On OS X, replace {{Key|Ctrl}} with  {{Key|Cmd}}
 +
{|
 +
| colspan=2 | '''Navigation'''
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|Shift|T}}
 +
| Open a Java class from the workspace
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|Shift|R}}
 +
| Open a file from the workspace
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|F3}}
 +
| Jump to selected class<br>(to edit the code, see [[Architecture#Using_snapshot_couplings_during_development|snapshot coupling]])
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|O}}
 +
| Show superclass/subclass hierarchy
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|T}}
 +
| Show implementations of interface or class
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|L}}
 +
| Go to line number
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|Q}}
 +
| Go to last edit location
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|E}}
 +
| Go to next file in editor
 +
|-
 +
| colspan=2 | '''Editing'''
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Alt|Up}}, {{Key|Alt|Down}}
 +
| Move current line up or down
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|D}}
 +
| Delete the current line
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|/}}
 +
| Comment/uncomment the selected line(s)
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|1}}
 +
| Quick fix selected error
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|Space}}
 +
| Auto-complete current selection
 +
|-
 +
| colspan=2 style="padding-top: 1em" | '''Code cleanup'''
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|Shift|O}}
 +
| Organize imports
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|Shift|F}}
 +
| Format code<br>(BUT make sure you set the [[Coding_style#Eclipse_code_style_profiles|coding style]])
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Alt|Shift|S}}, {{Key|U}}
 +
| Clean up (does format and much more)
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Alt|Shift|R}}
 +
| Refactor/rename selected class/variable
 +
|-
 +
| colspan=2 style="padding-top: 1em" | '''Debugging'''
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|Ctrl|Shift|B}}
 +
| Set/Remove breakpoint
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|F5}}
 +
| Step into
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|F6}}
 +
| Step over
 +
|-
 +
| style="text-align: right; vertical-align: top; white-space: nowrap" | {{Key|F7}}
 +
| Step out
 +
|}
 +
</div>
 +
Now that you have the project successfully nestled within Eclipse, you can run it, change the code, and run it again, iterating as needed to develop features and fix bugs. This process is known as the ''run-debug cycle''—although some people call it ''compile-debug'' or ''edit-compile-debug'' or ''edit-compile-run'' or ''debug-edit-compile'' or ''edit-build-test-debug'' or ''edit-compile-link-debug'' or...
 +
 
 +
== Launch ImageJ ==
  
 
If you cloned the [https://github.com/imagej/imagej imagej project], you can launch the program as follows:
 
If you cloned the [https://github.com/imagej/imagej imagej project], you can launch the program as follows:
Line 61: Line 175:
 
# Choose "Run As" and then "Java Application"
 
# Choose "Run As" and then "Java Application"
  
Other projects will have different main classes.
+
Other projects will have different main classes, but the general procedure is the same.
 +
 
 +
==Running and debugging==
 +
One major problem when debugging [[ImageJ 1.x]] plugins 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 [[Fiji]] project provides a convenience class ''fiji.Debug'' in the {{GitHub | org=fiji | repo=fiji-lib | label=fiji-lib}} component which lets you do that without any pain:
 +
 
 +
<source lang="java">
 +
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");
 +
}
 +
</source>
 +
 
 +
The format of <code>plugin parameters</code> can be determined by using the [[macro recorder]], or just pass <code>null</code> if your plugin opens a dialog. For more complex plugins that are not macro recordable, you can pass empty strings to the <code>run</code> method—it will still launch an ImageJ instance with your plugin on the classpath.
 +
 
 +
If your plugin does not depend on <code>fiji-lib</code> by default, you can add it using [https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html maven]. Just paste the following block into your <code>pom.xml</code> dependencies:
 +
 
 +
<source lang="xml">
 +
<dependency>
 +
    <groupId>sc.fiji</groupId>
 +
    <artifactId>fiji-lib</artifactId>
 +
</dependency>
 +
</source>
 +
 
 +
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:
 +
 
 +
<source lang="java">
 +
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());
 +
}
 +
</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>imagej.deleteOtherVersions</code> with value: <code>always</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==
 +
 
 +
The easiest method is to start with a [https://github.com/imagej/example-legacy-plugin minimal project], renamed to the desired name of your plugin. By convention, the project directory should match the base name of the <code>.jar</code> file to be generated.
 +
 
 +
The format of such a <code>pom.xml</code> is described briefly on the [[Maven]] page.
 +
 
 +
Most importantly, you will need to adjust the <code>artifactId</code> and the <code>dependencies</code> section. Should you require a dependency that is not used in Fiji yet, you might want to search for the appropriate <code>groupId</code> and <code>version</code> in the [http://maven.imagej.net/ ImageJ Maven repository].
 +
 
 +
Next, you will put your Java sources into <code>src/main/java/</code> and adjust <code>src/main/resources/plugins.config</code>.
 +
 
 +
After that, ask Eclipse to import it: {{bc | File | Import | Maven | Import Existing Maven Project}}.
 +
 
 +
==Viewing Dependency Source==
 +
 
 +
When jumping into a dependency class in Eclipse (using {{Key|F3}}), you may see a message stating "Source not found".
 +
 
 +
For Maven dependencies there must be a <code>-sources</code> classifier JAR in the repository along side the main JAR. For example, <code>imagej-common</code> has an <code>imagej-common-0.24.4.jar</code> and an <code>imagej-common-0.24.4-sources.jar</code>. In theory, the Eclipse M2E plugin should download this <code>-sources</code> JAR and automatically display it to you when you jump to the class.
 +
 
 +
However, if for some reason this doesn't happen you can try the following steps.
 +
 
 +
#Try right-clicking the JAR in the Maven dependencies in Eclipse, and selecting "Download Sources". This should force Eclipse to download the <code>-sources</code> JAR.
 +
#Check that the <code>-sources</code> JAR has been downloaded locally.
 +
#* Navigate to <code><path-to-.m2-repo>/repository/<groupId>/<artifactId>/<version></code> and see if there is a <code>-sources</code> JAR there.
 +
#* If it is not, then in a terminal navigate to the folder containing your project's pom.xml file. And then from the command line run <br /><code>mvn dependency:get -Dartifact=groupId:artifactId:version:packaging:classifier</code>.
 +
#**For example if a project depended on imagej-common and you needed to retrieve the <code>-sources</code> JAR, the command you'd type would be:<br /> <code>mvn dependency:get -Dartifact=net.imagej:imagej-common:0.24.4:jar:sources</code>
 +
#If the <code>-sources</code> JAR was there, you could check its contents by running the following command from the terminal:<br /><code>jar tr <path-to-.m2-repo>/repository/<groupId>/<artifactId>/<version>/<jar-name>-sources.jar</code>.
 +
#*If the file in question isn't there, then unfortunately this project doesn't have source for that class.
 +
 
 +
If the class you're trying to view is a part of the JRE and you're on Linux, you may need to run <code>sudo apt install openjdk-<java-version-number>-sources</code> to retrieve the sources.
 +
 
 +
Note that doing this only allows you to view the source code, it does '''not''' allow you to edit it. If you need to edit these files, see the [[Architecture#Using_snapshot_couplings_during_development|snapshot coupling]] section for more information.
  
== Keyboard Shortcuts ==
+
== See also ==
  
For Mac, replace {{Key|Ctrl}} with  {{Key|Cmd}}
+
{| class="wikitable nicetable"
 +
! [[ImageJ2]]
 +
! [[ImageJ 1.x]]
 +
|-
 +
|
 +
* [[Writing plugins]]
 +
* [[How to contribute to an existing plugin or library|Contributing to a plugin]]
 +
|
 +
* {{GitHub|org=imagej|repo=example-legacy-plugin|label=example-legacy-plugin}} project template
 +
* [[Developing Plugins for ImageJ 1.x]]
 +
|}
  
* {{Key|Shift}}+{{Key|Ctrl}}+{{Key|T}}: find objects
+
[[Category:Development]]
* {{Key|Ctrl}}+{{Key|1}}: quick fix
+
[[Category:IDEs]]
* {{Key|F3}}: jump to class (to edit the code, see [[Architecture#Using_snapshot_couplings_during_development|snapshot coupling]])
 
* {{Key|Ctrl}}+{{Key|O}}: show outline
 
* {{Key|Ctrl}}+{{Key|Space}}: auto-complete
 
* {{Key|Ctrl}}+{{Key|T}}: shows all implementations of interface or class
 
* {{Key|Alt}}+{{Key|Up}} or {{Key|Alt}}+{{Key|Down}}: move lines up or down
 

Latest revision as of 12:46, 14 March 2019

Development
Topics
Overview
Philosophy
Architecture
Source code
Project management
Coding style
Debugging
Tools
GitHub
Git
Maven
IDEs
Travis
AppVeyor
Dotfiles
Guides
Writing plugins
ImageJ Ops
Contributing to a plugin
Distributing your plugins
Development lifecycle
Building a POM
Developing with Eclipse
Hands-on debugging
Adding new ops
Adding new formats
Using native libraries
Tips for developers
Tips for C++ developers
ImageJ 1.x plugins
Versioning
Logging
Uber-JARs

This article explains how to install, configure and use Eclipse to develop ImageJ components and plugins. Directions correspond to Eclipse 4.4 Luna, and may need adjustment for other versions.

Initial setup

Install the Java Development Kit

  • Download and install the Java Development Kit (JDK) from the Java web site.

Install and configure Eclipse

Install Eclipse



  • Unpack the archive to a location of your choice.

Configure Eclipse for your platform

Win.png Windows

Avoid permissions issues. We recommend installing Eclipse outside of the Program Files directory. E.g.: C:\Users\frood\Programs\eclipse, where C:\Users\frood is your user directory.

Configure Eclipse. After installing Eclipse, you will need to configure it to know about your JDK.

Use Wordpad to edit the eclipse.ini file in your Eclipse installation (e.g., C:\Users\frood\Programs\eclipse). (Do not use Notepad, because it will not handle the Unix-style line breaks properly.) Carefully follow these instructions to specify the proper JDK. Then save the file and quit Wordpad.

Now update Eclipse's JRE to be JDK-aware:

  • Launch Eclipse
  • From the menu choose Window  › Preferences
  • Select Java  › Installed JREs
  • Click Search..., navigate to your JDK installation folder (e.g., C:\Program Files\Java\jdk1.8.0_11) and click OK
  • Check the box next to the JRE that appears and click OK

Osx.png OS X

Understand Java 6 vs. Java 8. Eclipse should work on OS X with no further configuration. However, we recommend reading the OS X section of the FAQ, as there are several Java-related issues on OS X.

Tux.png Linux

Avoid permissions issues. We recommend installing to $HOME/eclipse.

Do not use a package manager. For several reasons, we do not recommend installing Eclipse from a package manager. You may not get a new enough version of Eclipse (we recommend 4.3+), you will not get the Java Developers version that includes the M2E plugins, and you will likely have trouble installing additional plugins due to the permissions issues with the system-wide installation.

Adjust the Eclipse font size. Sometimes it is desirable to change the Eclipse font size. To do so, create a GTK configuration file (e.g. ~/.gtkrc-eclipse) and place the following lines there:

style "eclipse" {
    font_name = "Sans Condensed 8"
}
class "GtkWidget" style "eclipse"


Then run eclipse using this command: GTK2_RC_FILES=~/.gtkrc-eclipse eclipse

Clone the source code

Using your Git client of choice, clone the source code which interests you:

Import the source code

  1. Choose File  › Import from the Eclipse menu
  2. Select "Existing Maven Projects" and click Next
  3. Browse to the folder where you cloned the project source code
  4. Click Finish

Eclipse will import and automatically build the project(s). There should not be any build errors, but it is normal to see a large number (often hundreds) of warnings. These mostly come from Java-1.4-style code or unnecessary imports, variables or methods in the sources of authors who do not use an IDE and thus have no automatic assistance at cleaning up. All these warnings can be ignored, having no effect on the functionality of the code.

If you're having trouble, how to import and build your Maven + Eclipse project, follow this video: How To Setup and Make a Fiji Plugin

The Run-Debug cycle

Keyboard shortcuts

On OS X, replace ^ Ctrl with Cmd

Navigation
^ Ctrl+ Shift+T Open a Java class from the workspace
^ Ctrl+ Shift+R Open a file from the workspace
F3 Jump to selected class
(to edit the code, see snapshot coupling)
^ Ctrl+O Show superclass/subclass hierarchy
^ Ctrl+T Show implementations of interface or class
^ Ctrl+L Go to line number
^ Ctrl+Q Go to last edit location
^ Ctrl+E Go to next file in editor
Editing
Alt+, Alt+ Move current line up or down
^ Ctrl+D Delete the current line
^ Ctrl+/ Comment/uncomment the selected line(s)
^ Ctrl+1 Quick fix selected error
^ Ctrl+Space Auto-complete current selection
Code cleanup
^ Ctrl+ Shift+O Organize imports
^ Ctrl+ Shift+F Format code
(BUT make sure you set the coding style)
Alt+ Shift+S, U Clean up (does format and much more)
Alt+ Shift+R Refactor/rename selected class/variable
Debugging
^ Ctrl+ Shift+B Set/Remove breakpoint
F5 Step into
F6 Step over
F7 Step out

Now that you have the project successfully nestled within Eclipse, you can run it, change the code, and run it again, iterating as needed to develop features and fix bugs. This process is known as the run-debug cycle—although some people call it compile-debug or edit-compile-debug or edit-compile-run or debug-edit-compile or edit-build-test-debug or edit-compile-link-debug or...

Launch ImageJ

If you cloned the imagej project, you can launch the program as follows:

  1. In the Package Explorer, expand the imagej project
  2. Navigate into src/main/java
  3. Navigate into net.imagej
  4. Right-click on Main.java
  5. Choose "Run As" and then "Java Application"

Other projects will have different main classes, but the general procedure is the same.

Running and debugging

One major problem when debugging ImageJ 1.x plugins 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 Fiji project provides a convenience class fiji.Debug in the fiji-lib component which 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: imagej.deleteOtherVersions with value: always
  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.

Viewing Dependency Source

When jumping into a dependency class in Eclipse (using F3), you may see a message stating "Source not found".

For Maven dependencies there must be a -sources classifier JAR in the repository along side the main JAR. For example, imagej-common has an imagej-common-0.24.4.jar and an imagej-common-0.24.4-sources.jar. In theory, the Eclipse M2E plugin should download this -sources JAR and automatically display it to you when you jump to the class.

However, if for some reason this doesn't happen you can try the following steps.

  1. Try right-clicking the JAR in the Maven dependencies in Eclipse, and selecting "Download Sources". This should force Eclipse to download the -sources JAR.
  2. Check that the -sources JAR has been downloaded locally.
    • Navigate to <path-to-.m2-repo>/repository/<groupId>/<artifactId>/<version> and see if there is a -sources JAR there.
    • If it is not, then in a terminal navigate to the folder containing your project's pom.xml file. And then from the command line run
      mvn dependency:get -Dartifact=groupId:artifactId:version:packaging:classifier.
      • For example if a project depended on imagej-common and you needed to retrieve the -sources JAR, the command you'd type would be:
        mvn dependency:get -Dartifact=net.imagej:imagej-common:0.24.4:jar:sources
  3. If the -sources JAR was there, you could check its contents by running the following command from the terminal:
    jar tr <path-to-.m2-repo>/repository/<groupId>/<artifactId>/<version>/<jar-name>-sources.jar.
    • If the file in question isn't there, then unfortunately this project doesn't have source for that class.

If the class you're trying to view is a part of the JRE and you're on Linux, you may need to run sudo apt install openjdk-<java-version-number>-sources to retrieve the sources.

Note that doing this only allows you to view the source code, it does not allow you to edit it. If you need to edit these files, see the snapshot coupling section for more information.

See also

ImageJ2 ImageJ 1.x