- About XNAT
- News & Events
- XNAT Marketplace
- Contact Us
Create the basic structure required to build and expand your XNAT plugin project.
For XNAT 1.7, we provide support for creating plugins using the Gradle build tool. Gradle is a command-line build tool similar to earlier build tools like Ant or Maven, but provides a more easily accessible build model, can be easily extended through the use of its own plugin architecture, and is widely supported by most modern development tools.
The word "plugin" can get a lot of usage in a lot of different contexts:
Generically these functions are very similar: plugins allow tools to expand beyond their core set of functions. Understandably, which type of plugin is being discussed in a particular situation can be very confusing. We'll try to make it clear the context in which we're using the term when it becomes ambiguous.
To get started, create a folder where your plugin development will go, then change your current directory to that folder.
Once you're there, there are–theoretically anyway–a few ways you can start your new plugin project:
However, given the requirements for building XNAT plugins, it's easiest to simply copy an existing project. Or, at least, copy the build files from an existing project.
If you want to copy over an existing plugin project, start with the XNAT workshop plugin project (which is basically the end result of what you'll create through the steps of this practical session). Once you've copied this repository to your new project, delete the folders src and .git (if you downloaded the project instead of cloning it with Git, you may not have the .git folder). This will leave you with something like this:
$ ls LICENSE.txt README.md build.gradle gradle/ gradlew* gradlew.bat settings.gradle
These files can all be useful to you for your new plugin:
As discussed above, copying the workshop project provides you with the bootstrap wrapper and scripts. This takes the place of installing Gradle separately on your system. If you are starting with just the build files, you'll need to install Gradle on your system and have the gradle command available on your system path.
Once you have these files in place, start by editing settings.gradle. This file can be very important in Gradle builds, especially multi-project structures, but for a basic project usually just contains the name of the primary build target for the project. The workshop plugin's version of this file contains the following text:
rootProject.name = 'xnat-workshop-plugin'
You should change this to another name, e.g. my-workshop-plugin or something similar, to distinguish it from the prepared workshop plugin project.
The build.gradle file contains a lot of information and does a lot of important work. However, describing the full scope of the Gradle build tool and all of its configuration options is beyond the scope of this practical, since it would basically become a description of Gradle. As such, this page discuss in detail only those parts that are of direct interest and gloss over the rest. If you have a question about a particular aspect of the build file that's not addressed, feel free to ask a member of the XNAT development team or leave a comment on this page and we'll do our best to respond.
It's also worth noting that, as the XNAT 1.7 build process matures, much of the configuration that's currently required will be implemented through custom build logic, so future versions of XNAT plugin build files should hopefully be more compact and simpler.
Now let's look at build.gradle. There are a number of interesting parts of this file:
That's a lot of information, but once you have your main build file set up, you'll rarely need to change much more than the dependencies as you add new functionality that requires other supporting libraries. For your first few steps at customization, you won't need most of what's specified in the dependencies block here, but eventually you will, so go ahead and leave them in.
If you started with the XNAT workshop module project, you'll already have the Gradle wrapper as part of your project. If you just copied the build files, you should go ahead and create your own Gradle wrapper (as noted earlier, this requires having Gradle installed and accessible on your system). Just run the following command:
$ gradle wrapper
If you look at the contents of your build folder now, you'll see that you have the same gradle folder and gradlew and gradlew.bat scripts there.
Now you should initialize the wrapper by running the gradlew script:
This may take a little bit of time to complete since, if you haven't ever run this, the wrapper script will go and download an installable jar containing the Gradle engine. Once this has completed, you'll see a help message displayed.
The last step is to import your new Gradle project into your preferred development environment:
JetBrains provides two versions of its IntelliJ IDEA development environment: there is a freely available IntelliJ IDEA Community Edition and a commercial IntelliJ IDEA Ultimate Edition, which has a 30-day free trial, both of which are available from the IntelliJ IDEA download page. These instructions show the Ultimate Edition but the process to import a Gradle project is pretty much identical in both environments.
To import your Gradle project, select Import Project from the opening splash screen:
Or, if you already have IntelliJ IDEA open, you can select File->New...->Project from Existing Sources:
In either case, the Select File or Directory to Import dialog will appear:
Navigate to your new project folder, select the build.gradle file, and click the OK button. IntelliJ IDEA will process the Gradle configuration and create a new project.
There are a number of gradle plugins, but a common one is http://gradle.org/eclipse/. Once you've integrated that plugin, you can easily import the project using File -> Import -> Gradle -> Gradle Project
Then specify the directory where your build.gradle script is located...
Your project should now be available for use in Eclipse.
You now have a working Gradle build structure around which you can build your XNAT plugin project.