diff --git a/docs/guidelines-for-setting-up-a-local-workspace.md b/docs/guidelines-for-setting-up-a-local-workspace.md index b5c5221c3d3..1b803d7f70e 100644 --- a/docs/guidelines-for-setting-up-a-local-workspace.md +++ b/docs/guidelines-for-setting-up-a-local-workspace.md @@ -25,7 +25,7 @@ If you do not yet have a GitHub account, please [create one](/~https://github.com/ ### IDE -We suggest [IntelliJ](https://www.jetbrains.com/idea/) or [Eclipse](https://eclipse.org/) (`2019-12` or newer). +We suggest [IntelliJ IDEA](https://www.jetbrains.com/idea/) or [Eclipse](https://eclipse.org/) (`2019-12` or newer). Under Ubuntu Linux, you can follow the [documentation from the Ubuntu Community](https://help.ubuntu.com/community/EclipseIDE#Download_Eclipse) or the [step-by-step guideline from Krizna](www.krizna.com/ubuntu/install-eclipse-in-ubuntu-12-04/) to install Eclipse. Under Windows, download it from [www.eclipse.org](http://www.eclipse.org/downloads/) and run the installer. @@ -49,51 +49,80 @@ Under Ubuntu Linux, you can follow the [documentation from the Ubuntu Community] ## Configure your IDE -### Setup for IntelliJ - -1. Open `jabref/build.gradle` as a project -2. Enable annotation processors: - * File -> Settings -> Build, Execution, Deployment -> Compiler -> Annotation processors: - * Check "Enable annotation processing" -3. Configure module settings: Right click on project -> Open Module Settings: - * Ensure that the projects' SDK is Java 13: - * Project Settings -> Project -> Project SDK: Choose Java 13 - * Ensure that standard SDK is Java 13: - * Platform Settings -> SDK -> Choose Java 13 -4. Specify additional compiler arguments: - * File -> Settings -> Build, Execution, Deployment -> Compiler -> Java Compiler: - * Under "Override compiler parameters per-module" add ([+]) the following compiler arguments for the `JabRef.main` module: +### Setup for IntelliJ IDEA +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 13 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 13 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 13. +* Navigate to **File | Project Structure | Project** and ensure that the projects' SDK is Java 13 +* Navigate to **File | Settings | Build, Execution, Deployment | Build Tools | Gradle** and select the Java 13 SDK as +the Gradle JVM at the bottom. + +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.main` module: ``` --add-exports=javafx.controls/com.sun.javafx.scene.control=org.jabref --add-exports=org.controlsfx.controls/impl.org.controlsfx.skin=org.jabref ``` +* Enable annotation processors by navigating to +**File | Settings | Build, Execution, Deployment | Compiler | Annotation processors** and check "Enable annotation processing" + +#### Using Gradle from within IntelliJ IDEA + +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 "Reimport 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 `./gradlew run`. -5. Use IntelliJ to build and run (instead of gradle): - * File -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle: - * Set "Build and run using" and "Run tests using" both to "IntelliJ IDEA" -6. Ensure that the JDK13 is enabled for Gradle: Use IntelliJ to build and run (instead of gradle): - * File -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle -> Gradle: - * Set "Gradle JVM" to "JDK13" -7. Use the provided code style: - 1. Install the [CheckStyle-IDEA plugin](http://plugins.jetbrains.com/plugin/1065?pr=idea), it can be found via the plug-in repository: - 1. File > Settings > Plugins > Marketplace - 2. Search for "Checkstyle" and choose "CheckStyle-IDEA" - 3. Close the settings afterwards and restart IntelliJ - 2. Go to File > Settings > Editor > Code Style: - 1. Click on the settings wheel (next to the scheme chooser), then click "Import Scheme" and choose "IntelliJ Code Style.xml". - 2. Select the IntelliJ configuration file `config/IntelliJ Code Style.xml`. - 3. Click "OK". - 4. Go to File -> Settings -> Other Settings -> Checkstyle -> Configuration File: - 1. Import the CheckStyle configuration file by clicking the [+] button - 2. For the description provide e.g. "CheckStyle" - 3. Click "Browse" and choose `config/checkstyle/checkstyle.xml` - 4. Click "Next" and "Finish" - 5. Activate the CheckStyle configuration file by ticking it in the list - 6. Save settings by clicking "OK" -8. Open Run -> Edit Configurations... -> Select Application -> JabRef Main - * Verify, that "JRE" is set to "Default (JDK 13)" or to JDK 13 - * Set "VM Options" to the following: +#### Using IntelliJ's internal build system + +You can use IntelliJ IDEA's internal build system for compiling and running JabRef during development which is +usually more responsive. However, **it's 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". + +To use the "JabRef Main" run configuration, open **Run | Edit Configurations... | Application | JabRef Main** and + +* Verify, that your JDK 13 is used +* Set "VM Options" to the following: ``` --patch-module org.jabref=build/resources/main @@ -131,20 +160,38 @@ Under Ubuntu Linux, you can follow the [documentation from the Ubuntu Community] --patch-module test3=sourcecode_2.12-0.1.4.jar ``` -9. If you have configured Eclipse for the same project (the required steps are described below), then the additionally added file `Log4jPlugins.java` must be excluded from the compilation process, otherwise an error will occur during the compilation of the project: - * File -> Settings -> Build, Execution, Deployment -> Compiler -> Excludes: Add the following file to the list ([+]), in order to exclude it: - * `src/main/java/org/jabref/gui/logging/plugins/Log4jPlugins.java` -10. Use the provided run configuration: Run -> Run "JabRef Main" - * This uses now IntelliJ for building and running/debugging the application, which is recommended, since the application starts quite fast. -11. Alternatively, the project can also be built and run/debugged by using gradle from within the IDE, which is not recommended, since the application starts significantly slower: - 1. Open the gradle tool window: - * View -> Tool Windows -> Gradle - 2. Navigate to the following entry in the gradle tool window: - * JabRef -> Tasks -> application -> run - 3. Double click "run" to build and run the application - 4. After that a new entry called "jabref [run]" will appear in the run configurations. - 5. Now you can also select "jabref [run]" and either run or debug the application from within IntelliJ. - * Equivalently, this can also be executed from the terminal by running `./gradlew run`. +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. + +#### Using JabRef's code-style + +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](http://plugins.jetbrains.com/plugin/1065?pr=idea), it can be found via the plug-in repository: + 1. Navigate to **File | Settings | Plugins | Marketplace** and search for "Checkstyle" and choose "CheckStyle-IDEA" + 2. 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`. +* Go to **File | Settings | Other Settings | Checkstyle | Configuration File** + 1. Import the CheckStyle configuration file by clicking the [+] button + 2. For the description provide e.g. "CheckStyle" + 3. Click "Browse" and choose `config/checkstyle/checkstyle.xml` + 4. Click "Next" and "Finish" + 5. Activate the CheckStyle configuration file by ticking it in the list + 6. Save settings by clicking "OK" + +#### Troubleshooting when using both IDEA and Eclipse + +If you have configured Eclipse for the same project (the required steps are described below), +then the additionally added file `Log4jPlugins.java` must be excluded from the compilation process, +otherwise an error will occur during the compilation of the project: + +* **File | Settings | Build, Execution, Deployment | Compiler | Excludes** and add the following file to the +list ([+]), in order to exclude it: + * `src/main/java/org/jabref/gui/logging/plugins/Log4jPlugins.java` ### Setup for Eclipse @@ -163,7 +210,7 @@ Make sure your Eclipse installation us up to date, Eclipse 2019-12 or newer is r 5. Create a run/debug configuration for the main class `org.jabref.JabRefLauncher` and/or for `org.jabref.JabRefMain` (both can be used equivalently) * In the tab "Arguments" of the run/debug configuration, enter the following runtime VM arguments: * Set "VM Arguments" to: - + ``` --patch-module test=fastparse_2.12-1.0.0.jar --patch-module test2=fastparse-utils_2.12-1.0.0.jar