NOTES

Notes for Fiji developers
=========================

Fiji is organised into the following components:

- The Fiji superproject

- The following submodules

	- ImageJA

	- TrakEM2

	- VIB

The idea is to follow the projects in the submodules relatively closely,
and wrap them, together with Java, and make an easy installable package.

Building Fiji (including the submodules) should be as easy as calling
"make" in the project root directory.

Of course, this assumes that you have a Bash, make and gcc handy.  On
Linux/Unix and MacOSX, this is no problem.

For Windows, the easiest way is probably to use the msysGit package
(http://msysgit.googlecode.com/).  The standalone installer should
be enough.

Note that you'll probably need git (at least 1.5.3) in any case, to
handle the submodules, 3rd-party plugins, and to contribute back.

The menu structure for the plugins
----------------------------------

TODO

Installing 3rd party plugins
----------------------------

Please try to avoid closed-source plugins.

Just move the .jar into staged-plugins/, and create/adjust the corresponding
.config file (also in staged-plugins/).  Then type "make" and it will be
added/updated and committed.

Longer version:

The .config file should look something like this:

	File, "Show Prime Numbers", Primes_("")

where "File" is the menu you want to add the item to -- at the moment, the
only valid choices are "Plugins", "Plugins><submenu>", "File>Import",
"File>Save", "Analyze>Tools", "Help>About" and "Edit>Options".

Next comes the title of the menu item, and lastly the class name of the
plugin with a parameter that will be passed to the run() method of that
class.

In other words, the .config file will become the plugins.config of the
.jar file.

Please make sure that your .config file is designed such that the
menus fit in snuggly with the common Fiji menu structure.

Then just "make", and the plugin will be automatically installed and
committed (this needs "git" installed, though).


Adding a JDK
------------

To add a new JDK, copy it into a directory java/<name>, where <name> is
something similar to "linux", "win32", etc.

Then, call "uname -s", and introduce a section in the Makefile for it:

	ifeq ($(uname_S),Darwin)
		ARCH=macosx
		JAVA_HOME=$(JDK)/Home
		JAVA_LIB_PATH=../Libraries/libjvm.dylib
	endif

You need to find out the JRE home and the location of the library libjvm.
It may be necessary to override the variables JDK (defaults to java/$(ARCH)),
ARCH_INCLUDE (defaults to $(ARCH)), and INCLUDES (defaults to
-I$(JAVA_HOME)/../include -I$(JAVA_HOME)/../include/$(ARCH_INCLUDE)).

In this example, "Darwin" is the output of "uname -s", the JDK was copied
to java/macosx, the JRE lives in $(JDK)/Home, libjvm is in
$(JAVA_HOME)/../Libraries/libjvm.dylib, and Java's idea of the platform
name is "macosx".

Now call "make".  Fix all errors you encounter ;-)

When everything works, initialise a git repository in $(JDK):

	$ cd java/<whatever>
	$ git init
	$ git add .
	  <wait until it finished; this takes a while>
	$ git commit -m "Initial JDK for <whatever>"

Then, push this branch to instar, as "java/<whatever>":

	$ git push instar:/backup/repos/fiji.git/ \
		master:refs/heads/java/<whatever>

Now, commit the submodule in the superproject:

	$ cd ../..
	$ git fetch
	  <the fetch is necessary to fetch java in the superproject>
	$ git add Makefile
	$ git add java/<whatever>
	$ git commit -m "Inital JDK for <whatever>"

To verify that it all worked, just delete the JDK and try to let "make"
recreate it:

	$ rm -rf java/<whatever>
	$ mkdir java/<whatever>
	$ make


Upgrading a JDK / Adding Java3D
-------------------------------

It is much easier to upgrade a JDK than to add it:

	$ cd java/<whatever>
	$ rm -rf *
	$ cp -R /wherever/<jdk> ./
	$ git add -u
	$ git add .
	$ git commit -m "Upgrade JDK for <whatever>"

and push it:

	$ git push instar:/backup/repos/fiji.git/ \
		master:refs/heads/java/<whatever>

The procedure to add/upgrade Java3D is almost the same, except that you
skip the "rm -rf *" step, and that you copy the Java3D files, not the
JDK files, of course.


The portable app
----------------

One of the principal goals of Fiji is to provide an _easy_ way to install
all of Java, ImageJ and a set of plugins.

One way to do that is to have a so-called "portable app", an application
that does not need to be installed, but can run where you unpack it, or
it can even run from a USB disk.

For simplicity, we provide "One Fiji.app To Rule Them All".

Since MacOSX has the nice concept of "bundles", i.e. an application is just
a directory with a certain structure, the initial portable application is
the MacOSX application.

Subsequently all the necessary files are copied into Fiji.app, including
the JREs for the other platforms.

TODO: the subdirectory "Contents/MacOS/" has symbolic links; for USB disks
(which have a FAT filesystem, typically) we will have to adapt ImageJ-macosx
instead, to search not only in java/macosx, but also ../../java/macosx.