Difference between revisions of "Developing Fiji"

(Discussing code: stop recommending open-in-gitweb.sh)
m (Update minimal-ij1-plugin link to example-legacy-plugin, due to renamed repository)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Template:Outdated}}{{Development | fiji}}
+
{{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!
  
Line 5: Line 6:
  
 
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:
 
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=minimal-ij1-plugin|label=minimal-ij1-plugin}} project template
+
* {{GitHub|org=imagej|repo=example-legacy-plugin|label=example-legacy-plugin}} project template
 
* [[Introduction into Developing Plugins]] tutorial
 
* [[Introduction into Developing Plugins]] tutorial
 
* [https://www.youtube.com/watch?v=Ac-6gJ2eRb0 Developing ImageJ 1.x plugins with NetBeans] screencast
 
* [https://www.youtube.com/watch?v=Ac-6gJ2eRb0 Developing ImageJ 1.x plugins with NetBeans] screencast
Line 14: Line 15:
  
 
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.
 
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 ImageJ launcher ==
 
 
There is a program called "ImageJ-win32.exe", "ImageJ-linux64" or similar in Fiji's root directory.  Its main purpose is to load a Java virtual machine with known-good options, and then launch ImageJ.
 
 
However, it is much more powerful than that.  Amongst other things, you can
 
 
* Open images: '''./ImageJ-<platform> example.jpg'''
 
* Call Jython scripts: '''./ImageJ-<platform> 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: '''./ImageJ-<platform> --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: '''./ImageJ-<platform> --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: '''./ImageJ-<platform> --dry-run'''
 
* Compile a Java class: '''./ImageJ-<platform> --javac example.java'''
 
* Run a Java class' main() method: '''./ImageJ-<platform> --main-class=example'''
 
* Pass some [[JavaOptions|Java options]]: '''./ImageJ-<platform> -server --''' (everything that comes before a '''--''' is interpreted as Java option)
 
* Add '''.''' to the classpath and execute the given class' '''main()''' method: '''./ImageJ-<platform> Example.class'''
 
* Link Fiji into the PATH: '''ln -s $(pwd)/ImageJ-<platform> $HOME/bin/fiji && fiji'''
 
* Start Fiji and run a menu entry directly: '''./ImageJ-<platform> --run System_Clipboard''' (the underscore was used in place of a space to avoid having to quote the argument)
 
 
The ImageJ launcher can do more, just call '''./ImageJ-<platform> --help''' for a short description.
 
  
 
== Building Fiji ==
 
== Building Fiji ==
Line 54: 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 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|repo=fiji|label=the 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], 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|Gitweb]]. See also [[GitHub Tricks]].
 
  
 
== Contributing ==
 
== Contributing ==
  
Please make sure that you are 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 ''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 {{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 to contribute to Fiji's 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'''
 
## '''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].
 
  
 
== Providing documentation ==
 
== Providing documentation ==
Line 132: 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