Difference between revisions of "Overview of Fiji's source code"

(add to category Development)
(Jenkins -> Travis)
 
(17 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
== The Fiji launcher ==
 
== The Fiji launcher ==
  
The [[Developing Fiji#The_Fiji_launcher|Fiji launcher]] is a relatively small C++ program whose source sits in [http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=fiji.git;a=blob;f=fiji.cxx;hb=HEAD <Fiji-root>/fiji.cxx].
+
The [[Fiji Launcher]] is now called ''ImageJ launcher'' and lives {{GitHub|org=imagej|repo=imagej-launcher|label=in its own repository}}. It is [https://travis-ci.org/imagej/imagej-launcher built by Travis CI].
  
The whole purpose of the launcher is to make launching Java and Fiji easier, but there are a few other niceties in there, such as running Jython scripts or .jar files with the same classpath as Fiji.
+
== The plugins ==
  
The generated launcher is ''<Fiji-root>/fiji'' (or on Windows, ''fiji.exe'').
+
The plugins served from Fiji's update site are all [[Why Closed-Source Is Wrong|Open Source]]. The source code lives {{GitHub|org=fiji|repo=|label=on GitHub}}, in repositories reflecting the name of the ''.jar'' file generated from the source code. Example: the source code for ''Fiji_Plugins.jar'' lives in https://github.com/fiji/Fiji_Plugins.
  
== The plugins ==
+
The only special rule applies for plugins whose file names end in an underscore: that underscore will be stripped. Example: the sources of ''Arrow_.jar'' are stored in https://github.com/fiji/Arrow.
 +
 
 +
All of our plugins are maintained as [[Maven]] projects; this allows developers to build the code with their integrated development environment of choice.
  
We try to [[Why Closed-Source Is Wrong|avoid]] plugins without sources, but even those are not tracked in <Fiji-root>/plugins/, but rather in [http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=fiji.git;a=tree;f=staged-plugins;hb=HEAD <Fiji-root>/staged-plugins].  The reason is that we would want to provide our very own ''plugins.config'' files with them, i.e. we want to have custom locations/names of the plugins contained in the ''.jar'' file.
+
Plugins maintained in Maven projects consist of
  
Such ''plugins.config'' files that are to be inserted in certain ''.jar'' also live in ''staged-plugins'', as ''<basename-of-jar>.config''.  Example: the plugins.config for ''VIB_.jar'' is stored in [http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=fiji.git;a=blob;f=staged-plugins/VIB_.config;hb=HEAD <Fiji-root>/staged-plugins/VIB_.config].
+
# a pom.xml file in the top-level directory
 +
# the Java sources in the ''src/main/java/'' directory, and
 +
# the ''plugins.config'' file in ''src/main/resources/''
  
The sources for many plugins shipped with (and maintained in) Fiji live in [http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=fiji.git;a=tree;f=src-plugins;hb=HEAD <Fiji-root>/src-plugins].  The subdirectories in ''src-plugins'' mostly correspond to the basename of the .jar file generated from it.  Example: the sources of ''plugins/Fiji_Updater.jar'' are stored in [http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=fiji.git;a=tree;f=src-plugins/Fiji_Updater;hb=HEAD <Fiji-root>/src-plugins/Fiji_Updater/].
+
If the plugin sources contain unit tests, their sources are in ''src/test/java/'' so that the generated test classes will not be included in the final ''.jar'' file.
  
 
== Libraries ==
 
== Libraries ==
  
Some plugins require third-party libraries such as ''Jama''.  Such libraries are not stored in ''plugins/'' (lest an underscore in their filenames would make ImageJ mistake them for plugins), but in ''jars/'' instead.
+
Most libraries are available as regular [[Maven]] dependencies (you can [http://search.maven.org/ search for them on Maven Central]).
 
 
Some of the libraries' sources are stored in ''src-plugins/'' (in subdirectories corresponding to the basename of the respective ''.jar'' file).
 
  
 
== Submodules ==
 
== Submodules ==
  
Some components of Fiji are stored in ''submodules'', i.e. in [[Git]] repositories of their own right. This is the case for [[ImageJA]], many third-party libraries, and some plugins collections that existed before Fiji, such as [[TrakEM2]] or VIB.
+
Fiji used to maintain relationships with projects developed outside the ''fiji.git'' repository via Git submodules. This proved too cumbersome and too unintuitive for the affected parties.
  
These submodules are subdirectories in the <Fiji-root>, and they may, or may not, be checked out.
+
All submodule couplings are now replaced by proper [[Maven]] dependency management.
 
 
Every submodule is "committed" at a certain revision, i.e. Git not only records where, say, ImageJA is to be cloned from, but also what revision is current for any given commit in ''fiji.git''.
 
 
 
If submodules are checked out, you can cd into the respective directories and work with them as with other Git repositories.
 
 
 
Our policy, however, is that you do not need to check out the submodules if you do not want to work <u>on</u> them: the result of the most recently committed revision needs to be committed as binary in [http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=fiji.git;a=tree;f=precompiled;hb=HEAD <Fiji-root>/precompiled/].  For example, the ''.jar'' file generated from the ''VIB'' submodule is committed as ''precompiled/VIB_.jar''.
 
  
 
== The Fiji Build system ==
 
== The Fiji Build system ==
  
For historical reasons, the Fiji Build system's source code lives in ''<Fiji-root>/fake/Fake.java''.  It will be compiled into ''<Fiji-root>/fake.jar''.
+
Fiji used to have its home-brewn build system. We switched to using [[Maven]] in 2012, though.
  
To avoid a chicken-and-egg problem, a ''fake.jar'' that can compile the current Fiji Build system is committed to ''precompiled/'' (and for the same reason, precompiled versions of the Fiji launchers for all supported platforms live there, too).
+
For convenience, there is a {{GitHub|org=scijava|repo=minimaven|label=''Mini Maven''}} project that allows building Fiji without a full-blown Maven; however, for serious development, real Maven, or even better, Eclipse or Netbeans is recommended.
  
== The ''precompiled/'' directory ==
+
For backwards-compatibility, ''Mini Maven'' can be called via '''./Build.sh''' in the top-level directory of a ''fiji.git'' checkout. Despite the name, it does not really build anything, but only draws in all Fiji components as [[Maven]] dependencies.
 
 
Precompiled versions of all ''.jar'' files generated from submodules, of ''fake.jar'' and of the Fiji launchers live in ''precompiled/''.
 
  
 
== The ''bin/'' directory ==
 
== The ''bin/'' directory ==
Line 49: Line 43:
 
Quite a few tasks -- such as committing a new submodule or sources for a plugin, or releasing a new version of Fiji -- are performed by scripts.  These scripts live in the ''<Fiji-root>/bin/'' subdirectory.
 
Quite a few tasks -- such as committing a new submodule or sources for a plugin, or releasing a new version of Fiji -- are performed by scripts.  These scripts live in the ''<Fiji-root>/bin/'' subdirectory.
  
Some of these scripts are shell scripts, others are Jython scripts with special [http://en.wikipedia.org/wiki/Shebang_(Unix) shebang] lines which trigger them to be called with the current Fiji launcher.
+
Some of these scripts are shell scripts, others are Jython scripts with special [[wikipedia:Shebang (Unix)|shebang]] lines which trigger them to be called with the current Fiji launcher.
 
 
== The ''nightly-build/'' directory ==
 
 
 
We have a ''cronjob'' that builds Fiji every night, from then-current sources.  The responsible script is ''bin/nightly-build.sh''.
 
 
 
Of course, it might often be quite handy to do the same locally, i.e. compile from a completely pristine state (e.g. to ensure that your latest commit includes all necessary files).  You can easily do that by calling ''./bin/nightly-build.sh HEAD'', which will automatically create an appropriate ''nightly-build/'' subdirectory (if it does not exist yet), and simulate a from-scratch build.
 
  
 
[[Category:Development]]
 
[[Category:Development]]

Latest revision as of 09:02, 9 July 2019

This page will give you an idea how Fiji's source code is organized. Every directory referred to is relative to the Fiji root, i.e. the directory into which you cloned fiji.git.

The Fiji launcher

The Fiji Launcher is now called ImageJ launcher and lives in its own repository. It is built by Travis CI.

The plugins

The plugins served from Fiji's update site are all Open Source. The source code lives on GitHub, in repositories reflecting the name of the .jar file generated from the source code. Example: the source code for Fiji_Plugins.jar lives in https://github.com/fiji/Fiji_Plugins.

The only special rule applies for plugins whose file names end in an underscore: that underscore will be stripped. Example: the sources of Arrow_.jar are stored in https://github.com/fiji/Arrow.

All of our plugins are maintained as Maven projects; this allows developers to build the code with their integrated development environment of choice.

Plugins maintained in Maven projects consist of

  1. a pom.xml file in the top-level directory
  2. the Java sources in the src/main/java/ directory, and
  3. the plugins.config file in src/main/resources/

If the plugin sources contain unit tests, their sources are in src/test/java/ so that the generated test classes will not be included in the final .jar file.

Libraries

Most libraries are available as regular Maven dependencies (you can search for them on Maven Central).

Submodules

Fiji used to maintain relationships with projects developed outside the fiji.git repository via Git submodules. This proved too cumbersome and too unintuitive for the affected parties.

All submodule couplings are now replaced by proper Maven dependency management.

The Fiji Build system

Fiji used to have its home-brewn build system. We switched to using Maven in 2012, though.

For convenience, there is a Mini Maven project that allows building Fiji without a full-blown Maven; however, for serious development, real Maven, or even better, Eclipse or Netbeans is recommended.

For backwards-compatibility, Mini Maven can be called via ./Build.sh in the top-level directory of a fiji.git checkout. Despite the name, it does not really build anything, but only draws in all Fiji components as Maven dependencies.

The bin/ directory

Quite a few tasks -- such as committing a new submodule or sources for a plugin, or releasing a new version of Fiji -- are performed by scripts. These scripts live in the <Fiji-root>/bin/ subdirectory.

Some of these scripts are shell scripts, others are Jython scripts with special shebang lines which trigger them to be called with the current Fiji launcher.