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

Refine IntelliJ howto to enable built-in compiler again #6794

Merged
merged 14 commits into from
Sep 1, 2020
Merged

Refine IntelliJ howto to enable built-in compiler again #6794

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
613a7d0
Refine IntelliJ howto to enable built-in compiler again
koppor Aug 26, 2020
0cfa772
Fix linting issue
koppor Aug 26, 2020
82ae834
Fix text
koppor Aug 26, 2020
16bec67
Merge branch 'master' into refine-intellij-howto
koppor Aug 27, 2020
320aa9e
Remove obsolte image
koppor Aug 28, 2020
d35b31c
Add one more graphics (and refine markdown)
koppor Aug 28, 2020
5c931c5
Merge remote-tracking branch 'origin/master' into refine-intellij-howto
koppor Aug 28, 2020
ea25396
Fix markdown
koppor Aug 28, 2020
2bf95e0
Refine howto
koppor Aug 28, 2020
3aacefe
Merge branch 'refine-intellij-howto' of github.com:JabRef/jabref into…
koppor Aug 28, 2020
cb3e011
Add link to JetBrains issue
koppor Aug 28, 2020
465b3cc
Update guidelines-for-setting-up-a-local-workspace.md
koppor Sep 1, 2020
7e88d55
Merge remote-tracking branch 'origin/master' into refine-intellij-howto
koppor Sep 1, 2020
971d63c
Merge branch 'master' into refine-intellij-howto
koppor Sep 1, 2020
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
Binary file removed docs/.gitbook/assets/grafik.png
View file
Open in desktop
Binary file not shown.
Binary file added docs/.gitbook/assets/intellij-enable-annotation-processing.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
0 docs/.gitbook/assets/grafik (1).png → .../assets/intellij-wrap-at-right-margin.png
View file
Open in desktop
File renamed without changes
51 changes: 34 additions & 17 deletions docs/getting-into-the-code/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 @@ -56,7 +56,7 @@ It is strongly recommend that you have git installed.

We suggest [IntelliJ IDEA](https://www.jetbrains.com/idea/) or [Eclipse \(for advanced users\)](https://eclipse.org/) \(`2020-03` 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](https://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.
On 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](https://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.

### Other Tooling

Expand Down Expand Up @@ -88,26 +88,27 @@ These steps are very important. They allow you to focus on the content and ensur

### 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.
We recommend to install IntelliJ IDEA using [JetBrains Toolbox App](https://www.jetbrains.com/toolbox-app/), because IDE updates are automatically installed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As these installation notes are already pretty extensive, I would try to reduce them to the minimum. How Intellj is installed is best installed is something a user can figure out themselves I think. Also the "checked for" paragraph is not really helpful for a new dev in my opinion.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the "checked for", but kept the recommendation (based on my teaching experience).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For people who are new to the project, anything that would make them more comfortable and show them the steps towards that is great.
Pointing to the "default" IDE, is a point that helps a lot and in JabRef cases facilitates (even if some 'mentoring' is required)


To configure IntelliJ IDEA for developing JabRef, you should first ensure that you have enabled both bundled plugins _Gradle_ and _Gradle Extension_
IntelliJ instructions checked for

* Navigate to **File \| Settings \| Plugins \| Installed** and check that you have
* [2020.1](https://confluence.jetbrains.com/display/IDEADEV/IDEA+2020.1+latest+builds) - works with restrictions (outlined below)
* [2020.2](https://confluence.jetbrains.com/display/IDEADEV/IDEA+2020.1+latest+builds) - works with restrictions (outlined below)

the _Gradle_ and _Gradle Extension_ enabled.
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.

After that, you can open `jabref/build.gradle` as a project. It is crucial that Java 14 is used consistently for the JabRef project which includes ensuring the right settings for your project structure, Gradle build, and run configurations.
To configure IntelliJ IDEA for developing JabRef, you should first ensure that you have enabled both bundled plugins _Gradle_ and _Gradle Extension_:

* Ensure you have a Java 14 SDK configured by navigating to
* Navigate to **File \| Settings \| Plugins \| Installed** and check that you have the _Gradle_ and _Gradle Extension_ enabled.

**File \| Project Structure \| Platform Settings \| SDKs**. If you don't have one, add a new Java JDK and point it to the
After that, you can open `jabref/build.gradle` as a project. It is crucial that Java 14 is used consistently for the JabRef project which includes ensuring the right settings for your project structure, Gradle build, and run configurations.

location of a JDK 14.
Ensure you have a Java 14 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 14:

* Navigate to **File \| Project Structure \| Project** and ensure that the projects' SDK is Java 14
* Navigate to **File \| Settings \| Build, Execution, Deployment \| Build Tools \| Gradle** and select the Java 14 SDK as the Gradle JVM at the bottom.

To prepare IntelliJ's build system two additional steps are required
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:

Expand All @@ -118,16 +119,19 @@ To prepare IntelliJ's build system two additional steps are required

* Enable annotation processors by navigating to **File \| Settings \| Build, Execution, Deployment \| Compiler \| Annotation processors** and check "Enable annotation processing"

![Enable annotation processing](../.gitbook/assets/intellij-enable-annotation-processing.png)

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](https://youtrack.jetbrains.com/issue/IDEA-240517).

![Disable wrapping at right margin to prevent JavaDoc to be wrapped](../.gitbook/assets/grafik%20%281%29.png)
![Disable wrapping at right margin to prevent JavaDoc to be wrapped](../.gitbook/assets/intellij-wrap-at-right-margin.png)

#### 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.
* 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

Expand All @@ -137,17 +141,33 @@ After that a new entry called "jabref \[run\]" will appear in the run configurat

#### Using IntelliJ's internal build system

**Note that these steps do not work on IntelliJ 2020.x.**. You have to keep using gradle for executing tasks.
See [IDEA-249391](https://youtrack.jetbrains.com/issue/IDEA-249391) for details.

You should use IntelliJ IDEA's internal build system for compiling and running JabRef during development, because it is usually more responsive. Thereby, **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".
* Ignore the Gradle project "buildSrc" by clicking the button **Select Project Data To Import** in the Gradle Tool Window and unchecking the folder "buildSrc".
![Ignore the Gradle project "buildSrc"](../.gitbook/assets/intellij-gradle-config-ignore-buildSrc.png)
* Delete `org.jabref.gui.logging.plugins.Log4jPlugins` (location: `generated\org\jabref\gui\logging\plugins\Log4jPlugins.java`). Otherwise, you will see folowing error:

![Ignore the Gradle project "buildSrc"](../.gitbook/assets/intellij-gradle-config-ignore-buildSrc%20%281%29.png)
```text
Error:java: Unable to create Plugin Service Class org.jabref.gui.logging.plugins.Log4jPlugins
```

or following error:

```text
Error:(16, 25) java: package org.jabref.search does not exist
```

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 `SearchBaseVisitor` (e.g., `Error:(16, 25) java: package org.jabref.search does not exist`), you have to delete `generated\org\jabref\gui\logging\plugins\Log4jPlugins.java`. This is independet of having enabled or disabled Annotation Processing (see above at "Enable Annotation Processing").


#### 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.
Expand All @@ -172,9 +192,7 @@ Contributions to JabRef's source code need to have a code formatting that is con
8. Save settings by clicking "OK"
9. Your configuration should now look like this:

```text
![checkstyle settings](../.gitbook/assets/intellij-checkstyle-settings.png)
```
![checkstyle settings](../.gitbook/assets/intellij-checkstyle-settings.png)

### Setup for Eclipse

Expand Down Expand Up @@ -250,4 +268,3 @@ java.lang.UnsupportedClassVersionError: org/javamodularity/moduleplugin/ModuleSy
### Problems with generated source files

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.