Update Building with IntelliJ guide (#62)

This updates the guide with up-to-date instructions and screenshots for recent versions of IntelliJ.
runelite · Apr 9, 2024 · 3ead34d · 3ead34d
1 parent b7a5add
commit 3ead34d
Show file tree

Hide file tree

Showing 23 changed files with 82 additions and 42 deletions.
diff --git a/Building-with-IntelliJ-IDEA.md b/Building-with-IntelliJ-IDEA.md
@@ -4,12 +4,14 @@
 - [Getting started](#getting-started)
   - [Importing the project](#importing-the-project)
   - [Installing Lombok](#installing-lombok)
+  - [Configuring the project](#configuring-the-project)
   - [Building the project](#building-the-project)
   - [Running the project](#running-the-project)
   - [Conclusion](#conclusion)
 - [Troubleshooting](#troubleshooting)
+  - [WARNING: An illegal reflective access operation has occurred](#WARNING-An-illegal-reflective-access-operation-has-occurred)
   - [Missing git](#missing-git)
-  - [Missing JDK](#missing-jdk)
+  - [Tests are failing](#tests-are-failing)
   - [Client failing to start](#client-failing-to-start)
 
 # Getting started
@@ -20,104 +22,142 @@ You can build RuneLite locally using [JDK 11](https://adoptium.net/temurin/relea
 
 ## Importing the project
 
-After launching IntelliJ IDEA for first time, you will see IntelliJ welcome window. You will now need to clone RuneLite repository from git:
+After launching IntelliJ IDEA for first time, you will see IntelliJ's welcome window. You will now need to clone the RuneLite repository from git; to do this you can click the `Get from VCS` button.
 
-![welcome-import-git](https://i.imgur.com/bALnvDY.png)
+![get_from_vcs.png](img/building-with-intellij/get_from_vcs.png)
 
-After clicking on that you will be greeted with prompt. You can either enter the RuneLite repository `https://github.com/runelite/runelite` or your own GitHub fork, if you've created one.
+If you're presented with the editor instead of the welcome screen, click `File > New > Project from Version Control…`.
 
-**NOTE**: If you plan to make a Pull Request, you must fork the RuneLite repository, and clone from your fork.
-
-The prompt should look something like this (if you have issues with finding git.exe see [Troubleshooting](#troubleshooting) section):
+![new_project_from_vcs.png](img/building-with-intellij/new_project_from_vcs.png)
 
-![welcome-clone-project](https://i.imgur.com/bQTTpV0.png)
+After clicking on that you will be greeted with a prompt. You can either enter the RuneLite repository `https://github.com/runelite/runelite` or your own GitHub fork, if you've created one.  
+You can also specify a directory where you'd like to save the RuneLite files to in this prompt. If Git is not installed, click on ``Download and install`` to install Git.
 
-Click *Test* to verify if your entered URL is correct and then click on *Clone*. Now IntelliJ should start cloning the repository:
-
-![welcome-cloning-project](https://i.imgur.com/3jv107G.png)
+**NOTE**: If you plan to make a Pull Request, you must fork the RuneLite repository, and clone from your fork.
 
-After the cloning process is done you should be greeted with prompt asking you if you want to open the project, just click *Yes*:
 
-![after-clone-yes-no](https://i.imgur.com/EvIbCBS.png)
+![clone_runelite.png](img/building-with-intellij/clone_runelite.png)
 
-If everything went well, you should be able to see something like this:
+After cloning is done you will be presented with a `Trust and open Project 'runelite'?` popup. Click `Trust Project`.
 
-![after-clone-fresh-project](https://i.imgur.com/JOAFeMi.png)
 
 ## Installing Lombok
 
 When first viewing the project in IntelliJ IDEA you may come across this error:
 
-![missing-lombok-errors](https://i.imgur.com/a1YDonV.png)
+![missing-lombok-errors](img/building-with-intellij/missing_lombok_errors.png)
 
 This is because you do not have the [Lombok Plugin](https://plugins.jetbrains.com/plugin/6317-lombok-plugin) installed.
 
-Navigate to the **Plugins** tab under the **File > Settings** menu (**IntelliJ IDEA > Preferences** for Mac). Click the **Marketplace** button and search for **Lombok** to find it. Install the plugin and restart IntelliJ IDEA.
+Navigate to the `Plugins` tab under the `(Main Menu) > File > Settings` menu (`IntelliJ IDEA > Preferences` for Mac). Click the `Marketplace` button and search for **Lombok** to find it. Install the plugin and restart IntelliJ IDEA.
 
-![installing-lombok](img/building-with-intellij/installing_lombok.png)
+![installing_lombok.png](img/building-with-intellij/installing_lombok.png)
 
 Success! You should no longer be getting ``Cannot resolve symbol`` or ``Cannot resolve method`` errors.
 
-## Building the project
+
+## Configuring the project
+
+We need to make sure that the correct SDK is selected for RuneLite. To do that go to `File > Project Structure…`
+
+![project_structure.png](img/building-with-intellij/project_structure.png)
+
+Go to the `Project Settings > Project` tab and open the ``SDK`` dropdown menu. Click on ``Download JDK...``
+
+![select-download-jdk](img/building-with-intellij/select_download_jdk.png)
+
+Choose ``version`` ``11`` and ``vendor`` ``Eclipse Temurin (AdoptOpenJDK Hotspot)``. Then press ``Download`` to download the JDK.
+
+![download-jdk](img/building-with-intellij/download_jdk.png)
+
+Set the ``Language level`` to 11 and press ``OK`` to save the changes.
+
+![language-level](img/building-with-intellij/language_level.png)
+
+## Building the project 
 
 RuneLite is using [Maven](https://maven.apache.org/) as build tool. It is used for dependency management, resource generation, running tests and any other tooling needed to properly build, run and deploy RuneLite.
 
 So, to actually run RuneLite, we first need to invoke Maven.
 
-Locate *Maven* on right-side of the screen until you open something like this:
+Locate *Maven* on the right-side of the screen. Then navigate to ``RuneLite`` (parent) > ``Lifecycle``, right-click ``install``, and press ``Run Maven Build``:
+
+![run_maven_build.png](img/building-with-intellij/run_maven_build.png)
 
-![project-maven-view](https://i.imgur.com/xIRxBN1.png)
+At this point, it should start the build, which might take a while. Once the process is done, you should see a message to let you know the final status of the build. Don't worry if there are build or test failures. We can fix those later.
 
-Standard maven goal is *Install* so let's run that. Locate *Runelite (root)* project in dropdown and navigate to `RuneLite (root) -> Lifecycle -> Install` and right-click the option and select `Run Maven Build`:
+![successful_build.png](img/building-with-intellij/successful_build.png)
 
-![run-maven-install](https://i.imgur.com/MxTMK6o.png)
+It is highly recommended to create custom ``Run Configurations``. In the Maven window, right-click on ``RuneLite`` > ``Lifecycle`` > ``install``, and select ``Modify Run Configuration...``
 
-If you are having issues with missing JDK see [Troubleshooting](#troubleshooting) section.
-You can now save this build step as *Run configuration*, just right click *Install* again and select *Create..* (*Modify Run Configuration...* in IntelliJ 2021.2), window like this should pop-up, so just hit *Ok* (you can append `-DskipTests` for faster builds):
+![modify-run-configuration](img/building-with-intellij/modify_run_configuration.png)
 
-![project-maven-install-save](https://i.imgur.com/vdJoJ7L.png)
+Here you can choose a name, such as ``runelite-parent [install] skip tests``, and add a Maven command. For faster builds, try ``install -DskipTests``. This will skip the tests (and test failures).
 
-Now, we need to tell IntelliJ to pick up changes based on Maven build (it should do that automatically, but sometimes it doesn't). So, still in same Maven window, just click the Refresh icon:
+![install_skip_tests](img/building-with-intellij/install_skip_tests.png)
 
-![project-maven-refresh](https://i.imgur.com/L2SmWtF.png)
+Press ``OK``. You can now easily run your run configurations in the Maven window by right-clicking ``RuneLite`` (parent) > ``Run Configurations`` > ``runelite-parent [install] skip tests`` and selecting ``Run``.  
+Alternatively, you can select your run configuration in the dropdown box at the top and hit the ``Run`` button.
+
+![custom_configuration_top](img/building-with-intellij/custom_configuration_top.png)
+
+Other useful run configurations include:  
+``clean install -DskipTests -U`` which is your first troubleshooting step that you should run multiple times in case of a build failures  
+``-Dcheckstyle.skip=false checkstyle:check`` to only run checkstyle without building the client  
+``surefire:test`` to only run the tests without building the client  
+
+We now need to tell IntelliJ to pick up changes based on Maven build (it should do that automatically, but sometimes it doesn't). Click on `Generate Sources and Update folders for all projects` in the Maven window.
+
+![generate_sources.png](img/building-with-intellij/generate_sources.png)
 
 ## Running the project
 
-Now locate *Project* in sidebar and click that open project view, and expand the tree to `runelite/runelite-client/src/main/java/net/runelite/client`. And all you need to do now is right-click `RuneLite` class and select run, and you are done, RuneLite should open:
+Now locate `Project` in the sidebar, and in the project view expand the tree to `runelite/runelite-client/src/main/java/net/runelite/client`. 
+And all you need to do now is right-click the `RuneLite` class and select `Run 'RuneLite.main()'`
+
+![run_runelite.png](img/building-with-intellij/run_runelite.png)
+
+If you receive a notification regarding Lombok's annotation processing, press ``Enable annotation processing``:
+
+![lombok_annotation_processing](img/building-with-intellij/lombok_annotation_processing.png)
 
-![project-view-run-main](https://i.imgur.com/RXkMc48.png)
+In case of errors regarding missing classes, click the ``Reload All Maven Projects`` in the Maven tab.
 
-If you are having any issues with this step see [Troubleshooting](#troubleshooting) section.
+![reload_maven_projects](img/building-with-intellij/reload_maven_projects.png)
+
+And you are done! RuneLite should open.
+
+If you are having any issues with this step see the [Troubleshooting](#troubleshooting) section.
 
 ## Conclusion
 
-Success! You can switch between running the client and building the Maven project by switching between the **RuneLite** configuration and your custom Maven configuration (should be named *runelite-parent [install]* by default):
+Success! You can switch between running the client and building the Maven project by switching between the ``RuneLite`` configuration and your custom Maven configuration (e.g. ``runelite-parent [install]``):
 
-![select-run-config](https://i.imgur.com/zKSqojU.png)
+![select_run_config](img/building-with-intellij/select_run_config.png)
+
+### Hot reloading
+To help enable a faster edit-run-test development loop, check out [JetBrains's official documentation on hot reloading](https://www.jetbrains.com/help/idea/altering-the-program-s-execution-flow.html#reload_classes).
 
 # Troubleshooting
 
+## WARNING: An illegal reflective access operation has occurred
+You can ignore this.
+
 ## Missing git
 
 If you are getting error about `git.exe` (or `git` on linux and mac) missing, you will need to first download and install Git for your OS. Git is version control software and implementation that RuneLite uses to store and track history of it's source code. To download git, just [go here and select your OS version](https://git-scm.com/downloads).
 
-## Missing JDK
-
-If you are getting errors about missing JDK, make sure to install JDK 11 (see start of this page) and then navigate to *File* -> *Project Structure* like this:
-
-![missing-jdk-project-structure](https://i.imgur.com/IzAKzOH.png)
-
-Then press *+* button and *Add JDK* and locate directory of your installed JDK:
+## Tests are failing
 
-![missing-jdk-add](https://i.imgur.com/ZRHDAk3.png)
+If you've followed all instructions correctly, try deleting the `%TEMP%/cache-165` folder or skipping the tests by running a custom run configuration as outlined in [Building the project](#building-the-project).
 
 ## Client failing to start
 
 If the client fails to boot or if the applet does not appear, try running the Maven build again with the following command:  
 `clean install -DskipTests -U`
 ![mvn-clean-install](https://github-production-user-asset-6210df.s3.amazonaws.com/41973452/246999260-b33934e5-0969-4455-a5ee-adceeaf55f86.png)
 
-If that also doesn't work, feel free to ask for help in the discord server. Here are few helpful tips:
+If that also doesn't work, feel free to ask for help in the [Runelite Discord](https://runelite.net/discord) server. Here are few helpful tips:
 
 <!-- omit in toc -->
 #### Make sure your branch is up to date with master

diff --git a/img/building-with-intellij/access_settings.png b/img/building-with-intellij/access_settings.png
diff --git a/img/building-with-intellij/clone_runelite.png b/img/building-with-intellij/clone_runelite.png
diff --git a/img/building-with-intellij/custom_configuration_top.png b/img/building-with-intellij/custom_configuration_top.png
diff --git a/img/building-with-intellij/download_jdk.png b/img/building-with-intellij/download_jdk.png
diff --git a/img/building-with-intellij/generate_sources.png b/img/building-with-intellij/generate_sources.png
diff --git a/img/building-with-intellij/get_from_vcs.png b/img/building-with-intellij/get_from_vcs.png
diff --git a/img/building-with-intellij/install_skip_tests.png b/img/building-with-intellij/install_skip_tests.png
diff --git a/img/building-with-intellij/installing_lombok.png b/img/building-with-intellij/installing_lombok.png
diff --git a/img/building-with-intellij/language_level.png b/img/building-with-intellij/language_level.png
diff --git a/img/building-with-intellij/lombok_annotation_processing.png b/img/building-with-intellij/lombok_annotation_processing.png
diff --git a/img/building-with-intellij/missing_lombok_errors.png b/img/building-with-intellij/missing_lombok_errors.png
diff --git a/img/building-with-intellij/modify_run_configuration.png b/img/building-with-intellij/modify_run_configuration.png
diff --git a/img/building-with-intellij/new_project_from_vcs.png b/img/building-with-intellij/new_project_from_vcs.png
diff --git a/img/building-with-intellij/project_structure.png b/img/building-with-intellij/project_structure.png
diff --git a/img/building-with-intellij/quick_run_runelite.png b/img/building-with-intellij/quick_run_runelite.png
diff --git a/img/building-with-intellij/reload_maven_projects.png b/img/building-with-intellij/reload_maven_projects.png
diff --git a/img/building-with-intellij/run_maven_build.png b/img/building-with-intellij/run_maven_build.png
diff --git a/img/building-with-intellij/run_runelite.png b/img/building-with-intellij/run_runelite.png
diff --git a/img/building-with-intellij/select_download_jdk.png b/img/building-with-intellij/select_download_jdk.png
diff --git a/img/building-with-intellij/select_java.png b/img/building-with-intellij/select_java.png
diff --git a/img/building-with-intellij/select_run_config.png b/img/building-with-intellij/select_run_config.png
diff --git a/img/building-with-intellij/successful_build.png b/img/building-with-intellij/successful_build.png