Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure and improve docs for setting up IntelliJ #5960

Merged
merged 1 commit into from
Feb 19, 2020
Merged

Restructure and improve docs for setting up IntelliJ #5960

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 102 additions & 55 deletions docs/guidelines-for-setting-up-a-local-workspace.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down