Skip to content, Skip to search

Changes

Developing Fiji

9,354 bytes removed, 14:56, 6 June 2017
m
Update minimal-ij1-plugin link to example-legacy-plugin, due to renamed repository
{{Template: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 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=minimalexample-ij1legacy-plugin|label=minimalexample-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://imagej.net/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 {{GitHub|repo=fiji|path=src-plugins/pom.xml|label=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 are 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 send 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 {{GitHub[contributing|repo=fiji|label=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 submit a patch) PR on [irc://irc.freenode.net/fiji-devel IRC], please do not paste them directly, but use a [http://gist.github.com pastebin] instead. To point at specific code on IRC or via mail, you can also do so by posting links to our [[Git|GitwebGitHub]]. 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 {{GitHub|repo=fiji|label=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 === Contributing to Fiji's existing plugins === Sometimes you may want How to contribute to Fiji's an existing plugins, for example, a bug is found in one plugin and you want to fix it, or you would like to improve one plugin by adding more functions. '''Every plugin has its own git repository in {{GitHub|org=fiji|repo=|label=Fiji}}'''. For example, the GraphCut plugin's repository is {{GitHub|org=fiji|repo=Graph_Cut|label=GraphCut}}. This structure allows for easy, independent development of the individual parts of which the base version of Fiji consists. 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'''## library]]'''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], including 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