Guide on how to compile Quelea from source into installation package (deployment)

I am making this little guite in order to help those who want to run custom versions of Quelea.
I hope this will help you avoid the sumbling blocks i went through. Ideally this should be in the or the documenttaion.


In order to compile Quelea from source you need a an x86 CPU type machine running Windows or Linux (recommending latest). In this case we will explain how to do it on windows.
Install the the software required:

2.Download/Clone and Open the Project

First you have to select what fork you want to depoy. For most people this would be the official repository master branch, but it could be a fork and a branch with a feature.
Then load the project in Intelij.

3.Load gradle configuration

At this point you have the project loaded. This is a gradle project therefore locate the build.gradle from under the root directory name follwoed by Quelea/build.gradle.

A popup might appear to integrate or load the gradle configuration accept that and any security confirmations.
If not open the Run/Debug Configurations window and add new configuration by selecting gradle.
Edit Run Task

Can also use edit configuration tempaltes

Now select the directory where the gradle is stored and the gradle file will be located automatically.

If successful an elephant icon should appear on the side bar somewhere.

4.Setup Java SDK

Once the configuration is loaded it make take some time for all the setup to be completed.
The first thing to do is to build and run the project to verify everything is working as expected, but before that we need to setup Java.
Opne Project Structure and select the SDK.
Project Structure

Select Java SDK 17, and you may have to install it if you don’t have it already.

Just follow the onscreen instructions.

Gradle also needs to know what Java Vritual Environment (JVM) to use. This step is similar to setting up the project SDK, either can be done first.
Go to Settings
In the search bar type gradle selelect the “Gradle” tab submenu and select the same version for the Gradle JVM.

5.Run, verify the build, create deploymnet installers

Run the run task
run 'run' task

If everything is ok the project should build and open.

  • This could take a while
  • You may or may not get warrning messages. This is OK!
  • You should not get any error messages!
  • When running you shouldn’t encounter any runtime errors.
  • Note, (at least for me) when the Quelea opens there are 2 things that might not appear to work:
    • Any database songs or other user items might not appear.
    • Secondly the configuration menu might not open. (! I am not sure why that is but it is not a problem). You are currently running it in debug mode.
  • Ignore compaints about Gstreamer( or previously VLC) this is 3rd party external library.

Assuming you have previously isntalled innosetup the paths should be automatically there.
Run the dist gradgle task.

This will take a while. Once done you can find the installers under ...\Quelea\Quelea\dist\standalone\


1 Like

Thanks so much for this overview! Extremely helpful!

Great overview - thank you very much!

When you do UI work, for example a tab or some other element, do you use a 3rd party software or do you prefer doing it programmatically. Or perhaps a plug-in directly in in IntelJ.
I think it would be great to include some recommendation and instructions how to open, edit, save/export the UI element here.

All in code. A couple of contributions have used FXML, but most of Quelea is purely written programmatically in Java.

I’m not a fan of UI based editing tools - they tend to produce messy, hard to modify code that’s hard to review.