CSE 373, Summer 2019: Project Setup

Overview

We will be using Java for all our programming in this course. We'll be using IntelliJ to edit our Java code, and we'll be using Git to distribute and submit code. Additionally, we will use Checkstyle to grade your code style.

All of these systems need to be set up in order for you to work on our projects, and this page will go over how to do so.

Most people will only ever have to follow the instructions on this page once, but if you ever have issues with the following technologies then you may want to try uninstalling and then re-doing the setup instructions here.

Table of Contents

  1. Git

  2. SSH keys

  3. Java

  4. Installing IntelliJ

    1. Download

    2. Installation

  5. Configuring IntelliJ

    1. Startup

    2. Installing the Checkstyle plugin

    3. Selecting the correct version of Java

    4. Making sure Git is detected

    5. Applying CSE 373 settings

Git

What is Git?

Git is a version control system (VCS): a tool for tracking changes between versions of code and sharing those changes with other people. A VCS allows you to not only see changes from old code, but also revert back to older versions or create alternate versions, which you can later merge back together.

Git is one of the most widely-used VCSs; this is due in part to its flexibility, but its surrounding ecosystem also plays a large role in its popularity: many of you who aren't familiar with VCSs have still probably heard of GitHub, which has become a leading platform for open-source projects.

So, what is GitHub? GitHub is essentially a website that provides servers for Git repositories (repos). In the context of VCSs, a repository is a copy of your code and its history—it's a data structure representing your project. When working with multiple users in a Git project, each user has their own copy of the code repository on their machine. To share code, all users sync their local repositories with a single remote repository on some server—these repositories are what GitHub provides.

Now that we've gotten that introduction out of the way, we won't actually be using GitHub in this class. Instead, we'll be using GitLab, a Git-repository hosting service similar to GitHub, but open source so that it can run on our CSE servers.

(Windows only) Installing Git

Only Windows users should need to install Git manually.

Meanwhile, macOS should come with Git, and Linux operating systems should have easy access to git via the built-in package manager, so this guide is only for Windows. (If you're using Linux, we'll assume you know where to look if you need help installing Git.)

Note that most of the options in this process don't matter for this class. The screenshots in the walkthrough below show settings for one example installation, but you may choose other options unless we explicitly state otherwise in the steps below. Additionally, if there are any screens or settings in the installer that are not included in this guide, leaving those settings default should be fine (alternatively, you may apply common sense to choose those options).

  1. Download and run the Git for Windows installer from this page.

  2. Accept the license by clicking "Next >".

  3. On the next screen, choose any additional components you want, or just leave them default. None are required for the class, but none take any significant disk space, so it's fine to do whatever.

  4. On the next screen, you can choose a default text editor for Git. We won't need to run Git from command line, so Git should never actually use this setting, so it's again safe to select anything here; if you don't have any of the listed programs installed already, we recommend just selecting the one for Nano.

  5. On the next screen, choose which Git tools will be available from command line. We strongly recommend you choose the default option, as shown below:

  6. On the next screen, choose an HTTPS backend. This choice shouldn't matter, so the default is fine.

  7. On the next screen, choose how line endings will be treated. We strongly recommend choosing the default option, since anything else will likely produce formatting errors between operating systems.

  8. On the next screen, choose which terminal emulator Git Bash will use. The two options have slightlly different behaviors and configuration options, but both are functional, so it doesn't matter which you choose here.

  9. The last screen presents some more miscellaneous options. There isn't much reason to disable any of these, so you can just leave them enabled (or disable them if you want.)

  10. Afterwards, click "Install", and the installer should install Git. When it finishes, you can close it without starting Git Bash or viewing the README file.

SSH keys

What are SSH keys?

SSH keys fill the same role as a username and password, in that they are used to authenticate with servers. The general idea is that you generate a pair of keys using some program, upload one key to servers to associate with your account, then send the other to the server whenever you need to log in instead of using a username and password.

The key meant for sending to servers is called the "public key," and the one for actually authenticating is called the "private key." Make sure you keep your private key to yourself, since anyone can use it to authenticate as you.

You may upload the same public key to many servers if you want to use the same private key for authentication, so feel free to re-use an existing one if you have any already. In this case, you may skip to the second part of this guide: adding the SSH key to GitLab. If you do not have an SSH key yet, you'll need to start with the next section.

Generating an SSH key

We'll refer to the GitLab SSH setup guide for instructions here, but first, some notes:

  • We recommend using the ED25519 algorithm to generate SSH keys, as in the first of the two examples in the guide. You can scroll up to the previous section on that page for some more details.
  • You should leave the key in the default location with the default name so that other applications, such as your IDE, can detect it automatically.

Okay, now that we've gotten that over with, here's the link to the guide.

Assuming that you've generated your keys properly and in the default location, programs such as IntelliJ and the command line version of Git will automatically attempt to use your private key when authenticating with servers.

Need to move your SSH key?

If you already have a key and thus need to save this one somewhere else, you'll need to create a config file at ~/.ssh/config like the following example in order to tell programs where to look for your ssh key:

gitlab.cs.washington.edu
    IdentityFile ~/.ssh/some_key_name

This will tell programs to use the SSH key in "[your home/user directory]/.ssh/config" whenever connecting to the server gitlab.cs.washington.edu (which is the CSE GitLab server).

Adding an SSH key to GitLab

Again, we'll just direct you to GitLab's guide for adding SSH keys.

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.

We recommend you use Java 12 in this class. You will need Java 8 or newer in this class to run our provided code. The link above will take you to the correct Java download page.

Installing IntelliJ

Step A: 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 system 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 2019.1.

(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 B: 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.

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 already 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.

In this case, simply open the relevant project, then follow the instructions below another time, but use "File" > "Settings..." to open project settings, and "File" > "Project Structure..." for project structure.

Step A: 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 Remaining 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 B: 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 C: 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 "12" (i.e., Java 12).

    Missing option for 12?

    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 D: 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 E: 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.