From Van Essen Lab

Jump to: navigation, search


Development Tools Used for Caret6 Development

Install tools in the order in which they are listed.


Java 6 is required for Caret6.

Java is pre-installed on Macs. Use Software update to check for new versions. Windows and Linux users should download Java from


Mercurial is used for source code control. Download from and install so that "hg" is in the user's path.

  • Read the Mercurial book.
  • Mercurial and Eclipse example.

In your home directory, create the file ".hgrc" and add the following text to it (with your name and email address):

username =  FirstName LastName  Email-Address

With mercurial, there is a directory ".hg" which is created by Mercurial in the root directory of the project. In addition, uses may create a file in the root directory (same directory as ".hg") name ".hgignore". By default, Mercurial considers all files anywhere in and under the root directory as candidates for version control. ".hgignore" tells Mercurial which files should be ignored by Mercurial and are not candidates for source control. Examples of undesired files are object files and executables.

Mercurial is a distributed version control systems (DVCS). With Caret source code, there is "central" repository. Developers will clone this central repository, make source changes, commit the changes to their cloned repositories, pull updates made by others from the central repository, and push their changes to the central repository. The "hg" command may be executed anywhere in the projects directory tree.

Common Mercurial Commands

  • hg help will list all of the commands.
  • hg add is used to add new files to the repository..
  • hg clone is used to clone a repository.
  • hg commit is used to commit changed files to a repository.
  • hg incoming lists changes made to the central repository that are not present in the cloned repository.
  • hg log lists committed changes that have been made to a repository.
  • hg outgoing lists changes made to a cloned repository that are not part of the central repository.
  • hg init creates a repository.
  • hg pull gets changes that are in the central repository but not yet in the cloned repository (these changes are typically made by others.
  • hg push puts changes in the cloned repository into the central repository.
  • hg status Lists changes that have been made but not committed to the repository.


Maven is build system (somewhat analogous to Make) that is used to build Caret6 from the command line.

  • Download Maven binary distribution from
  • Unzip in /usr/local.
  • Create a symbolic link /usr/local/maven to /usr/local/apache-maven-2.2.1 (or wherever it is installed). Set the environment variable M2_HOME to "/usr/local/maven" and M2 to $M2_HOME/bin. When updating maven, just update the symbolic link to point to the new installation.
  • Maven Documentation.

Read the Maven User Guide.


Maven Lifecycles:

  • mvn clean - Clean the project.
  • mvn compile - Compile the project.
  • mvn test-compile - Compile the project's test code.
  • mvn test - Run project's tests.
  • mvn package - Build the Caret packages.
  • mvn install - Install into local repository for use with other projects.
  • mvn site - Generate documentation for project.


Eclipse is an integrated development environment (IDE).

To install eclipse, download Eclipse IDE for Java Developers from and unzip in the desired directory (/Applications on Mac). Find the executable and draw to Finder (Mac) or set PATH environment variable.

Install the Maven plugin for Eclipse.

Install the Mercurial plugin for Eclipse

  • Select Help->Install New Software and enter to install the Mercurial plugin. Check all but Obsolete. If not on Windows, click the triangle on the left of Mercurial Eclipse and uncheck Windows Binaries for Mercurial. Restart Eclipse. If there is an error with text "hg -y debuginstall", click OK. Go to Preferences->Team->Mercurial and enter the full path to "hg" in the Mercurial Executable text box.

Install FindBugs

  • Select Help->Install New Software and enter Install it. Run it from the projects context menu (run from menu when project is right-clicked).

Add C++ Support




Add "-agentlib:hprof=cpu=samples,interval=1" as an argument to the java virtual machine (java command). After the program terminates, a file named "java.hprof.txt" is created. The last section of this file lists the percent of execution time in classes and methods.

Caret Packages

All Caret packages follow the "reversed-domain-name" convention. Thus, all Caret packages are in the "edu.wust.caret" domain.

  • edu.wustl.caret.brain - Contains classes for brain structures, surfaces, and volumes and related algorithms.
  • edu.wustl.caret.commandline - Contains classes for command line operations.
  • edu.wustl.caret.common - Contains classes for "utility-like" functions such as mathematical, string, and system operations along with other classes that are used by the other packages in Caret6.
  • edu.wustl.caret.desktop - The Caret6 desktop application.
  • edu.wustl.caret.files - Contains classes for reading and writing data files. Also contains some algorithms that operate on files.
  • edu.wustl.caret.giftijlib - Contains classes for reading and writing GIFTI data files.
  • edu.wustl.caret.gui - Contains classes for the graphical user-interface.
  • edu.wustl.caret.guiswingworker - No longer used?
  • edu.wustl.caret.statisticalalgorithm - Contains classes that perform statistical tests. These classes are separate from the statistics package to that this package can be used by both the brain and statistics packages and avoid circular dependencies.
  • edu.wustl.caret.statistics - Contains classes that perform statistical operations on data files.
  • edu.wustl.caret.web - The Caret6 Java Applet that runs in a web browser.
  • edu.wustl.caret.wuswing - Java Swing-based classes for user-interface development.

External and Third-Party Libraries

  • JOGL - This is the Java OpenGL libraries.
  • Wizard - This package is used by "wizard" dialogs, that is, dialogs that are a sequence of pages.

Creating a Caret6 Development Environment

Also see Development QuickStart

Get the Source Code and Other Required Files

  • Create a new directory named "caret6_development" and change into the new directory.
  • Get the Caret6 Source code by running one of the following commands:
    • hg clone <path-to-hippocampus>/DS4600/REPOSITORIES_SOURCE_CODE/caret6/caret6_source ./caret6_source
    • hg clone ssh:// ./caret6_source
  • Copy the file "<path-to-hippocamps>/DS4600/REPOSITORIES_SOURCE_CODE/caret6/" to the directory that contains "caret6_source".
  • Unzip the

The current directory should now have three subdirectories.

  • caret6_source contains the source code.
  • distributions contains files for assembling the Caret6 and WebCaret6 distributions.
  • libraries_external contains java libraries used by Caret6.

Build the Source Code

  • Change into the caret6_source directory.
  • Run the command "mvn clean".
  • Run the command "mvn package".

Create Executables

  • Change into the parent directory (caret6_development) and then change into the directory "distributions/caret6_deploy".
  • Run the command "./" which creates a file named This ZIP file contains script files for running on each platform (in the "bin_*" directories), the Java classes (in the "jars" directory), and JOGL libraries for each platform (lib_jogl).
  • All Caret programs are contained in one JAR file located in the "jar" directory. Programs and the names of their "main" classes are:
    • caret6 - edu.wustl.caret.desktop.DesktopCaret.
    • caret6_command - edu.wustl.caret.commandline.commandLineMain.
    • caret6_stats - edu.wustl.caret.statistics.StatisticMain
    • WebCaret (runs as Java Applet in a Web Browser) - edu.wustl.caret.web.WebCaret.

Test Executables

  • Change into the directory "caret6".
  • Change into the "bin_" directory that matches your operating system.
  • Run each of the command files in the directory to verify that they run without crashing.

Start and Setup Eclipse

  • Start Eclipse.
  • When asked for a "Workspace", set the workspace with the path to and including the "caret6_source" directory.
  • Select Preferences from File Menu (Eclipse Menu on Mac OSX).
  • Select General->Workspace.
    • Check Save Automatically Before Build.
  • Select General->Editors->Text Editors.
    • Check Insert Spaces for Tabs.
    • Check SHow Line Numbers.
  • Select Java->Code Style->Code Templates.
    • Select Comments->Files. Press the Edit button and enter the text with copyright as shown below.
    • Near the bottom of the dialog, select the checkbox next to Automatically Add Comments fro New Methods and Types.
  • Select Java->Editor->Folding.
    • Deselect Enable Folding.
  • Select Java->Code Style->Organize Imports. Press the New button and enter "edu".
  • Select Java->Compiler->Errors/Warnings.
    • Open Potential Programming Problems
      • Set Serializable Class without serialVersionUID to Ignore.
      • Set Possible Accidental Boolean Assignment to Warning.
      • Set Switch Case Fall Through to Warning.
      • Set Null Pointer Access to Warning.
  • Select Java->Installed JREs.
    • Check JVM1.6.0 (or newest) and deselect all others.
  • Select Java->Installed JREs->Execution Environment.
    • In the left section, select JavaSE-1.6. In the right section check JVM 1.6.0 and uncheck all others.
  • Select Java->Code Style->Formatter.
    • Press the Edit.. button in top right.
    • Select the Indentation tab. Remove "[built it]" from Profile Name.
    • Set Tab Policy to Spaces Only and set both tab size and indentation size to 4.
    • Do this for both the Java Conventions and Eclipse Conventions.
  • Press the OK button to close the preferences dialog. Answer No to Full Build pop-up.
  * Copyright 1995-2010 Washington University School of Medicine.
  * CARET is free software
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <>.

Create Eclipse Projects

Create the Projects:

  • In Eclipse, select File Menu->New->Project.
  • In the New Project:Select a Wizard Dialog, select Java->Java Project. Press the Next button.
  • In the New Java Project:Create a Java Project Dialog, select Create a Project from Existing Source in the Contents section. Press the Browse button and choose the path to the <path>/caret6_source/giftijlib directory. This should result with giftijlib as the name.
  • Press the Finish button.
  • Most of the projects will need to have other projects added to the Build Path. The projects that need to be added to the build paths are listed below.
    • Right-click the name of the project in the Package Explorer Window on the left.
    • From the pop-up menu, select Properties.
    • In the Properties Dialog:
      • Select Java Build Path.
      • Press the Projects tab.
      • Press the Add button.
      • Check the box next to the needed projects. Press the OK button.
      • Press the OK button on the Properties dialog.
  • Repeat these steps for each project in this order giftijlib, common, files, statisticalgorithm, brain, statistics, wuswing, gui, commandline, web, desktop.

  • It may be necessary to change the default output path for class files.
    • Right click the project and select Properties.
    • Select Java Build Path in the left column.
    • Click the Source tab at the top of the dialog in the right portion.
    • At the bottom of the page, change the Default Output Folder to <project-name>/target/classes.

  • The projects should be created in the following order. The projects that need to be added to the build path are listed to the right of the dash character.
    • common - giftijlib
    • files - common, giftijlib
    • statisticalgorithm - common, files, giftijlib
    • brain - statisticalgorithm, common, files, giftijlib
    • statistics - brain, statisticalgorithm, common, files, giftijlib
    • wuswing -
    • gui - brain, statisticalgorithm, common, files, giftijlib, wuswing
    • desktop - gui, brain, statisticalgorithm, common, files, giftijlib, wuswing
    • commandline- rain, statisticalgorithm, common, files, giftijlib
    • web - gui, brain, statisticalgorithm, common, files, giftijlib, wuswing

Some projects need external libraries added. To add an external library:

  • Right-click the project name.
  • Select Properties from the menu.
  • In the Properties dialog:
    • Select Java Build Path
    • Click the Libraries tab.
    • Press the Add External JARs button. Select the need JAR files from the "external_libraries" directory in caret6_development.
    • The projects desktop, gui, and web need libraries_external/jogl/lib/jogl.jar, libraries_external/jogl/lib/gluegen-rt.jar, libraries_external/wizard/wizard.jar.

To run Caret6 from within Eclipse:

  • Right-click desktop in the Package Explorer window.
  • Select Properties from the menu.
  • In the Properties dialog:
    • Select Run/Debug Settings.
    • Click DesktopCaret and press the Edit button.
    • Click the Argument tab.
      • In the VM Arguments section, add "-Xmx2g".
    • Press the Environment tab.
      • Press the New button. Enter the environment's library path variable (MacOSX: DYLD_LIBRARY_PATH, Linux: LD_LIBRARY_PATH, Windows: PATH) for the name and in the value, enter the full path to <path>/caret6_development/distributions/caret6_deploy/caret6/lib_jogl/<JOGL-FOR-COMPUTER>/lib.
    • Press the Classpath tab.
      • Click the mouse on the User Entries line.
      • Press the Add Projects button and select these projects: brain, common, files, giftijlib, gui, statisticalgorithm, wuswing.
      • Press the Add External JARs button. Navigate to the <path>/caret6_development/libraries_external/jogl/lib directory and select both jogl.jar and gluegen-rt.jar.
      • Press the Add External JARs button. Navigate to the <path>/caret6_development/libraries_external/wizard directory and select wizard.jar.
      • Press the OK button.
    • Press the OK button to close the Preferences dialog.
  • Select the project (desktop) in the Package Explorer window and then select Run Menu->Run and/or Run Menu->Debug.

Using Mercurial with Caret6

It is probably easiest to operate with Mercurial on the command line rather than through Eclipse's Mercurial plug-in.

From the caret6_source directory:

  • Run hg status to see what changes you have made that have not been committed to your repository.
  • If files have been added or remove, run hg addremove.
  • To commit changes to your repository, run hg commit -m "<comment describing changes>.
  • To see if the central repository has been changed by other users, run hg incoming. If changes have been made by others, run hg update to update your repository with changes from the central repository. If necessary, run hg merge to combine your changes with changes from the central repository. If needed, recommit and changes as a result of merging.
  • Run hg push to push changes from your repository to the central repository.
  • Run hg update to verify that your repository and the central repository do not differ.

Multi-Structure Organization

  • Brain - Contains that are independent of BrainStructures and contains BrainStructures.
  • BrainStructure - Contains files that model a single structure such as a cerebral hemisphere or the cerebellum.

Coding Conventions

  • Follow Sun's Java Code Conventions.
  • Write comments that support the Javadoc Tool.
  • Declare one variable per line.
  • For variable naming, do not use underscores and always start a variable name with a lower-case letter. If the variable name consists of multiple words start the second and additional words with a capital letter.
  • Like class naming, do not use underscores and all words in the class name, including the first, start with a capital letter.
  • Use meaningful names for variables. Avoid names like temp. Use of i, j, etc. for loop counters is acceptable.
  • Do not declare a variable until it is needed. A possible exception is variables that require a heap allocation inside a loop that is iterated many times.
  • Use plenty of parenthesis for both logical and mathematical statements for clarity and to make precedence obvious.
  • Use a for loop statement when looping with iterators for (Iterator<String> iter = collection.iterator(); iter.hasNext(); ) {. This limits the scope of the iterator to the loop.
  • Use a for loop statement when looping through and reading the elements of an array for (int value : anArray) {.
  • Use plenty of comment indicate the intended function of the code.
  • Use blank lines to break up the code.
  • Use "this." when accessing member variable and methods.
  • For method parameters, try to use Enums in place of boolean flags.


If an Exception class is crated, always add a constructor that accepts any Exception. This makes the stack trace available for locating the cause of the error.

   * Constructor that uses stack trace from the exception
   * passed in as a parameter.
   * @param e Any exception whose stack trace becomes
   * this exception's stack trace.
  public SomeException(Exception e) {

When an exception needs to change type, pass the exception, not exception.getMessage() to the constructor.

Do this:

  new SomeException(otherException);

NOT this:

  new SomeException(otherException.getMessage());

Performance Tips

Avoid Memory Allocations in Loops

While it is best to limit the scope of variables, such as array in this example:

   for (i = 0; i < infinity; i++) {
       float[] array = object.getXYZ();

Allocating array many times can greatly harm performance. Moving array outside of the loop may greatly improve performance:

   float[] array = new float[3];
   for (i = 0; i < infinity; i++) {
       ...more code

ArrayLists for Primitive Types

Do not use ArrayList<Integer> and ArrayList<Float>. Instead, use ArrayListInt and ArrayListFloat from the common package.

Do Not Implement the Clonable Interface

Instead of implementing the Cloneable Interface for a class, create a copy constructor.

Avoid Multi-Dimensional Arrays

When possible, use a one-dimensional array instead of multi-dimensional arrays. Accessing multi-dimensional arrays many times is slow than access of a one-dimensional array.

Avoid Repeatedly Making Heap Memory Requests

Instead of:

for (int i = 0; i < N; i++) {
    float[] xyz = object.getXYZ()

Do this:

float[] xyz = new float[3];
for (int i = 0; i < N; i++) {

Cloning Multi-Dimensional Arrays

int[][] a = new int[3][3];

Note that a.clone() only clones the first dimension of the array, not both dimensions.

Use StrictMath not Math

When a mathematical function is needed, use java.lang.StrictMath, not java.lang.Math. StrictMath produces the same results in all Java Virtual Machines whereas Math may vary.


Include our lab's copyright statement at the top of each source code file.

  * Copyright 1995-2010 Washington University School of Medicine.
  * CARET is free software
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * GNU General Public License for more details.
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <>.

GUI Development


  • Create modal dialogs as a subclass of WuDialogModal.
  • When a modal dialog is needed for data entry, use WuDataEntryDialog.
  • Create non-modal dialogs as a subclass of WuDialogNonModal. Non-modal dialogs should be maintained by GuiNonModalDialogManager so that the dialogs are updated as data is changed.

Layout Managers

With the exception, of BorderLayout, avoid using the AWT and Swing layout managers which are poorly designed and difficult to use.

In Swing, layout manages are added to JPanel objects. The WuSwing package contains objects that are a combine a JPanel with a GridLayout and greatly simplify the building of user-interfaces. This "layout-panels" are based on the QT layouts QBoxLayout and QGridLayout.

  • WuPanelLayoutBox - Used for placing components in a single horizontal row or single vertical column. Use the class' factory method to create a horizontal or vertical layout panel.
  • WuPanelLayoutGrid - Used for placing components into a grid with varying row height and column widths. Use the class' factory method to create a grid layout panel.


Use WuSpinnerInt and WuSpinnerFloat for integer and floating-point spinner components. These classes encapsulate the JSpinner class and ease the creation of spinners.


Instead of "print" statements, use the CaretLogger.

Eclipse Caret C++ Development

Creating an Eclipse C++ Project

This example uses the caret_common directory which, in this example, is "/Users/john/caret5_development/caret5_eclipse/caret_source/caret_common".

Set Environment Variables

  • Open Eclipse's Preferences.
  • Click the triangle to the left of C/C++

Create the Eclipse Project

  • Start Eclipse. It will ask you to select a workspace. I entered "/Users/john/caret5_development/caret5_eclipse/workspace" and pressed the OK button.
  • Select File Menu->New->Project.
  • Click the triangle next to C/C++. Select C++ Project and press the Next Button.
  • Set the project name to "caret_common". Uncheck the Use default location checkbox, press the Browse button and select the caret_common directory (/Users/john/caret5_development/caret5_eclipse/caret_source/caret_common). Click the triangle next to Makefile project. Select Empty Project. In Toolchains, select the appropriate compiler (MacOSX GCC on Mac OSX). Press the Next button.
  • Press the Finish button.
  • When asked "This kind of project is associated with the C/C++ perspective. Do you want to open this perspective now? Choose Yes.
  • Click the triangle next to caret_common in Project Explorer. You should see the source code files.

Using Mercurial for Source Control

  • Go to the root directory of the project.
  • Run: hg init .
  • Run: hg addremove
  • Run hg commit -m "Creating repository"

These command will create the repository, add all files in the directory tree to the repository, and commit the added files to the repository.

How to Get Caret5 Source Code From Command Line

  • You must have an account on hippocampus with "hg" (/usr/local/bin/hg) in your path. On your computer, "hg" must be in your path.
  • From your computer:
    • Change into the directory that will be the parent directory of caret5 source code directory.
    • hg clone ssh:// ./caret5_source
    • cd ./caret5_source
    • hg log # This command will list the history of changes to the repository

How to Get Caret5 Source Code Using Eclipse

This requires hippocampus DS4600 disk mounted on your computer (path = /Volumes/DS4600)

  • Start Eclipse
  • Set the eclipse workspace to a directory in the same directory into which the repository is cloned.
  • Select File Menu->New Project.
  • Right-click the arrow to the left of Mercurial and select Clone Existing Mercurial Repository.
  • In URL enter, Volumes/DS4600/REPOSITORIES_SOURCE_CODE/caret5/caret5_source.
  • Verify that Checkout as a project(s) in the workspace is checked.
  • Verify that clone directory name is caret5_source.
  • Press the Next button.
  • Select the desired revision and press the Next button.
  • Select all of projects and press the Finish button.

Create Makefiles and Build

  • Go into the caret5_source directory.
  • Run "make rebuild" to build the source.

Building in Eclipse

  • Go into the caret5_source directory.
  • Run "make qmake-static" to create the Makefiles.
  • For each project:
    • Select project, right-click->Make Targets->Build.
    • On Make Targets dialog, press Add.
    • On Create Make Target dialog, enter Target name "all", press OK.
    • Back on Make Targets dialog, select "all" and press Build.
Personal tools
Sums Database