Difference between revisions of "Downloading and Building Fiji From Source"

(Cloning source as unknown contributor: hint at using github.com for the initial clone)
(Add step about installing OpenJDK 8)
 
(38 intermediate revisions by 11 users not shown)
Line 1: Line 1:
== Downloading the Source Code with Git ==
+
{{FijiMenu}}The complete Fiji distribution of ImageJ consists of over a hundred individual components. Most of these components are ImageJ [[plugins]]; the rest are core libraries, [[scripts]] and several other resources (such as the [[:File:Fiji-icon.png|Fiji logo]] and the README).
  
''Warning: the source code for Fiji is rather large; make sure that you have two gigabytes of disk space free before beginning this.''
+
In the past, Fiji used to be built from one monolithic source code repository, which became unmanageable over time. These days, therefore, developers start from a fully-populated ''Fiji.app/'' directory and build only the parts they would like to change.
  
To fetch the Fiji source code you should use [http://git.or.cz/ git] (Windows users, please go [http://msysgit.googlecode.com here]).  If you are not familiar with Git, you might want to read [[Git mini howto|this page]] or [[:Category:Git|these pages]] instead.
+
= Download Fiji =
  
==== Cloning source as unknown contributor ====
+
The first step is the same for developers as it is for users: [[Downloads|Download]] Fiji, and unpack it. The Desktop is the recommended location.
Your first step should be to "clone" the fiji repository with the following command:
 
  
git clone git://pacific.mpi-cbg.de/fiji.git
+
= Install Java =
  
This should start downloading the base fiji repository and unpack it into a directory called "fiji" in your current directory.  Once this has successfully completed, change into the newly created "fiji" directory.
+
The next step is to install [https://adoptopenjdk.net/ OpenJDK 8]. You will need a JDK in order to develop Java code.
  
'''If this clone is slow''', you might want to try to clone from github.com, and after that switch back to the official repository:
+
= Check out and build individual plugins/libraries =
  
git clone git://github.com/dscho/fiji
+
To develop a plugin, the developer first needs to find out in which file it is contained. To do that, simply call the ''Command Finder'' (shortcut {{key press|Ctrl|L}}), type (part of) the label of the menu entry in whose function you are interested, and look at the ''File'' column.
cd fiji
 
git config remote.origin.url git://pacific.mpi-cbg.de/fiji.git
 
git pull
 
  
==== Cloning source as known contributor ====
+
Each individual component is maintained in its own repository in the [https://github.com/fiji/ ''fiji'' org on GitHub]. The name of the repository corresponding to a given ''.jar'' file is essentially identical with the file name, except that trailing underscores are stripped. Example: ''Stitching_.jar'' is maintained in the repository at https://github.com/fiji/Stitching, ''Time_Lapse.jar'' in the repository at https://github.com/fiji/Time_Lapse.
The above command creates a unknown contributor copy of Fiji in your computer. If you have your own user account in pacific.mpi-cbg.de, then you should clone fiji with the following command:
 
 
git clone ''username''@pacific.mpi-cbg.de:/srv/git/fiji.git
 
  
Just substitute ''username'' with your corresponding user name on that machine.
+
If in doubt about the location of the repository, just call {{bc | Plugins | Debug | System Information}} and find the section corresponding to the file in question.
  
=== Submodules ===
+
Once the developer has identified which plugin or library she wants to modify or develop further, it is very easy to build and contribute by following [[How to contribute to an existing plugin or library|this tutorial]].
  
Some plugins are managed as submodules.  If you want to work on them, you will have to initialize and update them.  (For more on submodules, see the [[Git submodule tutorial]].)  These submodules must be initialized and updated with the following commands:
+
== Example ==
  
git submodule init ImageJA TrakEM2 VIB micromanager1.1 mpicbg
+
Let's assume that we want to develop the Skeletonize3D plugin. Its source code is maintained at https://github.com/fiji/Skeletonize3D. The first step is to clone the source code:
git submodule update
 
  
The build system will attempt to use the system Java installation if it is available. However, on some platforms this may not work (or you may not have a recent enough Java installation) so we recommend that you also initialize and update the appropriate Java submodule for your system. To do this, run one of these commands:
+
<source lang="bash">
 +
$ git clone https://github.com/fiji/Skeletonize3D
 +
Cloning into 'Skeletonize3D'...
 +
remote: Counting objects: 115, done.
 +
remote: Compressing objects: 100% (58/58), done.
 +
remote: Total 115 (delta 46), reused 115 (delta 46)
 +
Receiving objects: 100% (115/115), 22.81 KiB | 0 bytes/s, done.
 +
Resolving deltas: 100% (46/46), done.
 +
Checking connectivity... done.
 +
</source>
  
git submodule init java/linux          # For 32-bit Linux systems
+
You only need to type the part after the ''$'' prompt, i.e you would type <code>git clone https://github.com/fiji/Skeletonize3D</code>. The rest is shown only for reference, so that you know what to expect.
git submodule init java/linux-amd64    # For 64-bit Linux systems
 
git submodule init java/macosx-java3d  # For MacOS X systems
 
git submodule init java/win32          # For 32-bit Windows systems
 
git submodule init java/win64          # For 64-bit Windows systems
 
  
Then update the submodules again with:
+
Then let's use the command-line Maven to build the project:
  
git submodule update java/<the-name-for-your-OS>
+
<source lang="bash">
 +
$ cd Skeletonize3D/
 +
$ mvn
 +
[INFO] Scanning for projects...
 +
[... lots and lots of interesting and useful information ...]
 +
[INFO] ------------------------------------------------------------------------
 +
[INFO] BUILD SUCCESS
 +
[INFO] ------------------------------------------------------------------------
 +
[INFO] Total time: 52.574s
 +
[INFO] Finished at: Tue Dec 02 10:27:00 CET 2014
 +
[INFO] Final Memory: 20M/81M
 +
[INFO] ------------------------------------------------------------------------
 +
</source>
  
 +
And finally, let's build the project and install it into the ''Fiji.app/'' directory:
  
Note: using <b>git submodule update</b> without specifying which submodule, will update <b>all</b> submodules. What <i>update</i> means: "put all submodules, if checked out, to the last commit that was committed in the fiji repos". Which is most likely not what you want--will put any submodule that you have been working on into a <b>(no branch)</b> situation. To fix it, just cd to that submodule <i>git checkout master</i> or whatever branch you were working on.
+
<source lang="bash">
 
+
$ mvn -Dimagej.app.directory=$HOME/Desktop/Fiji.app/ -Ddelete.other.versions=true
=== Getting a snapshot without Git ===
+
[INFO] Scanning for projects...
 
+
[... lots and lots of interesting and useful information ...]
If you insist on not using Git, you can download a snapshot of Fiji [http://pacific.mpi-cbg.de/cgi-bin/gitweb.cgi?p=fiji.git;a=snapshot;h=master;sf=tgz here], but you need to make sure that you have a new enough Java version installed.
+
[INFO]
 
+
[INFO] --- imagej-maven-plugin:0.5.4:copy-jars (copy-jars) @ Skeletonize3D_ ---
== Building Fiji from Source==
+
[INFO] Copying Skeletonize3D_-1.0.2-SNAPSHOT.jar to $HOME/Desktop/Fiji.app/plugins
 
+
[INFO] Deleted overridden Skeletonize3D_-1.0.1.jar
You should now be able to build Fiji with:
+
[INFO] Copying ij-1.49j.jar to $HOME/Desktop/Fiji.app/jars
 
+
[INFO] Deleted overridden ij-1.49m.jar
sh Build.sh run
+
[INFO] ------------------------------------------------------------------------
 
+
[INFO] BUILD SUCCESS
... which will invoke Fiji's multi-platform build system. If all goes well, after some time you should see the main Fiji window:
+
[INFO] ------------------------------------------------------------------------
 
+
[INFO] Total time: 21.331s
[[Image:Fiji-main-window.png|Fiji's main window]]
+
[INFO] Finished at: Tue Dec 02 10:30:02 CET 2014
 +
[INFO] Final Memory: 14M/81M
 +
[INFO] ------------------------------------------------------------------------
 +
</source>
  
 +
Of course, this assumes that you followed the suggestion and unpacked your Fiji onto the Desktop. If you unpacked it somewhere else, you ''have'' to adjust the command-line accordingly.
  
 +
Note that the exact dependency versions, as specified by the project in the ''pom.xml'' file, are copied into the ''Fiji.app/'' directory, possibly replacing other versions. You will want to make sure to use not-too-different versions from the current versions.
  
 
[[Category:Development]]
 
[[Category:Development]]
 +
[[Category:Fiji]]

Latest revision as of 09:15, 9 July 2019

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

The complete Fiji distribution of ImageJ consists of over a hundred individual components. Most of these components are ImageJ plugins; the rest are core libraries, scripts and several other resources (such as the Fiji logo and the README).

In the past, Fiji used to be built from one monolithic source code repository, which became unmanageable over time. These days, therefore, developers start from a fully-populated Fiji.app/ directory and build only the parts they would like to change.

Download Fiji

The first step is the same for developers as it is for users: Download Fiji, and unpack it. The Desktop is the recommended location.

Install Java

The next step is to install OpenJDK 8. You will need a JDK in order to develop Java code.

Check out and build individual plugins/libraries

To develop a plugin, the developer first needs to find out in which file it is contained. To do that, simply call the Command Finder (shortcut ^ Ctrl+L), type (part of) the label of the menu entry in whose function you are interested, and look at the File column.

Each individual component is maintained in its own repository in the fiji org on GitHub. The name of the repository corresponding to a given .jar file is essentially identical with the file name, except that trailing underscores are stripped. Example: Stitching_.jar is maintained in the repository at https://github.com/fiji/Stitching, Time_Lapse.jar in the repository at https://github.com/fiji/Time_Lapse.

If in doubt about the location of the repository, just call Plugins  › Debug  › System Information and find the section corresponding to the file in question.

Once the developer has identified which plugin or library she wants to modify or develop further, it is very easy to build and contribute by following this tutorial.

Example

Let's assume that we want to develop the Skeletonize3D plugin. Its source code is maintained at https://github.com/fiji/Skeletonize3D. The first step is to clone the source code:

$ git clone https://github.com/fiji/Skeletonize3D
Cloning into 'Skeletonize3D'...
remote: Counting objects: 115, done.
remote: Compressing objects: 100% (58/58), done.
remote: Total 115 (delta 46), reused 115 (delta 46)
Receiving objects: 100% (115/115), 22.81 KiB | 0 bytes/s, done.
Resolving deltas: 100% (46/46), done.
Checking connectivity... done.

You only need to type the part after the $ prompt, i.e you would type git clone https://github.com/fiji/Skeletonize3D. The rest is shown only for reference, so that you know what to expect.

Then let's use the command-line Maven to build the project:

$ cd Skeletonize3D/
$ mvn
[INFO] Scanning for projects...
[... lots and lots of interesting and useful information ...]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 52.574s
[INFO] Finished at: Tue Dec 02 10:27:00 CET 2014
[INFO] Final Memory: 20M/81M
[INFO] ------------------------------------------------------------------------

And finally, let's build the project and install it into the Fiji.app/ directory:

$ mvn -Dimagej.app.directory=$HOME/Desktop/Fiji.app/ -Ddelete.other.versions=true
[INFO] Scanning for projects...
[... lots and lots of interesting and useful information ...]
[INFO]
[INFO] --- imagej-maven-plugin:0.5.4:copy-jars (copy-jars) @ Skeletonize3D_ ---
[INFO] Copying Skeletonize3D_-1.0.2-SNAPSHOT.jar to $HOME/Desktop/Fiji.app/plugins
[INFO] Deleted overridden Skeletonize3D_-1.0.1.jar
[INFO] Copying ij-1.49j.jar to $HOME/Desktop/Fiji.app/jars
[INFO] Deleted overridden ij-1.49m.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 21.331s
[INFO] Finished at: Tue Dec 02 10:30:02 CET 2014
[INFO] Final Memory: 14M/81M
[INFO] ------------------------------------------------------------------------

Of course, this assumes that you followed the suggestion and unpacked your Fiji onto the Desktop. If you unpacked it somewhere else, you have to adjust the command-line accordingly.

Note that the exact dependency versions, as specified by the project in the pom.xml file, are copied into the Fiji.app/ directory, possibly replacing other versions. You will want to make sure to use not-too-different versions from the current versions.