CSE 373, Winter 2019: IntelliJ Setup Guide

Step 0: Installing Java

Before you start installing IntelliJ, make sure that you have the Java Development Kit (JDK) installed on your system. If you're not sure, it's safe to just try installing it again: if you already have the JDK installed, installing it again will just update you to a slightly newer version. (Also remember that the JDK differs from the Java Runtime Environment (JRE); the JRE allows you to run Java programs, but if you also want to program in Java, you'll need the JDK.)

To download the JDK, go to this page and download the appropriate file for your operating system.

Note: while the latest version of Java is Java 11, we strongly recommend you use Java 8 in this class. While our course projects should work in theory with newer version of Java, they have only been tested with Java 8. The link above will take you to the Java 8 download page.

Step 1: Installing IntelliJ

Step 1a: Download

NOTE: If you've used IntelliJ before, you may have an older version installed, but we strongly recommend you install the latest version for maximum compatibility. Some previous versions of IntelliJ had worse support for Gradle, the build sytem we use for our projects, and thus require extra configuration to work properly.

You can download IntelliJ from the IntelliJ website here. The community version will suffice, although you may download the ultimate version if you want (you can sign up for a free student license, although it may take some time to activate). The latest version, as of time of writing, is 2018.3.3.

(You may also download the JetBrains Toolbox, an installer/manager for all of JetBrains IDEs, and then use that to install IntelliJ instead. For this class, you will not need more than a single version of IntelliJ, so Toolbox is not particularly useful, but it can be convenient if you decide to continue using IntelliJ or other JetBrains IDEs in the future. The download page is here.)

Step 1b: Installation

Run the IntelliJ installer. You can keep hitting "Next" and select all the default options, or you may change these settings if you want; anything should be fine.

Step 2: Configuring IntelliJ

Parts of this section will involve changing the IntelliJ project settings for new projects. These settings only apply to new projects; if you have alredy imported a project for a homework assignment, these settings will not apply to that project, so you will need to apply them manually to that project as well.

Additionally, if you do not wish to change your settings for new projects, you can use the single-project workflow we describe in the project import page and apply the settings to only that project instead of all new projects.

In either of these cases, simply open the relevant project, then follow the instructions below, but use "File" > "Settings..." to open project settings, and "File" > "Project Structure..." for project structure.

Step 2a: Startup

You can probably skip this section if you're using an existing IntelliJ installation; just make sure you have the proper default plugins installed as described.

  1. Start IntelliJ. If you're running this version for the first time, you'll probably see a screen like this:

    The options will vary depending on whether you have previous versions of IntelliJ installed. If you do and wish to import the settings from that version (or you otherwise have custom IntelliJ settings you wish to import), you may do so. Otherwise, just select "Do not import settings" and continue.

  2. If you choose not to import settings, you'll see a screen like this:

    If you don't care about customization, you may select "Skip Remainaing and Set Defaults", otherwise, you can choose a color scheme and continue. The next screen will allow you to select default plugins:

    The Gradle and JUnit plugins will be required, and the Git and Terminal plugins are recommended, but all other plugins can be safely disabled (or you can just leave them enabled). The next screen will present more plugins; you can skip these too or install them if you want.

  3. Once you're done with configuration, you should see a "Welcome" screen like below.

Step 2b: Installing the Checkstyle plugin

Before we continue, you'll want to install the Checkstyle plugin, which will automatically provide feedback from the Checkstyle code analysis tool that we will use to grade your code style.

  1. To install the Checkstyle plugin, first open the Plugins window from this screen ("Configure" > "Plugins"), then search for the CheckStyle-IDEA plugin by Jamie Shiell.

    The plugin's page should look like this:

    Then, click the "Install" button to install the plugin (you'll also need to accept the privacy note; this plugin really shouldn't be accessing private data at all–you can check the source code to be sure–but if you're uncomfortable with this, you may check the checkstyle resource page for alternatives).

    After the installation finishes, you'll need to restart the IDE for it to apply; click the "Restart IDE" button and confirm to continue.

Step 2c: Selecting the correct version of Java

  1. From the welcome screen, open the default project structure window ("Configure" > "Project Defaults" > "Project Structure").

  2. In the "Project Settings" > "Project" item in the left-side navigation menu (this should be the default item), click the dropdown under "Project SDK" and select "1.8" (i.e., Java 8; you may try a newer Java version, but our projects are only tested on Java 8).

    Missing option for 1.8?

    If the option is missing, that means IntelliJ can't find your Java (JDK) installation. To add a JDK installation, click the "New..." button, then select "JDK" from the dropdown.

    IntelliJ should open a directory selection window at the default JDK installation path, where you should select your desired JDK folder (not a JRE folder). If you cannot find your JDK installation here, you may have installed it somewhere else, in which case you'll need to navigate to that location first; otherwise, you probably did not install the JDK properly, in which case you should reinstall it.

    Afterwards, go back and select that version of Java as the default "Project SDK", as instructed previously.

Step 2d: Making sure Git is detected

  1. Open the Settings window for new projects (Welcome screen > "Configure" > "Settings").

  2. Navigate to the "Version Control" > "Git" item. The screen should look like this:

  3. Click the "Test" button to check whether your Git executable is correctly detected. You should get a popup like this:

    Otherwise, you'll need to click the "..." button to the left of the "Test" button to find and select your Git executable. If you're on Windows and Git was not automatically detected, try looking in the %LOCALAPPDATA%\Programs directory for Git\cmd\git.exe. If it's not there or you're on another operating system, you'll need to figure out how to locate your Git installation.

Step 2e: Applying CSE 373 settings

Once IntelliJ has finished restarting, we need change some settings to make working with the CSE 373 code style easier.

Loading the CSE 373 style rules

  1. Navigate to the Settings window for new projects (Welcome screen > "Configure" > "Settings").

    Now, open the settings for Checkstyle at the bottom of the left-side navigation pane. You should see a window that looks like this:

    If you do not see settings for "Checkstyle", you probably have not installed the Checkstyle plugin correctly and should do that again (or you haven't restarted the IDE).

  2. Change the "Scan Scope" dropdown in the top right to "Only Java sources (including tests)".

  3. Click the "+" button on the right side under Configuration File. In the window that appears...

    • Enter a description for the checkstyle settings for this class in the "Description" text box (e.g., "CSE 373 style").

    • Do one of the following:

      • Select "Use a Checkstyle file accessible via HTTP" and paste the URL of the 373 Checkstyle settings file into the "URL" text box. (From your browser, right click the link and select the option to copy the link.)

      • Select "Use a local Checkstyle file", download the 373 Checkstyle settings file (saving them somewhere that you'll remember and that won't move or get deleted later), and select that XML file in the "File" selector. (From your browser,right click the link and select the option to download or save the link.)

        (This option may be more stable if you plan to code without internet access, or if the course website goes down for whatever reason.)

    • Continue, and click "Finish" after the file is validated. If the validation fails, the download may have failed, in which case you should try again, or you may have an old version of the Checkstyle plugin, in which case you should update the plugin from the Plugins window.

  4. After clicking "OK", you should now be back to the "Preferences" window. Click the checkbox in the row of the configuration we just added to enable it. Your screen should now look like this:

  5. Click "Apply" to apply settings without closing the window.

Enabling stricter generics checks

The next step is to configure IntelliJ so it catches a common generics-related issue:

  1. Navigate to the Settings window for new projects (Welcome screen > "Configure" > "Settings").

  2. Open the "Editor" > "Inspections" item.

  3. Within that screen, navigate to the "Java" > "Java language level migration aids" > "Java 5" section, enable the "Raw use of a parameterized class" item, change the "Severity" from "Warning" to "Error", and change the checkboxes below to match this image:

  4. Click "Apply".

Configuring other IntelliJ settings

There are a couple style-related default settings that differ from our Checkstyle settings, so it'll make your life easier if you change them to match. The settings listed here may not be all-inclusive; feel free to tell us if we've missed any.

  1. By default, IntelliJ's comment command (Ctrl+/ by default) adds comment markers at the beginning of the line, which conflicts with our Checkstyle settings.

    To fix this, open the Settings window for new projects (Welcome screen > "Configure" > "Settings"), navigate to "Editor" > "Code Style" > "Java", then select the "Code Generation" tab. On that screen disable "Line comment at first column" and "Block comment at first column". (You may optionally enable "Add a space at comment start".)

  2. Click "OK" to apply the settings and close the window.