"Hello world" for ImageJ with Eclipse

How can we prepare an environment for the development of ImageJ plugins in Java using Eclipse IDE? Here is an answer. The example below was for Windows 10, but the procedures required for macOS is very similar, except that you don't have to set the environmental variables. It has quite a lot of steps, and a bit challenging for someone who is not familiar with Eclipse. 

## References
These two references are almost identical to mine. Yet, the first one is pretty old (last updated in 2010) with a bug, and I still needed to struggle a bit to get it to work. The second one is in Japanese. So I decided to write my own version in English, which really worked for me. I think the example below is equivalent of [Method 3 of the reference 1: "Importing the ImageJ source, using ImageJ build.xml, building with ant"](http://imagejdocu.tudor.lu/doku.php?id=howto:plugins:the_imagej_eclipse_howto#method_3importing_the_imagej_source_using_imagej_buildxml_building_with_ant)


1. [The ImageJ Eclipse Howto](http://imagejdocu.tudor.lu/doku.php?id=howto:plugins:the_imagej_eclipse_howto)

2. [EclipseでImageJのPlugin作成 -下準備編 ver.2-](http://aki-miya.hatenablog.com/entry/2017/12/29/Eclipse%E3%81%A7ImageJ%E3%81%AEPlugin%E4%BD%9C%E6%88%90_-%E4%B8%8B%E6%BA%96%E5%82%99%E7%B7%A8_ver.2-)



# 1. Install JDK 8

1. Go to [the Oracle web site](https://www.oracle.com/technetwork/java/javase/downloads/index.html) and download **JDK 8**. <br /> ![Image001.png](https://qiita-image-store.s3.amazonaws.com/0/109898/9c884a4b-f34f-b899-862f-d0531f9b9b3d.png)

2. Accept License Agreement and download JDK (**Windows x64** in this case. Choose the one that is for you). <br /> ![Image002.png](https://qiita-image-store.s3.amazonaws.com/0/109898/06e71c8a-978f-23e1-3a27-b2ecd3c1a8c6.png)

3. You'll have downloaded the file `jdk-8u181-windows-x64.exe` (Windows x64). Double-click the file and install the JDK to your PC.#

4. Change the Environment Variables for JDK (**NOTE: this is only required for Windows**. For macOS, jump to step 5)
   1. Type `adv` in the Windows Search Box next to the Start button. Click **View advanced system settings**. Then go to **Environmental Variables... > User variables for XXXXX** <br />  ![Image003.png](https://qiita-image-store.s3.amazonaws.com/0/109898/b90a66f0-6de4-4202-4bb8-4147ebd829e1.png) ![Image005.png](https://qiita-image-store.s3.amazonaws.com/0/109898/5e4a315b-3870-ed16-6470-646d529850c0.png)

   2. Find the folder where the JDK binary files are. It should look like: `C:\Program Files\Java\jdk1.8.0_181\bin` . Copy the address from the Explorer and paste it into a new field by clicking the **New** button.<br />  ![Image004.png](https://qiita-image-store.s3.amazonaws.com/0/109898/b9862f68-152a-99d7-f24f-217f2acee8dd.png) ![Image006.png](https://qiita-image-store.s3.amazonaws.com/0/109898/0eb43a82-0812-521b-e68f-f00196fd82b6.png)
5. Type `cmd` in the Windows Search Box next to the Start button. Launch **Command Prompt**. (for macOS, launch **Terminal**)
6. Type `javac -version` into Command Prompt and press Enter.
7. If the installation of JDK is successful, you'll see the version of JDK as below: <br /> ![Image051.png](https://qiita-image-store.s3.amazonaws.com/0/109898/0053f76f-d6bb-07ef-24f5-2bfa71243c5d.png)


# 2. Install Eclipse

1. Go to Eclipse download page https://www.eclipse.org/downloads/ and Click the **Download** button. Click **Download** in the next page to start downloading.　<br /> ![Image007.png](https://qiita-image-store.s3.amazonaws.com/0/109898/0ddb5ef0-2344-2f29-aeb1-3d72c18db563.png)　<br /> ![Image008.png](https://qiita-image-store.s3.amazonaws.com/0/109898/7781a003-b36f-a9c3-2166-472f184ebcd3.png)


2. Launch the Eclipse installer, and click **Eclipse IDE for Java Developers**. <br /> ![Image009.png](https://qiita-image-store.s3.amazonaws.com/0/109898/e33dbb1f-de12-8cf5-3d66-ab672c2e8874.png)


3. Choose Installtion folder. With regard to file permission, it is recommended to install Eclipse outside of usual `C:\Programs\`. click the **INSTALL** button. <br /> ![Image010.png](https://qiita-image-store.s3.amazonaws.com/0/109898/9f12e087-7ac0-ca4a-2f52-297045d18746.png)


4. During installation, you'll be asked about licensing. Click **Accept** to proceed.　<br />  ![Image011.png](https://qiita-image-store.s3.amazonaws.com/0/109898/a67fa2a9-c9ae-4d8f-38c6-7d373194e3f2.png)


5. Launch Eclipse.　<br />  ![Image012.png](https://qiita-image-store.s3.amazonaws.com/0/109898/846fa1b3-6e92-2e8f-c72c-8b549ce7fe5d.png)


6. Select a directory as workspace. Accept as it is and click **Launch**.　<br />  ![Image013.png](https://qiita-image-store.s3.amazonaws.com/0/109898/b5797b64-7442-9077-a7a7-6388b621d6ce.png)


7. It will look like this:　<br />  ![Image014.png](https://qiita-image-store.s3.amazonaws.com/0/109898/9195fdb5-442c-0f6c-5ceb-20331346b04e.png)



# 3. Create a Java project IJ

1. Create a new Java Project from **File > New > Java Project**:　<br />  ![Image015.png](https://qiita-image-store.s3.amazonaws.com/0/109898/0f8e030f-bfe7-f5ad-9b8c-8eaaf4a2f335.png)


2. Type `IJ` for **Project name**, and click **Next**.　<br />  ![Image016.png](https://qiita-image-store.s3.amazonaws.com/0/109898/740323ea-9163-8b54-5aed-01e5fe577eb1.png)


3. In the Source tab, make sure that Default output folder is set as `IJ/bin`.　<br />  ![Image017.png](https://qiita-image-store.s3.amazonaws.com/0/109898/050cca44-f35c-a575-6a18-76235f3f41e7.png)


4. Then click **Link additional source:**. This will make ImageJ jar files available to this Java project.

   1. Download the latest version of Image from https://imagej.nih.gov/ij/download/src/. Unzip the file in a appropriate folder.
   2. Using **Browse** button, choose the `source` folder within the ImageJ folder unzipped. Click **Next**.　<br />  ![Image019.png](https://qiita-image-store.s3.amazonaws.com/0/109898/9979db91-1efd-8e2d-ca48-e55cf945a4ea.png)

   3. In the **Inclusion and Exclusion Patterns** dialog, click **Add** for **Inclusion patterns**. 　<br /> ![Image052.png](https://qiita-image-store.s3.amazonaws.com/0/109898/36ca17a1-9e8c-ab08-f750-61f13c9d415c.png)

   4. Type `IJ_Props.txt` or browse to select that file. click **OK**.　<br />  ![Image020.png](https://qiita-image-store.s3.amazonaws.com/0/109898/723f73ae-7205-7191-34b0-80e9494dded2.png)

   5. Also **Add** `ij/` to **Inclusion patterns**. ![Image021.png](https://qiita-image-store.s3.amazonaws.com/0/109898/a3acc653-7202-deab-3aa9-0e9d9355fbae.png)

   6. Also **Add** `images/`, `macors/`, and `plugins/` to **Exclusion patterns**, and click **Finish**.　<br />  ![Image022.png](https://qiita-image-store.s3.amazonaws.com/0/109898/6ffd4a39-a55a-0c75-c64c-82126707723e.png)

7. In the **Libraries** tab, click **Add External JARs...**, and browse to JDK's `toolbar.jar` file. <br /> ![Image018.png](https://qiita-image-store.s3.amazonaws.com/0/109898/b0d9555a-2f58-f2e2-b116-345a9906ab7c.png)

   - In Windows 10, `toolbar.jar` can be found at `C:\Program Files\Java\jdk1.8.0_181\lib\toolbar.jar` or somewhere similar.
   - In macOS, it can be found at `/Library/Java/JavaVirtualMachines/jdk1.8.0_181.jdk/Contents/Home/toolbar.jar` .

# 4. Create a Java project TESTPlugin_

1. Create a new Java Project from **File > New > Java Project**:　<br />  ![Image015.png](https://qiita-image-store.s3.amazonaws.com/0/109898/29710305-7822-eda1-c32d-13507b1bb2de.png)

2. Set Project name as `TESTPlugin_`. In order to show the new plugin in ImageJ's pull down menu, the name must end with underscore `_`. Click **Next**.　<br />  ![Image024.png](https://qiita-image-store.s3.amazonaws.com/0/109898/8fe93139-3257-dab8-8da6-f57cf1dffb10.png)

3. In the Source tab, make sure that the Default output folder is set to `TESTPlugin_/bin`. <br /> ![Image025.png](https://qiita-image-store.s3.amazonaws.com/0/109898/6ab093b7-72eb-7380-2da5-68a033975255.png)

4. In the Projects tab, click **Add** and select the **IJ**, which you've just created. Click **Finish**.<br /> ![Image026.png](https://qiita-image-store.s3.amazonaws.com/0/109898/e72af4bf-645f-2425-106a-5a98787b15f6.png)
<br /> ![Image027.png](https://qiita-image-store.s3.amazonaws.com/0/109898/7ef4f5fe-56c3-a8ef-a76f-f8fddff77a6d.png)


# 5. Create TESTPlugin_ class

1. Add a new class to the project `TESTPlugin_` by **New > Class**<br />![Image023.png](https://qiita-image-store.s3.amazonaws.com/0/109898/d08561ca-97f6-da6b-9357-f35fa272e148.png)

2. Set Name to `TESTPlugin_` and click **Finish**.<br/> ![Image028.png](https://qiita-image-store.s3.amazonaws.com/0/109898/66e5b909-86cb-a4f4-da79-c1d3719e7a7c.png)

3. Copy the code below and paste it into `TESTPlugin_.java`. Make sure the name of the `.java` file and the class name must be identical. Again, you need the underscore `_` in order to make this plugin visible in ImageJ's pulldown menu. <br/> ![Image029.png](https://qiita-image-store.s3.amazonaws.com/0/109898/a7c72fd4-4d7d-0c4f-2d4f-37a832714b97.png)


```java
import ij.IJ;
import ij.plugin.PlugIn;
 
public class TESTPlugin_ implements PlugIn {
	public void run(String arg) {
		IJ.error("Hello world!");
	}
}
```

# 6. Create build.xml

1.  Create a new file by **File > New > File**. Under the project `TestPlugin_`. <br />  ![Image030.png](https://qiita-image-store.s3.amazonaws.com/0/109898/6783c9b0-c517-ea2a-4fb4-72dbfffd2c8a.png) <br /> ![Image031.png](https://qiita-image-store.s3.amazonaws.com/0/109898/a9dcf20a-9dd1-59ca-96d8-2d4c4edc960c.png)

2.   Copy and paste the code below to the file `build.xml`.　<br />  ![Image032.png](https://qiita-image-store.s3.amazonaws.com/0/109898/4498a990-59c3-9f07-deaa-5bc336d495da.png)


```xml
<project name="TESTPlugin_" default="" basedir=".">
    <description>
        TESTPlugin_ build file
    </description>
  <property name="src" location="src" />
  <property name="build" location="bin" />
  <property name="dist"  location="dist" />
 
	 <property name="pluginsDir"  location="$basedir/../../IJ/plugins/" />
 
  <property name="user.name" value="Patrick Pirrotte" />
<target name="main" depends="compress" description="Main target">
	<echo>
		Building the .jar file.
	</echo>
</target>
 <target name="compress" depends="" description="generate the distribution">
 	<jar jarfile="TESTPlugin_.jar">
 		<fileset dir="." includes="plugins.config" />
		<fileset dir="${build}" includes="**/*.*" />
 		<manifest>
 		 	 	      <attribute name="Built-By" value="${user.name}"/>
 		</manifest>
 	</jar>
    <copy file="TESTPlugin_.jar" toDir="${pluginsDir}" />
  </target>
</project>
```
# 7. Builder configuration
1. From Package Explorer, right-click on the `TESTPlugin_`  project and select **Properties**.<br /> 　![Image033.png](https://qiita-image-store.s3.amazonaws.com/0/109898/4802499e-b199-9aa8-c44b-57c254f62233.png)

2. In the Property dialog, click **Builders**.　<br /> 　![Image034.png](https://qiita-image-store.s3.amazonaws.com/0/109898/1d15b34f-1948-1c2e-ff8e-b76416198cd8.png)

3. In Builders, click **New...**, and select **Ant Builder** and click **OK**.　<br /> 　![Image035.png](https://qiita-image-store.s3.amazonaws.com/0/109898/c65942e0-993b-8441-8ac9-a3f480af8e36.png)

4. In the **Main** tab, go to **Buildfile:** and click **Browse Workspace...** and select the `build.xml` in `TESTPlugin_` project.　<br />  ![Image037.png](https://qiita-image-store.s3.amazonaws.com/0/109898/7cdc0436-93ab-fec7-239a-74ab8e7930ae.png)　<br /> ![Image036.png](https://qiita-image-store.s3.amazonaws.com/0/109898/84e36be5-8931-6671-3c97-adc9292baa39.png)

5. In the **Targets** tab, click Set **Targets...** for both **After a "Clean":**  and **Auto Build:**, and select **main** and **compress** for both of them. <br />  ![Image038.png](https://qiita-image-store.s3.amazonaws.com/0/109898/8c1fa318-0b13-d560-024d-e6bf00ec6e2e.png)　<br />  ![Image053.png](https://qiita-image-store.s3.amazonaws.com/0/109898/5b54fe9f-1dc6-c920-c179-bd3148b2b667.png)　<br /> 　![Image039.png](https://qiita-image-store.s3.amazonaws.com/0/109898/74a806e2-0c63-d7e9-4a77-511680a37e7a.png)


# 8. Debug
1. **Run > Debug Configurations...** 　<br /> 　![Image041.png](https://qiita-image-store.s3.amazonaws.com/0/109898/bec2f628-541a-c030-9ff0-1e79e7dc7878.png)

2. Double-click **Java application**. Set **Project** to `IJ`  and **Main class:** to `ij.ImageJ` (`JavaPackageName.ClassName`)　<br />  ![Image042.png](https://qiita-image-store.s3.amazonaws.com/0/109898/c8440211-dcec-1bb2-3f93-14277093a014.png)　<br /> 　 ![Image044.png](https://qiita-image-store.s3.amazonaws.com/0/109898/51acfa90-2849-cf67-cb99-fbae5166d574.png)

3. Go to the **Source** tab,  and click **Add...**　<br /> 　![Image045.png](https://qiita-image-store.s3.amazonaws.com/0/109898/9fed35f5-62a2-772b-ccd3-984f797ff696.png)

4. Select **Java Project** and click **OK**　<br /> 　![Image046.png](https://qiita-image-store.s3.amazonaws.com/0/109898/6f2c385e-2cc4-116c-4d64-3f2ef516e76c.png)

5. Select the `TESTPlugin_` project. This step is crucial if you want to step into your plugin source during the debug phase.　<br /> 　![Image047.png](https://qiita-image-store.s3.amazonaws.com/0/109898/6c7d93e9-c692-fc32-6634-2264364c6dbc.png)

6. **Apply** the changes and then click **Debug**.　<br /> 　![Image048.png](https://qiita-image-store.s3.amazonaws.com/0/109898/fbd59da9-3169-15cb-9b51-149dd8c89468.png)

7. **ImageJ** should launch and select **Plugins > TESTPlugin** (it should be visible at this stage).<br /> 　![Image049.png](https://qiita-image-store.s3.amazonaws.com/0/109898/79e63268-10b4-badd-8ff4-247570813b18.png)

8. You'll see the **Hello World** message.　<br /> 　![Image050.png](https://qiita-image-store.s3.amazonaws.com/0/109898/ee162a61-d805-5ee3-3732-7784f1dfca42.png)

# Contact

Dr Kouichi C. Nakamura
kouichi.nakamura@pharm.ox.ac.uk
kouichi.c.nakamura@gmail.com

MRC Brain Network Dynamics Unit, Department of Pharmacology, University of Oxford