Skip to content, Skip to search

Changes

Developing Fiji

9,388 bytes removed, 14:56, 6 June 2017
m
Update minimal-ij1-plugin link to example-legacy-plugin, due to renamed repository
{{FijiMenu}}{{Outdated}}
 
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 [https://github.com/fiji/fiji/ Fiji's source code] (i.e., the core Fiji plugins). If what you need is to develop a ''new plugin'' for ImageJ, you do not actually need Fiji's source. Rather, see these resources:* [https://github.com/{{GitHub|org=imagej/minimal|repo=example-ij1legacy-plugin minimal|label=example-ij1legacy-plugin] }} project template
* [[Introduction into Developing Plugins]] tutorial
* [https://www.youtube.com/watch?v=Ac-6gJ2eRb0 Developing ImageJ 1.x plugins with NetBeans] screencast
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 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, for Beanshell scripts with '''.bsh''' extension, '''.clj''' for Clojure and '''.js''' for Javascript)
* Call the Jython interpreter: '''./fiji --jython''' (the classpath will be the same as when calling ImageJA), and likewise '''--jruby''', '''--bsh''' and '''--js''' for the respective language's command-line interpreters
* 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)
* Add '''.''' to the classpath and execute the given class' '''main()''' method: '''./fiji Example.class'''
* 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.
== Building Fiji ==
Fiji is organized into a set of [[Maven]] projects. For convenience and speed, we use there is [[ImageJ2SciJava]]' s minimal Maven-lookalike [[MiniMaven]] to build Fiji, and but it is recommended to make things even more convenientuse an [[IDEs|Integrated Development Environment]], there is a single shell script you need to call that builds it all:or at least real Maven.
<source lang="bash">For details, please see [[Downloading and Building Fiji From Source]].See also the [[Supported Compilers]] page for more information./Build.sh</source>
See the [[Supported Compilers]] page for more details on the Fiji build system. == Adding plugins Testing == 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 ''pom.xml'' and ''.gitignore'' files, 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'''.* Now Fiji Build will most likely complain that some libraries are missing, most importantly the central library ij.jar, you will need to specify which jars are required for the build:** open the file ''pom.xml'' in the ''src-plugins/'' directory with a text editor of your choice** find the section "From source"** you will find a lot of entries which look like CLASSPATH(plugins/Whatever_plugin.jar)=jars/ij.jar** Add an entry for your plugin and add the required jars, e.g. CLASSPATH(plugins/My_plugin.jar)=jars/ij.jar:jars/imglib.jar - if you want to write a plugin using imglib** save the file and build again* 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 It is strongly recommended to write regression tests (also the known as ''unit tests''). It is [[PlugIn Design GuidelinesFiji_contribution_requirements#Regression_tests|easy]].
=== Plugins Furthermore, it is highly recommended to write and run unit tests in the Fiji Source Tree ===an [[IDEs|Integrated Development Environment]] for efficient debugging.
The sources for many useful plugins are maintained in src-plugins/ in the Fiji source tree. In order to be built by the Fiji Build System, they must be properly [[Maven_-_Frequently_Asked_Questions|Mavenized]]. In other words, there should be a pom.xml file that describes the plugin, and its artifactId should be added as a module in the modules section of [https://github.com/fiji/fiji/blob/master/src-plugins/pom.xml the pom file for src-plugins] (alphabetically, please). See You may also [[Maven_-_Frequently_Asked_Questions]] == 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 repositorygit 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> Submodules '''must''' be Maven projects themselves. So what does ''commit-submodule.py'' do? It* verifies that the submodule is pushed,* makes sure that the submodule is recorded in ''.gitmodules'',* adds the target to the ''modules/pom.xml'' file,* adds the target to ''.gitignore'' so it is not committed by accident, and* finally commits the result == Testing == 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.
== Discussing code ==
When you want to propose and/or discuss your changes to some Fiji componentsource code, the preferred way is to inline a patch and sending it to the [mailto:fiji@fiji.sc fiji-devel mailing list]. You can also send a link to your repository, e.g. a fork of [http://github.com/fiji/fiji the Fiji repository on github.com], but then commenting is not as easy (and the discussion will involve fewer developers). When discussing larger chunks of code (or contributing|submit a patch) PR on [irc://irc.freenode.net/fiji-devel IRCGitHub], 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 ==
Please make sure that you are have a little familiar with [[Git mini howto|Git]], or you can learn basic git knowledge interactively with [http://try.github.io/ GitHub]. Once you are, you can easily make a local 'look at the excellent 'contrib'' branch and [[Git mini howto#Contributing|push it]]. === 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/fiji/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 How 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 contribute to connect to GitHub, typically ''master'')# '''git config branch.<branch>.merge refs/heads/<branch>'''# '''git push github <branch>''' to push the current state === Contributing to Fiji's existing plugins === Sometime you want to contributing to Fiji's an existing plugins, for example, you find a bug in one plugin and you want to fix it, or you want to improve one plugin by adding more functions. '''Every plugin has its own git repository in [https://github.com/fiji/ Fijilibrary]'''. For example, the GraphCut plugin's repository is [https://github.com/fiji/Graph_Cut GraphCut]. This structure allows for easy, independent development of the individual parts of which the base version of Fiji consists. Suppose that you want to contribute to Fiji's GraphCut plugin:# ''' Fork that repository by clicking the "Fork" button'''# ''' Clone it - git clone https://github.com/username/Graph_Cut.git'''# ''' Configure remotes'''## '''cd Graph_Cut'''## '''git remote add upstream https://github.com/fiji/Graph_Cut.git'''## '''git fetch upstream'''# '''Create a topic branch'''## '''git branch mybranch'''## '''git checkout mybranch'''# '''Make changes and commit them to your topic branch'''# '''Push the commits to your github repository'''# '''Send the pull request''' You can learn more about Git fork and branch model from [https://help.github.com/articles/fork-a-repo Fork A Repo], and learn how to send a pull request from [https://help.github.com/articles/using-pull-requests Pull Request] === 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@fiji.sc the Fiji devel mailing list]tutorial.
== Providing documentation ==
[[Category:Development]]
[[Category:Fiji]]
40
edits