Skip to content

Guidelines for setting up a local workspace

Jump to bottom
Oliver Kopp edited this page Aug 25, 2019 · 62 revisions

Prerequisites

Java Development Kit 11 with JavaFX development. We recommend Liberica JDK at https://bell-sw.com/pages/java-11.0.3/, because it includes JavaFX.

See https://github.com/JabRef/jabref/issues/2594 for the ongoing development.

An indication that JAVA_HOME is not correctly set or no JDK 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)

Ensure you have a Java SDK installed

  • In the command line (terminal in Linux, cmd in Windows) run javac -version
  • If javac is not found, check your PATH environment variable, your JAVA_HOME environment variable or install the most recent SDK

GitHub account

If you do not have a GitHub account, create it at https://github.com.

Get an IDE in place

We suggest Eclipse or IntelliJ.

IntelliJ

The community edition should be enough. If not, a developer key for the JabRef project for the full version is available upon request.

You can find a IntelliJ Codestyle configuration file in the folder config

In case there are errors at the Gradle sync (and that there is no play button at the tests), fix the reference JDK.

JabRef 5.x

Please use a JDK with JavaFX support. We recommend the LibericaJDK as it works out of the box. See https://bell-sw.com/.

JabRef 4.x

The current JDK is most probably JDK 8 (and not JDK 11). Hints are given at https://stackoverflow.com/a/54507226/873282.

Eclipse

Please install EclEmma for code coverage.

In Ubuntu Linux, you can follow one of these guidelines to Install Eclipse:

In Windows download it from www.eclipse.org and run the installer.

Get git in place

Get the code

Fork JabRef into your GitHub account

  1. Log into your GitHub account
  2. Go to https://github.com/JabRef/jabref
  3. Create a fork by clicking at fork button on the right top corner
  4. A fork repository will be created under your account (https://github.com/YOUR_USERNAME/jabref)

Clone your forked repository on your local machine.

  • In command line go to a folder you want to place the source code locally (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.
  • Run git clone --depth=10 https://github.com/YOUR_USERNAME/jabref.git. The --depth--10 is 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.
  • Update submodules: git submodule update --init

Generating additional source codes and getting dependencies using Gradle

(not required for IntelliJ)

  1. Go to the jabref folder (the repo you just cloned, if you are following this tutorial, just execute cd jabref)

  2. Execute the following steps from the git-bash:

    • Run ./gradlew assemble
    • If you use Eclipse: Additionally run ./gradlew eclipse
    • If you use IntelliJ: No further setup is required

  3. 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.

  4. ./gradlew tasks shows many other runnable tasks.

Set-up Eclipse

  • Open Eclipse
  • To Import your JabRef project go to menu File --> Import
  1. Choose General --> Existing projects in the workspace and "next"
  2. For "select root directory", browse until the root folder of your jabref just cloned from your repo (e.g., /home/user/<YOU>/jabref)
  3. Click on "Finish" and voilá!
  4. In Eclipse, right click on the project and choose Refresh workspace and then choose Run as --> Java application (Forget about the existing errors)
  5. Choose JabRefMain as the main class to be executed

Set-up your IDE (IntelliJ)

JabRef 5.x

In IntelliJ, execute following steps:

  1. Open build.gradle as project

  2. Do not enable automatic sync if asked

  3. Ensure that Projekt SDK is Java 11

    1. Right click on project -> Module Settings
    2. Platform Settings -> SDK

  4. Ensure that each module has Java 11

  5. File | Settings | Build, Execution, Deployment | Compiler | Java Compiler

  6. All Modules have to have "Target bytecode version" as 11.

  7. Ensure that IntelliJGradle is used as execution service

  8. File | Settings | Build, Execution, Deployment | Build Tools | Gradle

  9. Build and run using: IntelliJ IDEAGradle

  10. Run tests using: IntelliJ IDEAGradle

  11. Stop here

  12. Open Module Settings (right click on the project root)

  13. Select Project Settings --> Libraries

  14. Add all *.jars from lib/ directory one by one: Make it available to all projects (multiselection is possible)

  1. Remove all starting with com.lihaoyi

  1. Remove all com.google.errorprone

  2. Remove all org.checkerframework

  3. Remove all jsr305

  4. Enable impl.org.controlsfx.skin being visible:

    1. See https://intellij-support.jetbrains.com/hc/en-us/community/posts/360001797820/comments/360000274319
    2. Add --add-exports org.controlsfx.controls/impl.org.controlsfx.skin=org.jabref --add-exports javafx.controls/javafx.scene.control=org.jabref --add-exports javafx.controls/com.sun.javafx.scene.control=org.controlsfx.controls --add-exports javafx.controls/com.sun.javafx.scene.control=org.jabref as option to JabRef.main
    3. Ensure that you click the "Apply" button. You have to select the black area below the input field to enable the Apply button.

  5. Execute Build/Rebuild Project

  6. Start the UI

  7. Run org.jabref.JabRefMain:main

  8. Ensure that "Use classpath of module JabRef.main" is selected

  9. Currently does not start. We are working on it.

  10. Apply workaround to have Gradle as execution environment

JabRef 4.x

See https://youtu.be/FeQpygT0314. This ensures that src/main/gen is present.

After that steps, please follow these:

  1. Install the CheckStyle-IDEA plugin, it can be found via plug-in repository (File > Settings > Plugins > Browse repositories).
  2. Go to File > Settings > Editor > Code Style, choose a code style (or create a new one)
  3. Click on the settings wheel (next to the scheme chooser), then Import scheme and choose "CheckStyle Configuration". Select the CheckStyle configuration file config\checkstyle\checkstyle.xml. Click OK and restart IntelliJ.
  4. Go to File > Settings > Checkstyle and import the above CheckStyle configuration file. Activate it.

In case IntelliJ cannot compile the sources, tell IntelliJ to use Gradle for compiling and testing:

IntelliJ Gradle Config

Final comments

Got it running? GREAT! You are ready to lurk the code and contribute to JabRef 📚 . In the latter case, please read CONTRIBUTING.md.

Clone this wiki locally