Difference between revisions of "Developing Fiji"
m (→The Fiji launcher: Typo: removed whitespace)
m (→Further reading for developers: added link to orphan page "Project ideas")
|Line 104:||Line 104:|
*[[Developing Fiji in Eclipse]]
*[[Developing Fiji in Eclipse]]
Revision as of 06:52, 30 November 2009
Fiji is a community effort. So we are happy whenever we see new people developing Fiji!
First, you have to download and build Fiji.
The Fiji launcher
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.
However, it is much more powerful than that. Amongst other things, you can
- Open images: ./fiji example.jpg
- 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 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.
The Fakefile system
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)!
The plugins/Examples folder contains numerous plugins in all supported languages, heavily commented.
There is an introductory tutorial to ImageJ programming in Java. The tutorial contains explanations on ImageJ datastructures (ImagePlus, ImageProcessor, Regions of Interest or ROIs, etc).
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.
Some projects have their own source code repositories. In this case, we do not copy the files into src-plugins/, but use submodules.
If the project uses a different source code management tool than Git, no problem, just mirror it.
Then add the submodule. Example:
# clone the VIB repository git clone ssh://email@example.com/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
In the case of VIB, it works as easily as that, because it has its own 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:
# clone the "egit" repository, but name it "jgit" git clone ssh://firstname.lastname@example.org/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
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.
At some point, you might want to debug whatever you wrote. There's a small Debugging intro page.
When you want to point at specific code on IRC or via mail, you can do so by posting links to our Gitweb. There is even a little shell script that helps you finding the link:
This script will open the appropriate link with Firefox. 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>".
You probably also want to let us know what you did, so just send a mail to the Fiji devel mailing list.