Building from source¶
Building software can be tricky, but hopefully this won’t be - thanks to Gradle.
The following instructions assume:
- You’re starting from scratch
- You’re not an expert in building software
If you are an expert, you’ll know which steps you can skip or amend.
Do you need this?!
Most people using QuPath won’t need to build QuPath from source! Just download an existing installer from qupath.github.io and use that instead.
Important
These instructions are for QuPath v0.2 only!
For later releases, switch to the latest version of the QuPath docs on ReadTheDocs.
Step 1: Installing prerequisites¶
Install a Java Development Kit (JDK)¶
QuPath v0.2 requires OpenJDK 14 (the exact version is important!).
There are a few places where you can find pre-built OpenJDK binaries – a popular source is AdoptOpenJDK.
Tip
During installation you may be asked if you want to add the JDK to your PATH. It usually makes things easier if you do.
If you can’t (e.g. because of some other Java software needing the PATH set to something else) I’m afraid I’ll leave resolving that up to you.
Warning
Problems have been reported on Linux using some JDK distributions. Switching to HotSpot (rather than OpenJ9) may help – see here for more details.
Step 2: Get the QuPath source code¶
You can get the source code for QuPath v0.2.3 from https://github.com/qupath/qupath/releases/tag/v0.2.3
Use the Source code (zip) or Source code (tar.gz) links.
Step 3: Build QuPath with Gradle¶
Open the QuPath source directory in a command prompt¶
You now need to unzip the source code subdirectory, then open a command prompt and navigate to the directory.
On Windows, the steps in more detail are
- Right-click on the source zip file, then choose the option to extract the contents
- Open a command prompt
- Type
cd
followed by a space in the prompt window, then drag the unzipped directory onto the window to have it automatically fill in the right path. - Press Enter
On a Mac, the process is similar except the command prompt is called Terminal.
Run gradlew¶
At the command prompt, type the following on Windows:
gradlew clean build createPackage
Or on macOS/Linux type
./gradlew clean build createPackage
This will download Gradle and all its dependencies, so may take a bit of time (and an internet connection) the first time you run it.
If all goes well, you should see a triumphant message that the build was successful.
Afterwards, you should find QuPath inside the ./build/dist
subdirectory. You may then drag it to a more convenient location.
Congratulations! You’ve now built QuPath, and can run it as normal from now on… at least until there is another update, when you can repeat the (hopefully painless) process.
Extras¶
Variations & troubleshooting¶
The code above should create everything you need to run QuPath.
If you want an installer instead, you can use
gradlew createPackage -Ptype=installer
Note that for this to work on Windows you’ll need to install WIX Toolset.
Inevitably, things will go wrong at some point. When this happens, it’s worth running
gradlew clean
once or twice extra to clean up old files that could be causing trouble.
Building javadocs¶
To generate javadocs for the source code, use
gradlew mergedJavadocs
This will generate html javadocs in a ./build/merged-docs
subdirectory.
If you’d like to include external links to other relevant javadocs (e.g. for the JDK, ImageJ, JTS) use
gradlew mergedJavadocs -PlinkJavadoc=true