Typical Development Environment for Contributors

Building with Eclipse

It is not necessary to build ClearTK with the following tools as you can do everything from the command line with git and maven clients. However, several core developers use Eclipse along with two plugins, subclipse and m2eclipse. Specifically:

Checking out and Compiling ClearTK in Eclipse

To check out ClearTK:

  1. Go to File -> Import… -> Git -> Projects from Git.
  2. Select URI and then click Next.
  3. Paste git@github.com:ClearTK/cleartk.git as the URI and then click Next.
  4. The master branch will be selected. Click Next.
  5. The default local storage directory should be fine. Click Next.
  6. Wait several minutes while the project is cloned.
  7. Make sure “Import existing projects” is selected and click Next.
  8. Click Finish.

You should now see the root cleartk project in your Eclipse workspace and all of its sub-projects. All of the sub-projects should successfully compile. Please close the cleartk project by right-clicking on it and selecting “Close Project”.

Running tests with Eclipse

All ClearTK module have tests defined in their src/main/test directory. To run them:

It is common for some tests to fail if you have limited memory or have not installed all the classifiers in your environment. To ignore known sets of problematic tests do the following:

Troubleshooting Eclipse Failures to Build

Sometimes you may find that the projects fail to build for no apparent reason. Here are some troubleshooting tips that you can try:

Sometimes Eclipse will complain that the persisted container within a project references a missing libraries. This is an issue with workspace resolution caused by mismatches between m2(eclipse) and Eclipse. To fix it try:

(This is assuming that you use the workspace resolution feature of the m2e plugin, which automatically handles inter-project dependencies between the ClearTK sub-projects. If you are not using this feature, or if you don’t have all of the ClearTK sub-projects in your Eclipse workspace, you’ll have to build manually with maven.)

Importing the consistent-versions-plugin project is not necessary for developing ClearTK. If you already have imported it and it is causing compile errors, then you can simply close the project as a way to ignore these errors.

Building on the Command Line

To build ClearTK on the command line, you’ll need to have Git and Maven installed. For those old schoolers out there, roughly speaking, Git is a replacement for the CVS version control system, and Maven is a replacement for the Ant build system. There is a wide variety of documentation for Git and Maven online, so here we just summarize the steps you need to get going with ClearTK.

Checking out ClearTK with Git

The ClearTK code is kept in a Git repository. To check out the code run:

git clone git@github.com:ClearTK/cleartk.git

This will create a cleartk directory in your current directory, and fill it with the contents of the ClearTK code base.

Compiling ClearTK with Maven

When you check out ClearTK from the Git repository you will almost always end up with a snapshot version (e.g. 0.5.0-SNAPSHOT). You can tell if you have a snapshot version by looking for <version>...-SNAPSHOT</version> in the pom.xml in the cleartk root directory.

Snapshot versions are not deployed to the ClearTK repository, so if you try to compile from a single sub-module (e.g. cleartk-ml), maven will not be able to find the dependencies (e.g. org.cleartk:cleartk-util:0.7.0-SNAPSHOT). However, the top level cleartk module knows about all the snapshot versions of the sub-modules cleartk-ml, cleartk-util, etc. Therefore, you can (should) always compile snapshot versions from the top level cleartk module using:

mvn compile

Running tests with Maven

From the top level cleartk module, run the standard:

mvn test

It is common for some tests to fail if you have limited memory or have not installed all the classifiers in your environment. See the contributor FAQ for details on how to skip problematic tests.