BoneJ is open to new development. Most development follows the philosophy of Fiji's PlugIn design guidelines.
The primary source code reference is BoneJ's master branch at GitHub.
These instructions help you set up a development environment using the Eclipse IDE
and Git version control.
EGit, plus Eclipse, plus GitHub presents a bit of a moving target for this sort of documentation, so please get in touch if you find that something doesn't work as expected.
If you are unfamiliar with Git, please take the time to read these tutorials before starting:
This guide will use GUI tools (Eclipse, EGit and your web browser) as far as possible, but you can use the command line if you like to live on the edge.
- Install Git (optional, if you want command-line control)
- Download and install Eclipse IDE for Java Developers.
- In Eclipse, install EGit:
- Help->Install New Software...
- Work with: http://download.eclipse.org/egit/updates
- If Eclipse complains that the site is a duplicate, hit the "Available Software Sites" link, and select Egit from the list that appears
- Tick all of the the Collaboration, Eclipse Git Team Provider and JGit items and install them.
- Restart Eclipse
- Take a quick look at the EGit User Guide
- Right click in Eclipse's Package Explorer
- Import > Git > Projects from Git > Next...
- type filter text: https://github.com/fiji/imagej1.git, hit Next, hit Finish
- In the Create a Java project wizard, select Java > Java Project, hit Next
-
- Project name: imagej, make sure that the repo will clone into a subdirectory of your workspace, e.g. ~/workspace/imagej/
- Finish.
- Select the imagej project you just created, Right Click, Team > Share Project
- Select a repository type, Git, Hit Next
- Check "Use or create repository in parent folder of project", click the imagej row, hit the Create Repository button, hit Finish
- Select "Use the New Projects wizard" and "Try to share new projects automatically", Finish
- Your imagej project now has a yellow icon on it showing it has a repository but says NO-HEAD
- Right click, Team > Remote > Fetch From... Next
- Hit the Add All Branches Spec and Add All Tags Spec buttons, hit Finish
- Eclipse will download all the code, should take a few seconds on broadband
- But you need to check it out into a new branch, your local 'master'
- Right click > Team > Switch to > New branch > Select refs/remotes/choose_remote_name/master from the dropdown
- Branch name: master
- Finish
- Configure your imagej project's build path to include tools.jar
- tools.jar is distributed with the JRE included with the 'full' version of ImageJ
- It's also included in the Java Development Kit (JDK) under {jdk directory}/lib/tools.jar or similar
- Once you've found it, right-click on your Eclipse ImageJ project -> Properties->Java Build Path->External Libraries->Add...
- The little red cross symbolising a compilation error will go away once tools.jar is properly linked
- You can get Wayne's latest code from the ImageJ repository by right clicking on the imagej project >Team >Fetch From... >Next >Finish
You need an SSH key pair so that GitHub knows it's you who's pushing to your repository.
- Eclipse > Window > Preferences > type 'ssh' > Select SSH2 in the left-hand list
- Key Management tab > Generate RSA Key...
- Enter a strong password (your key is only as good as your password)
- Click amongst the text that appears, Ctrl+A. Click Save Private Key... and save in the default location
- You want your Public key. You just saved a Private Key in an ssh
directory, probably ~/.ssh/ (the ~ is shorthand for home directory) - also in
there is a .pub file - your public key. Open the public key in a text editor like Notepad or gedit. Select all, copy.
- Go to https://github.com/account > SSH Public Keys > edit or Add another
public key > paste in the key
- Get an account at GitHub.
- Make your own fork of BoneJ by hitting "Fork" on the BoneJ repository
- Import your branch of BoneJ from GitHub into Eclipse
- Right click in Eclipse's Package Explorer
- Import > Git > Projects from Git > Next...
- type filter text: https://username@github.com/username/BoneJ.git , hit Clone
- In the next step, make sure that the repo will clone into a subdirectory of your workspace, e.g. ~/workspace/BoneJ/
- Next > Next > Finish. EGit will clone your BoneJ repository to your Eclipse workspace
- Select the BoneJ repository you just created, Next >
- Select "Use the New Projects wizard" and "Try to share new projects automatically", Finish
- Select "Java Project" from the list, Next >
- Enter the project's name, BoneJ, Finish
- Now download some external libraries
- Configure your BoneJ project's build path to include JUnit 4, imagej, ImageJ_3D_Viewer.jar, vecmath.jar, j3dcore.jar and j3dutils.jar
- Right-click on your Eclipse BoneJ project -> Properties->Java Build Path->External Libraries->Add... and add the .jar files
- Add your imagej project under the Projects tab (if you cloned the Git repository)
- or the ijxxxx.jar in the Libraries tab otherwise
- Add JUnit 4 under under Libraries tab -> Add Library... -> JUnit -> JUnit library version: JUnit 4
- The little red cross symbolising a compilation error will go away once all libraries are properly linked
- Configure a directory for unit tests, so they aren't included with BoneJ_.jar
- In the source tab, make sure that "Allow output folders for source folders" is checked
- The default output folder is BoneJ/bin
- Your unit test code is in the BoneJ/test source directory
- Select "Source folders on build path:" -> BoneJ/test [+] Output folder, click Edit
- Select Specific output folder, Browse, and create a new folder, testbin
- Your compiled unit tests will now be kept in BoneJ/testbin, and not included in BoneJ_.jar
- BoneJ can be automatically compiled with an Ant buildfile. An example from my system is here. You may have to right-click and save, then open in a text editor to see it.
You will need to change it to suit your environment. If you get stuck, try these instructions.
- Once you're building and testing your changes to BoneJ and you're happy
with your efforts, you can commit the changes to the local git repo (on
your hard drive)
- Then push your commits to your GitHub repo
- Right click->Team->Push To...
- Configured remote repository: origin: git+ssh://@github.com:username/BoneJ.git
- If your configured remote repository doesn't look like the one above and EGit refuses to connect, you have to add
a pushurl line to your .git/config file
- Next
- Source ref: master -> Add Spec -> Finish
- If you'd like your changes to be incorporated into BoneJ, send me a pull request.
Try to keep your work in a state that I can easily cherry-pick your commits into my integration branch using
Github's fork queue.
Acknowledgement
Many thanks to BoneJ's first collaborator Nick Powell (nmpowell), who tested earlier versions of these instructions
and contributed several important improvements.
This file last modified 1345hrs 29 May 2020 © Michael Doube 2004-2025 :: Designed to be interoperable and standards-compliant.
