This guide explains how to set up your environment for development of JabRef. It includes information about prerequisites, configuring your IDE, and running JabRef locally to verify your setup.
For a complete step-by-step guide for Linux using IntelliJ IDEA as the IDE, have a look at the following video instructions:
This section list the prerequisites you need to get started to develop JabRef. After this section, you are ready to get the code.
A working Java (Development Kit) 18 installation with Java FX support is required. In the command line (terminal in Linux, cmd in Windows) run
javac -version and make sure that the reported version is Java 18 (e.g.,
javac 18). If
javac is not found or a wrong version is reported, check your
PATH environment variable, your
JAVA_HOME environment variable or install the most recent JDK.
JavaFX is not part of the default JDK any more, it needs to be installed separately if not using a special JDK.
Download and install the JDK from https://jdk.java.net/. Afterwards, download the “jmods” JavaFX 18 zip archive from https://gluonhq.com/products/javafx/ and put the
.jmod files into
If you do not yet have a GitHub account, please create one.
Proposals for account names:
- Login similar to your university account. Example:
- Use your last name prefixed by the first letter of your first name. Example:
You can hide your email address by following the recommendations at https://saraford.net/2017/02/19/how-to-hide-your-email-address-in-your-git-commits-but-still-get-contributions-to-show-up-on-your-github-profile-050/.
Most developers, though, do not hide their email address. They use one which may get public. Mostly, they create a new email account for development only. That account then be used for development mailing lists, mail exchange with other developers, etc.
- Same login as in GitHub (see above). Example:
it” in the name. Example:
- Use the university login. Example:
It is strongly recommend that you have git installed.
- In Debian-based distros:
sudo apt-get install git
- In Windows: Download the installer and install it. Using chocolatey, you can run
choco install git.install -y --params "/GitAndUnixToolsOnPath /WindowsTerminalto a) install git and b) have linux commands such as
grepavailable in your
- official installation instructions
We recommend to install IntelliJ IDEA using JetBrains Toolbox App, because IDE updates are automatically installed.
On Ubuntu Linux, you can follow the documentation from the Ubuntu Community or the step-by-step guideline from Krizna to install Eclipse. On Windows, download it from www.eclipse.org and run the installer.
Eclipse JEE 2022-03 or newer is required.
See our tool recommendations.
This section explains how you get the JabRef code onto your machine in a form allowing you to make contributions.
- Log into your GitHub account
- Go to https://github.com/JabRef/jabref
- Create a fork by clicking at fork button on the right top corner
- A fork repository will be created under your account
- In a command line, navigate to the folder where you want to place the source code (parent folder of
jabref/). To prevent issues along the way, it is strongly recommend to choose a path that does not contain any special (non-ASCII or whitespace) characters. Note that placing jabref folder directly in the disk root directory may cause an error.
git clone --depth=10 https://github.com/YOUR_USERNAME/jabref.git. The
--depth--10is used to limit the download to ~20 MB instead of downloading the complete history (~800 MB). If you want to dig in our commit history, feel free to download everything.
- Go to the newly created jabref folder:
- Generate additional source code:
./gradlew assemble(on Windows:
- Source code should now reside in
- Start JabRef:
- JabRef’s GUI should now start up.
These steps are very important. They allow you to focus on the content and ensure that the code formatting always goes well. Did you know that IntelliJ allows for reformatting selected code if you press Ctrl + Alt + L?
IntelliJ IDEA fully supports Gradle as a build tool, but also has an internal build system which is usually faster. For JabRef, Gradle is required to make a full build but once set up, IntelliJ IDEA’s internal system can be used for sub-sequent builds.
To configure IntelliJ IDEA for developing JabRef, you should first ensure that you have enabled both bundled plugins Gradle and Gradle Extension:
- Navigate to File > Settings > Plugins > Installed and check that you have the Gradle and Gradle Extension enabled.
After that, you can open
jabref/build.gradle as a project. It is crucial that Java 18 is used consistently for the JabRef project which includes ensuring the right settings for your project structure, Gradle build, and run configurations.
Ensure you have a Java 18 SDK configured by navigating to File > Project Structure > Platform Settings > SDKs. If you don’t have one, add a new Java JDK and point it to the location of a JDK 18.
Navigate to File > Project Structure > Project and ensure that the projects’ SDK is Java 18
Navigate to File > Settings > Build, Execution, Deployment > Build Tools > Gradle and select the “Project SDK” as the Gradle JVM at the bottom. If that does not exist, just select a JDK 18.
To prepare IntelliJ’s build system two additional steps are required:
Navigate to File > Settings > Build, Execution, Deployment > Compiler > Java Compiler, and under “Override compiler parameters per-module” add ([+]) the following compiler arguments for the
JabRef.mainmodule. Otherwise, you will get:
java: package com.sun.javafx.scene.control is not visible (package com.sun.javafx.scene.control is declared in module javafx.controls, which does not export it to module org.jabref)
Note that you need to focus another UI element before pressing OK. Otherwise, the setting will be empty.
Enable annotation processors by navigating to File > Settings > Build, Execution, Deployment > Compiler > Annotation processors and check “Enable annotation processing”
To have autoformat working properly in the context of line wrapping, “Wrap at right margin” has to be disabled as shown below. Details are found in IntelliJ issue 240517.
To enable “magic” creation and auto cleanup of imports, enable both “Add unambiguous imports on the fly” and “Optimize imports on the fly”:
Ensuring JabRef builds with Gradle should always the first step because, e.g. it generates additional sources that are required for compiling the code. After adjusting all settings mentioned earlier, your first step should be to
- Open the Gradle Tool Window with the small button that can usually be found on the right side of IDEA or navigate to View > Tool Windows > Gradle.
- In the Gradle Tool Window, press the “Reload All Gradle Projects” button to ensure that all settings are up-to-date with the setting changes.
After that, you can use the Gradle Tool Window to build all parts JabRef and run it. To do so, expand the JabRef project in the Gradle Tool Window and navigate to Tasks. From there, you can
- Build and run JabRef by double-clicking JabRef > Tasks > application > run.
After that a new entry called “jabref [run]” will appear in the run configurations. Now you can also select “jabref [run]” and either run or debug the application from within IntelliJ. You can run any other development task in a similar way. Equivalently, this can also be executed from the terminal by running
You should use IntelliJ IDEA’s internal build system for compiling and running JabRef during development, because it is usually more responsive. Thereby, it is important that you understand that JabRef relies on generated sources which are only build through Gradle. Therefore, to build or update these dependencies you need to run the
assemble Gradle task at least once.
To use IntelliJ IDEA’s internal build system when you build JabRef through Build > Build Project or use the provided “JabRef Main” run configuration, ensure that
- In File > Settings > Build, Execution, Deployment > Build Tools > Gradle the setting “Build and run using” and “Test using” is set to “IntelliJ IDEA”.
Ignore the Gradle project “buildSrc” by clicking the button Select Project Data To Import in the Gradle Tool Window and unchecking the folder “buildSrc”.
- Right click on the project “jabref”.
- Select “Open Module Settings”
- Expand “JabRef”
- Select “main”
- Select tab “Sources”
- Click “+ Add Content Root”
- Select the
- Click “OK”. When expanding “main”, “java” should have been selected as source
- Click “OK” to save the changes
- In case the above step does not work, run with gradle, import gradle project again, and try again.
Essentially, you now have the best of both worlds: You can run Gradle tasks using the Gradle Tool Window and unless you haven’t made changes to input files that generate sources, you can compile and run with IntelliJ’s faster internal build system.
In case all steps are followed, and there are still issues with
Error:(16, 25) java: package org.jabref.search does not exist), you have to delete
src\main\generated\org\jabref\gui\logging\plugins\Log4jPlugins.java. This is independent of having enabled or disabled Annotation Processing (see above at “Enable Annotation Processing”).
Note that the above steps might not work on IntelliJ 2020.x.**. You have to keep using gradle for executing tasks. See IDEA-249391 for details.
Contributions to JabRef’s source code need to have a code formatting that is consistent with existing source code. For that purpose, JabRef provides code-style and check-style definitions.
- Install the CheckStyle-IDEA plugin, it can be found via the plug-in repository:
- Navigate to File > Settings > Plugins > Marketplace and search for “Checkstyle” and choose “CheckStyle-IDEA”
- Close the settings afterwards and restart IntelliJ
- Go to File > Settings > Editor > Code Style
- Click on the settings wheel (next to the scheme chooser), then click “Import Scheme”
- Select the IntelliJ configuration file
config/IntelliJ Code Style.xml
Finally, ensure that the checkstyle configuration file is in place:
- Go to File > Settings > Tools > Checkstyle > Configuration File
- Import the CheckStyle configuration file by clicking the [+] button
- For the description provide “JabRef”
- Click “Browse” and choose
- Click “Next” and “Finish”
- Activate the CheckStyle configuration file by ticking it in the list
- Ensure that the latest CheckStyle version is selected (8.36 or higher). 9.3 is required for Java 18.
- Set the “Scan Scope” to “Only Java sources (including tests)
- Save settings by clicking “OK”
Your configuration should now look like this:
Make sure your Eclipse installation us up to date.
./gradlew runto generate all resources and to check if JabRef runs.
- The JabRef GUI should finally appear.
- This step is only required once.
- This must always be executed, when there are new upstream changes.
- Open or import the existing project in Eclipse as Java project.
- Remark: Importing it as gradle project will not work correctly.
- Refresh the project in Eclipse
- Create a run/debug configuration for the main class
org.jabref.gui.JabRefMain(both can be used equivalently)
Remark: The run/debug configuration needs to be added by right clicking the class (e.g. JabRefLauncher or JabRefMain) otherwise it will not work.
In the tab “Arguments” of the run/debug configuration, enter the following runtime VM arguments:
--add-exports javafx.controls/com.sun.javafx.scene.control=org.jabref --add-exports org.controlsfx.controls/impl.org.controlsfx.skin=org.jabref --add-exports javafx.graphics/com.sun.javafx.scene=org.controlsfx.controls --add-exports javafx.graphics/com.sun.javafx.scene.traversal=org.controlsfx.controls --add-exports javafx.graphics/com.sun.javafx.css=org.controlsfx.controls --add-exports javafx.controls/com.sun.javafx.scene.control.behavior=org.controlsfx.controls --add-exports javafx.controls/com.sun.javafx.scene.control=org.controlsfx.controls --add-exports javafx.controls/com.sun.javafx.scene.control.inputmap=org.controlsfx.controls --add-exports javafx.base/com.sun.javafx.event=org.controlsfx.controls --add-exports javafx.base/com.sun.javafx.collections=org.controlsfx.controls --add-exports javafx.base/com.sun.javafx.runtime=org.controlsfx.controls --add-exports javafx.web/com.sun.webkit=org.controlsfx.controls --add-exports javafx.graphics/com.sun.javafx.css=org.controlsfx.controls --add-exports javafx.controls/com.sun.javafx.scene.control.behavior=com.jfoenix --add-exports javafx.graphics/com.sun.javafx.stage=com.jfoenix --add-exports com.oracle.truffle.regex/com.oracle.truffle.regex=org.graalvm.truffle --patch-module org.jabref=build/resources/main
In the tab “Dependencies” of the run/debug configuration tick the checkbox “Exclude test code”
- Optional: Install the e(fx)clipse plugin from the Eclipse marketplace: 1. Help -> Eclipse Marketplace… -> Search tab 2. Enter “e(fx)clipse” in the search dialogue 3. Click “Go” 4. Click “Install” button next to the plugin 5. Click “Finish”
- Now you can build and run/debug the application by either using “JabRefLauncher” or “JabRefMain”. This is the recommended way, since the application starts quite fast.
In the run configuration, there is a “Build and run” section. At the “VM options” (the box below the java version), following content needs to be present:
-ea --add-exports=javafx.controls/com.sun.javafx.scene.control=org.jabref --add-exports=org.controlsfx.controls/impl.org.controlsfx.skin=org.jabref --add-exports javafx.graphics/com.sun.javafx.application=ALL-UNNAMED --add-exports javafx.graphics/com.sun.javafx.stage=ALL-UNNAMED --add-exports javafx.graphics/com.sun.javafx.stage=com.jfoenix
Now the test will run.
To run the
LocalizationConsistencyTest you need to add some extra module information: Right-click on the file -> “Run/Debug as JUnit test”. Go to the Run/debug configuration created for that file and in the arguments tab under VM-configurations add:
--add-exports javafx.graphics/com.sun.javafx.application=ALL-UNNAMED --add-exports javafx.graphics/com.sun.javafx.stage=ALL-UNNAMED --add-exports javafx.graphics/com.sun.javafx.stage=com.jfoenix
Got it running? GREAT! You are ready to lurk the code and contribute to JabRef. Please make sure to also read our contribution guide.
An indication that
JAVA_HOME is not correctly set or no JDK 18 is installed is following error message:
compileJava FAILED FAILURE: Build failed with an exception. * What went wrong: Execution failed for task ':compileJava'. > java.lang.ExceptionInInitializerError (no error message)
Another indication is following output
java.lang.UnsupportedClassVersionError: org/javamodularity/moduleplugin/ModuleSystemPlugin has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0
In rare cases you might encounter problems due to out-dated automatically generated source files. Running
./gradlew clean deletes these old copies. Do not forget to run at least
./gradlew eclipse or
./gradlew build afterwards to regenerate the source files.
- Open the context menu of
- Select “Load/Unload modules”.
Following error message appears:
Error occurred during initialization of boot layer java.lang.module.FindException: Module org.jsoup not found, required by org.jabref
This can include different modules.
- Go to File -> Invalidate caches…
- Check “Clear file system cache and Local History”.
- Check “Clear VCS Log caches and indexes”.
- Uncheck the others.
- Click on “Invalidate and Restart”.
- After IntelliJ restarted, you have to do the “buildSrc”, “Log4JAppender”, and “src-gen” steps again.
There might be problems with building if you have openjfx libraries in local maven repository, resulting in errors like this:
> Could not find javafx-fxml-18-mac.jar (org.openjfx:javafx-fxml:18). Searched in the following locations: file:<your local maven repository path>/repository/org/openjfx/javafx-fxml/18/javafx-fxml-18-mac.jar
As a workaround, you can remove all local openjfx artifacts by deleting the whole openjfx folder from specified location.
In case of a NPE at
org.jabref.logic.journals.JournalAbbreviationLoader.loadRepository(JournalAbbreviationLoader.java:30) ~[classes/:?], invalidate caches and restart IntelliJ. Then, Build -> Rebuild Project.
If that does not help:
- Save/Commit all your work
- Close IntelliJ
- Delete all non-versioned items:
git clean -xdf. This really destroys data
- Start IntelliJ and try again.
After changing the contents of
build.gradle, on might get following error:
Entry org/jabref/build/JournalAbbreviationConverter$_convert_closure1$_closure2.class is a duplicate but no duplicate handling strategy has been set.
Please update to the latest development code. We applied the workaround from https://github.com/gradle/gradle/issues/17236#issuecomment-923074298.