Difference between revisions of "Developing Fiji"

(Fix link)
m (Update minimal-ij1-plugin link to example-legacy-plugin, due to renamed repository)
 
(44 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
{{FijiMenu}}{{Outdated}}
 +
 
Fiji is a community effort.  So we are happy whenever we see new people developing Fiji!
 
Fiji is a community effort.  So we are happy whenever we see new people developing Fiji!
  
== Getting started ==
+
== Purpose ==
  
First, you have to [[Downloading_and_Building_Fiji_From_Source|download and build Fiji]]. If you do not know Git yet, we have a [[Git for dummies|concise introduction]] for you.
+
The purpose of this tutorial is to get you started hacking on [https://github.com/fiji/ Fiji's source code] (i.e., the core Fiji plugins). If you need to develop a ''new plugin'' for ImageJ, you do not actually need Fiji's source. Rather, see these resources:
 +
* {{GitHub|org=imagej|repo=example-legacy-plugin|label=example-legacy-plugin}} project template
 +
* [[Introduction into Developing Plugins]] tutorial
 +
* [https://www.youtube.com/watch?v=Ac-6gJ2eRb0 Developing ImageJ 1.x plugins with NetBeans] screencast
  
== The Fiji launcher ==
+
See also [[Developing Fiji in Eclipse]] for a tutorial specific to the Eclipse IDE.
  
After building, you have a program called "fiji" in Fiji's root directory.  Its main purpose is to load a Java virtual machine with known-good options, and then launch ImageJA.
+
== Getting started ==
  
However, it is much more powerful than that. Amongst other things, you can
+
First, you have to [[Downloading_and_Building_Fiji_From_Source|download and build Fiji]]. If you do not know Git yet, we have a [[Git for dummies|concise introduction]] for you.
  
* Open images: '''./fiji example.jpg'''
+
== Building Fiji ==
* Call Jython scripts: '''./fiji example.py''' (also works for JRuby scripts when they have an '''.rb''' extension)
 
* Call the Jython interpreter: '''./fiji --jython''' (the classpath will be the same as when calling ImageJA)
 
* Run Fiji with the system Java instead of its own one: '''./fiji --system'''.  But beware: this might fail since some plugins need at least Java 1.5, and the 3D viewer needs Java3D.
 
* Show the java command line instead of running Fiji: '''./fiji --dry-run'''
 
* Run [[Fiji Build System]]: '''./fiji --build plugins/lens_correction.jar'''
 
* Compile a Java class: '''./fiji --javac example.java'''
 
* Run a Java class' main() method: '''./fiji --main-class=example'''
 
* Pass some [[JavaOptions|Java options]]: '''./fiji -server --''' (everything that comes before a '''--''' is interpreted as Java option)
 
* Link Fiji into the PATH: '''ln -s $(pwd)/fiji $HOME/bin/ && fiji'''
 
* Start Fiji and run a menu entry directly: '''./fiji --run Update_Fiji''' (the underscore was used in place of a space to avoid having to quote the argument)
 
  
The Fiji launcher can do more, just call '''./fiji --help''' for a short description.
+
Fiji is organized into a set of [[Maven]] projects. For convenience and speed, there is [[SciJava]]'s minimal Maven-lookalike [[MiniMaven]] to build Fiji, but it is recommended to use an [[IDEs|Integrated Development Environment]], or at least real Maven.
  
== The Fakefile system ==
+
For details, please see [[Downloading and Building Fiji From Source]].
 +
See also the [[Supported Compilers]] page for more information.
  
Fiji comes with its own builder, named [[Fiji Build System]].  There are already other build systems, such as Ant or Maven, but at least it is simple and small.  For details, go to [[Fiji Build System|this page]].
+
== Testing ==
 
 
== Adding plugins ==
 
 
 
After you built Fiji successfully, you can add your own plugins.
 
 
 
* If you haven't done so, pick a name for your .jar file, say ''My_Plugin''.  Make sure that it has at least one underscore in it, otherwise ImageJ will not pick it up.  If you cannot think of a name with an underscore, just append one.  Then create a subdirectory ''src-plugins/My_Plugin''.
 
* Now put your sources into that subdirectory.  Please no .class files.  Readme or license files are okay, however.
 
* Create a ''staged-plugins/My_Plugin.config'' file.  This will be included in the .jar file as ''plugins.config''.
 
* In Fiji's root folder, call '''./fiji bin/commit-plugin.py src-plugins/My_Plugin/'''.  Please make sure that it ends with a slash.  This command will make the necessary edits to the Fakefile and .gitignore, and ''staged-plugins/My_Plugin.config'', and commit everything needed for your plugin.  If you want to do this manually, look in the Git log for an example (e.g. TurboReg) and imitate it.
 
* Now build the plugin with '''./fiji --build'''.
 
* After testing, you might realize that you need changes.  In this case, decide if you want to amend the commit (if there was a silly typo, you might want to hide that fact from the world), or if you want to make a new commit.
 
* When everything is done and fine, publish (which is called "push" in Git)!
 
 
 
== Writing plugins ==
 
 
 
Fiji accepts plugins written in [http://www.mcdb.ucla.edu/research/hartenstein/acardona/imagej_programming_tutorials.html Java], [[Javascript Scripting|Javascript]], [[Jython Scripting|Jython]], [[JRuby Scripting|JRuby]], [[Beanshell Scripting|Beanshell]], [[Clojure Scripting|Clojure]] and the [http://rsb.info.nih.gov/ij/developer/macro/macros.html ImageJ Macro language].
 
 
 
The plugins/Examples folder contains numerous plugins in all supported languages, heavily commented.
 
 
 
See the [[Introduction into Developing Plugins]], Albert Cardona's [http://albert.rierol.net/imagej_programming_tutorials.html tutorial], or Werner Bailer's [http://imagingbook.com/index.php?id=102 Writing ImageJ PlugIns] for introductions to the ImageJ API (Application Programming Interface).
 
 
 
See [[Scripting Help]] for details on how to develop, test and run ImageJ plugins written in the supported scripting languages.
 
 
 
There are also [[Scripting comparisons]].
 
 
 
See also the [[PlugIn Design Guidelines]].
 
 
 
== Adding submodules ==
 
 
 
Some projects have their own source code repositories.  In this case, we do not copy the files into ''src-plugins/'', but use [[Git_submodule_tutorial|submodules]].
 
 
 
If the project uses a different source code management tool than Git, no problem, just mirror it.
 
 
 
Then add the submodule. Example:
 
<source lang="bash">
 
# clone the VIB repository
 
git clone ssh://contrib@fiji.sc/srv/git/VIB.git
 
# first time, commit-submodule need to know the target, too ("jars/jgit.jar" in this case)
 
./fiji bin/commit-submodule.py VIB plugins/VIB_.jar
 
</source>
 
 
 
In the case of ''VIB'', it works as easily as that, because it has its own [[Fiji Build System|Fakefile]].  Submodules do not need to have that, you can provide one in ''staged-plugins/'', and they do not need to be installed in ''plugins/'', either:
 
<source lang="bash">
 
# clone the "egit" repository, but name it "jgit"
 
git clone ssh://contrib@fiji.sc/srv/git/egit jgit
 
<create a staged-plugins/jgit.Fakefile>
 
# first time, commit-submodule need to know the target, too ("jars/jgit.jar" in this case)
 
./fiji bin/commit-submodule.py jgit jars/jgit.jar
 
</source>
 
  
So what does ''commit-submodule.py'' do? It
+
It is strongly recommended to write regression tests (also known as ''unit tests''). It is [[Fiji_contribution_requirements#Regression_tests|easy]].
* verifies that the submodule is pushed,
 
* makes sure that the submodule is recorded in ''.gitmodules'',
 
* adds the target to the ''Fakefile'',
 
* adds the target to ''.gitignore'' so it is not committed by accident,
 
* adds a precompiled/<target> to ensure that the submodule does not need to be checked out, and
 
* finally commits the result
 
  
== Testing ==
+
Furthermore, it is highly recommended to write and run unit tests in an [[IDEs|Integrated Development Environment]] for efficient debugging.
  
When you're testing Fiji, you may want to measure the code coverage of your tests - one way is described in the page [[Code Coverage in Fiji]].
+
You may also want to measure the code coverage of your tests - one way is described in the page [[Code Coverage in Fiji]].
  
 
At some point, you might want to debug whatever you wrote.  There's a small [[Debugging intro]] page.
 
At some point, you might want to debug whatever you wrote.  There's a small [[Debugging intro]] page.
Line 94: Line 35:
 
== Discussing code ==
 
== Discussing code ==
  
When you want to discuss your changes to some Fiji component, the preferred way is to inline a patch and sending it to the [http://groups.google.com/group/fiji-devel fiji-devel mailing list]. You can also send a link to your repository, e.g. a fork of [http://github.com/dscho/fiji Johannes' Fiji repository on github.com], but then commenting is not as easy (and the discussion will involve fewer developers).
+
When you want to propose and/or discuss changes to some source code, the preferred way is to [[contributing|submit a PR on GitHub]].
 
 
When discussing larger chunks of code (or a patch) on [irc://irc.freenode.net/fiji-devel IRC], you should not paste them directly, but you should use a [http://gist.github.com pastebin] instead.
 
 
 
When you want to point at specific code on IRC or via mail, you can also do so by posting links to our [[Git|Gitweb]].  There is even a little shell script in fiji.git that helps you finding the link:
 
<source lang="bash">
 
bin/open-in-gitweb.sh fiji.cxx
 
</source>
 
This script will open the appropriate link with xdg-open.  It can deal with files, even in submodules, and commits (for commits, your current directory must be inside the appropriate Git checkout).  For files, you can append ":<linenumber>" to the file name to get a link to a specific line.
 
  
 
== Contributing ==
 
== Contributing ==
  
Please make sure that you are a little familiar with [[Git mini howto|Git]].  Once you are, you can easily make a local ''contrib'' branch and [[Git mini howto#Contributing|push it]].
+
Please have a look at the excellent ''[[How to contribute to an existing plugin or library]]'' tutorial.
 
 
=== Forking on GitHub ===
 
Alternatively, you can make an account for yourself on GitHub and fork fiji.git:
 
 
 
# create an account on [http://github.com/ GitHub]
 
# Fork [http://github.com/dscho/fiji Fiji]:
 
: [[Image:GitHub-fork.png]]
 
# clone it
 
 
 
If you already worked in an existing checkout of ''fiji.git'', no problem, you can connect that to the new remote:
 
 
 
# '''git remote add github github.com:<user>/fiji''' (where ''<user>'' is your account on GitHub)
 
# '''git config branch.<branch>.remote github''' (where "<branch>" is the branch you want to connect to GitHub, typically ''master'')
 
# '''git config branch.<branch>.merge refs/heads/<branch>'''
 
# '''git push github <branch>''' to push the current state
 
 
 
=== Letting us know ===
 
 
 
After you published your contributions, you probably also want to let us know what you did, so just send a mail to [mailto:fiji-devel@googlegroups.com the Fiji devel mailing list].
 
  
 
== Providing documentation ==
 
== Providing documentation ==
Line 138: Line 52:
 
*[[Description of ImageJ's plugin architecture]]
 
*[[Description of ImageJ's plugin architecture]]
 
*[[Tips for developers]]
 
*[[Tips for developers]]
 +
*[http://jenkins.imagej.net/job/ImageJ1-javadoc/lastStableBuild/artifact/target/site/apidocs/ ImageJ1 Javadoc ZIP] (for offline usage)
 +
*[http://jenkins.imagej.net/job/ImageJ-daily/lastStableBuild/artifact/target/site/apidocs/ ImageJ2 Javadoc ZIP] (for offline usage)
 
*[[Developers HowTo]]
 
*[[Developers HowTo]]
 
*[http://www.imagingbook.com/index.php?id=102 ImageJ plugin writing tutorial]
 
*[http://www.imagingbook.com/index.php?id=102 ImageJ plugin writing tutorial]
Line 151: Line 67:
  
 
[[Category:Development]]
 
[[Category:Development]]
 +
[[Category:Fiji]]

Latest revision as of 14:56, 6 June 2017

Fiji-icon.png Fiji Is Just ImageJ
Overview
Using Fiji
Featured Fiji Projects
Fiji Publications
Links
Developing Fiji
Building Fiji from source
Developing Fiji
Contribution requirements



Fiji is a community effort. So we are happy whenever we see new people developing Fiji!

Purpose

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

See also Developing Fiji in Eclipse for a tutorial specific to the Eclipse IDE.

Getting started

First, you have to download and build Fiji. If you do not know Git yet, we have a concise introduction for you.

Building Fiji

Fiji is organized into a set of Maven projects. For convenience and speed, there is SciJava's minimal Maven-lookalike MiniMaven to build Fiji, but it is recommended to use an Integrated Development Environment, or at least real Maven.

For details, please see Downloading and Building Fiji From Source. See also the Supported Compilers page for more information.

Testing

It is strongly recommended to write regression tests (also known as unit tests). It is easy.

Furthermore, it is highly recommended to write and run unit tests in an Integrated Development Environment for efficient debugging.

You may also want to measure the code coverage of your tests - one way is described in the page Code Coverage in Fiji.

At some point, you might want to debug whatever you wrote. There's a small Debugging intro page.

Discussing code

When you want to propose and/or discuss changes to some source code, the preferred way is to submit a PR on GitHub.

Contributing

Please have a look at the excellent How to contribute to an existing plugin or library tutorial.

Providing documentation

A plugin wants to be used. Therefore you want to give users some information about it, and most likely also a tutorial how to use it.

If you have an account on this Wiki, you can easily create new tutorials with the Tutorial Maker.

Further reading for developers