Your new Wii Bundle with Wii Sports has finally arrived and you can't wait to get it working. By buying a Wii you'll be able to both play "sports" and use the console to complete your CS32 assignments! The only problem is that the development environment isn't setup out of the box.
In this lab you'll set up a development environment so that you can work on course projects and labs efficiently throughout the semester.
|Table of Contents|
|Where to Work / Working From Home|
|Configuring Your IDE + Checkstyle: Eclipse|
|Configuring Your IDE + Checkstyle: IntelliJ|
Where to Work / Working From Home
You are free to work on projects for the course on whichever machine you'd like.
Always make sure to run your code on a department machine before turning it in. If we can't run your code, then you will receive deductions. Check out the SSH and Port forwarding section for an explanation of how to check your code on a department machine without physically being on a department machine.
If you prefer to work from a personal machine follow the below steps in either the MacOS/Linux or Windows section to set up Maven and the Java JDK. This will allow you to run your code through the command line. We will learn how to set up an IDE (Integrated Development Environment) such as Eclipse to work with the code in the next section.
Getting a Shell
To run almost every program in CS32, we'll be using the shell, as opposed to running programs through a file explorer or from the desktop. The shell can be intimidating if you haven't used it a lot before, but it doesn't need to be! If you need an intro to the shell, you can view our guide, Shell Basics.
To open a shell/terminal on MacOS, just go to your applications, find "Terminal", and open it! You can also get here by searching "Terminal" on Spotlight.
To open a shell/terminal on most versions of Linux, you can either use the shortcut CTRL-ALT-T, or search "Terminal" in any application finder.
Installing a Package Manager
Package managers are very powerful tools to know how to use on both MacOS and Linux. These allow you to install programs and be sure that the program you're getting is the same one everyone else is getting.
We strongly recommend using homebrew to install Maven. Homebrew is a package manager for OS X that makes installing packages as easy as a simple terminal command. To get homebrew run the following command in your terminal:
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
To check if Homebrew is already installed or if you installed it correctly, run
brew -v. This should
output the version of Homebrew that's installed.
Now, if you need to run a program from the command line, but don't have it yet, a good first option is
brew install <program-name>.
Debian and Ubuntu already come with a package manager installed, APT. To use it to install a program, just run
apt-get install <program-name>
(this may require
sudo apt-get install <program-name>).
In CS 32 we're going to be using Java 11. Throughout the course you'll learn a lot about the new features introduced in this version and how you can use them to your advantage. To code in Java 11 you'll need to download the JDK (Java Development Kit) here for whichever computer you're working on. Download JDK 11.0.6. Then, unzip the file and install.
Additionally, here are two good tutorials for installing the JDK on Debian / Ubuntu.
Next we're going to set up Maven and your JAVA_HOME environment variable. Maven is a build automation tool that we're using to manage libraries and build your projects. Check out the Boggle assignment for more information about Maven. The JAVA_HOME variable is an environment variable that you can set on your computer to tell it where the Java compiler exists in the file system.
To set your JAVA_HOME variable, copy the following into your terminal:
Here's what this command does:
Your computer uses an environment variable called
echo "export JAVA_HOME=$(/usr/libexec/java_home -v 11)" >> ~/.bash_profile
JAVA_HOMEto keep track of where Java is installed. By default on Mac, the JDK installs Java 11.0.x to
/Library/Java/JavaVirtualMachines/jdk-11.0.x.jdk, so we want to set
/Contents/Homedirectory of this path. However, if you were to update your version of Java, this path would change. Luckily,
/usr/libexec/java_home -v 11always returns the correct
JAVA_HOMEfor any Java version 11. Wrapping this command in
$(<my_command>)saves the output of
<my_command>as a string, which we then set
Once you've done this, run the following to make sure the variable is set properly.
$ source ~/.bash_profile $ java -version java version "11.0.6" 2020-01-14 LTS Java(TM) SE Runtime Environment 18.9 (build 11.0.6+8-LTS) Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.6+8-LTS, mixed mode)
If the version starts with 11 then you've set the variable properly.
Maven on MacOS:
To install Maven, we'll be using Homebrew. Just run
$ brew install maven.
Maven on Debian & Ubuntu:
If you've previously have Maven 2 installed, then you may need to run
$ sudo apt-get remove maven2
Then for either distros you can run,
$ sudo apt-get install maven
to get Maven 3, and you can double check that its the right version the same
way as we mentioned above for Mac.
If Maven complains about
JAVA_HOME, then you can set
JAVA_HOME in your
although there's a good chance that this may not be needed. Your JDK will
be installed in
And now you should have Maven installed! To double check, run
mvn -version and you should get something like this:
$ mvn -version Apache Maven 3.6.0 (97c98ec64a1fdfee7767ce5ffb20918da4f719f3; 2018-10-24T14:41:47-04:00) Maven home: /usr/local/Cellar/maven/3.6.0/libexec Java version: 11.0.6, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-11.0.6.jdk/Contents/Home Default locale: en_US, platform encoding: UTF-8 OS name: "mac os x", version: "10.15.1", arch: "x86_64", family: "mac"
Getting a Shell
We will also being using bash scripts to run our programs from the command line. Although Windows has a shell (PowerShell), PowerShell has its own language and can't run bash scripts. So, you'll need to download a tool that does. One option is Git Bash, an emulator that acts like a Linux command prompt. It comes with the normal installation of git, which you'll need for this course later anyways. You can download Git here . Another option is WSL. Both are acceptable to use throughout this course. Once one of these is installed, you should be able to open it up and use it as a normal terminal.
In CS 32 we're going to be using Java 11. Throughout the course you'll learn a lot about the new features introduced in this version and how you can use them to your advantage. To code in Java 11 you'll need to download the JDK (Java Development Kit) here for whichever computer you're working on. Download JDK 11.0.6. Then, run the .exe installer and follow the prompts.
First, we will need to set the JAVA_HOME and also edit the PATH environment variables. Setting the
JAVA_HOME variable tells Maven where to find your instillation of the JDK,
and editing the PATH variable tells your shell where to find the JDK to run Java commands. We recommend
for how to set your JAVA_HOME variable and edit the PATH variable. You will need to replace
C:\Program Files\Java\jdk1.8.0_60 in Step 3 with
Note: To make sure this step was properly completed, open the terminal you previously installed
java -version and then
javac -version. You should see some version information,
including the version number of the JDK you installed. If you are getting an error message,
try to make sure you did not accidentally skip a step in the above guide, or contact the TAs on Piazza for help.
FAQ: Why do we set the JAVA_HOME and the PATH variable instead of just the PATH variable?
If you have previous experience with setting Windows environment variables, you may be wondering why we set both a JAVA_HOME variable and the PATH variable. In fact, pointing the PATH variable directly to the /bin folder of your installed JDK is enough to tell your shell where to locate your installed files. But, Maven requires the JAVA_HOME variable to be defined in order to work properly, so we first set the JAVA_HOME variable and then set the PATH variable.
Installing Maven and Setting MAVEN_HOME
Next we're going to set up Maven. Maven is a build automation tool that we're using to manage libraries and build your projects. Check out the Boggle assignment for more information about Maven.
Note: To make sure this step was properly completed, open the terminal you previously installed
mvn -version. You should output similar to this:
Apache Maven 3.6.0 (97c98ec64a1fdfee7767ce5ffb20918da4f719f3; 2018-10-24T14:41:47-04:00) Maven home: C:\Program Files\apache-maven-3.6.0 Java version: 11.0.6, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk-11.0.6\jre Default locale: en_US, platform encoding: Cp1252 OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
If you are getting an error message, check the FAQs on the guide, or contact the TAs on Piazza for help.
FAQ: Why do we set the MAVEN_HOME and the PATH variable instead of just the PATH variable?
Again, you may be wondering why we choose to set both a MAVEN_HOME variable and change the PATH variable. In this case, setting the MAVEN_HOME variable makes it easier to switch versions of Maven (which we will not be doing in this class). For instance, if you wanted to switch to an older version of Maven (maybe you are using an older JDK that is not compatible with the newest version of Maven), you would only need to edit the MAVEN_HOME system variable if you had it properly set beforehand. But, if you did not set MAVEN_HOME, you would need to directly edit the PATH variable. In older versions of Windows, editing the PATH variable was a bit more difficult. Instead of the nice editor you are given in Windows 10, you had to edit a single, long string of text. You may have noticed this if you saw the screenshot in section 4.1 of the setting JAVA_HOME guide or if you are on an older version of Windows. Thus, it was simply easier to set the PATH variable once and change the MAVEN_HOME variable if necessary.
Configuring Your IDE + CheckStyle: Eclipse or IntelliJ
Your IDE will help you build your projects more efficiently. In addition, setting up Checkstyle directly within your IDE will allow you to avoid having hundreds of style warnings after completing your projects. Below are instructions for setting up Eclipse and IntelliJ, our two recommended editors. All TAs will be able to help you with Eclipse, but IntelliJ is newer and more advanced. You are also free to use any other editor you prefer, though TAs will not be able to help you set them up.
Setting up Eclipse
1. Installing Eclipse: To install Eclipse, download the Eclipse installer here. Select "Eclipse IDE for Java Developers." Eclipse 2019-12 4.14 is the preferred version for the course. Now Open your Eclipse Installer and select Eclipse IDE for Java Developers, then Install. Wait impatiently.
2. Setting Up Java 11: Once it's installed, open up Eclipse. You now want to add Java 11 by
Eclipse → Preferences → Java → Installed JREs. If there is an installed JRE
Java SE 11.0.6 you're good.
Otherwise, press Add, select
Standard VM and click next. Remember when we set the
variable? Good times. Set
JRE home to the path stored in
JAVA_HOME. You can find this by opening a Terminal and
echo $JAVA_HOME. Set
JRE name to "Java SE 11.0.6" and hit finish. Don't Apply and Close just yet!
3. Setting up the Java 11 compiler: On the left navigator go to
Java → Compiler and
compliance level to 11. Now hit Apply and Close.
4. Importing a Maven project: To import a Maven project (such as Boggle), we need to tell Eclipse where it is. First select File > Import.
Then select Maven > Existing Maven Projects.
Finally, browse to your project directory and select the pom.xml file that appears.
Click finish, and your project should successfully be imported into Eclipse!
Automating Eclipse Checkstyle
Our standards for code style are outlined in our style guide, and we use the Checkstyle plugin for Maven
to detect errors (
mvn site). You can use Eclipse to auto-format your code upon saving: this will
you time fixing small style errors such as too-long lines or trailing whitespace. Note that the options below
fix all Checkstyle errors (more complicated fixes aren’t automated), so you should still check Maven
before handing in your project.
First, open up any of our projects (e.g. Boggle) in Eclipse.
Project → Properties.
Java Code Style → Formatter.
- New... and choose a name.
- Indentation → Spaces only, Indentation size = 2
- Line Wrapping → Maximum Line Width 100
- “New Lines” → In “Array Initializers” section: Select both
After opening brace of array initializerand
Before closing brace of array initializerThen OK.
Java Code Style → Clean Up
- Edit... and tick
Format source code,
Remove trailing whitespace (all lines),
Organize Imports. OK.
- Edit... and tick
Java Editor → Save Actions → Format all lines.
Additional Save Actions, then click Configure.... Tick
Format source code,
Remove trailing whitespace (all lines), and
SSH & Port Forwarding
If you need to test your servers remotely on a department machine, you'll notice that your server will be hosted at localhost:4567 on the department machine, but you will have no way to access it on your own computer. To get the remote machine's port bound to your own machine's do the following when SSH-ing:
- ssh as you would normally and start up your project.
- Take note of what machine your server is running on (e.g. cslab4g, hertz, mslab-1, etc).
ssh <username>@ssh.cs.brown.edu -L 4567:<machine name>:4567
Now if you visit localhost:4567 on your local machine, you should be able to visit your page - which is running on the department machine, with no problem!
Alternatively you can also run,
ssh -f <username>@ssh.cs.brown.edu -L 4567:<machine name>:4567 -N
To execute the port binding in the background - if you don't want to have a
useless terminal laying around. If you do it this way be sure to kill this
process manually when you're done with it. Namely, you can track it down with:
ps aux | grep ssh
and kill it by its PID.
Configuring Your IDE + CheckStyle: IntelliJ
Setting Up IntelliJ
IntelliJ is another popular Java IDE, created by JetBrains. You may find that you prefer IntelliJ to Eclipse. IntelliJ contains many of the same features as Eclipse and has some of its own unique features that you may find useful in your projects. However, your choice of IDE is largely just preference, and using either will be sufficient for CS32.
1. Getting access to IntelliJ: IntelliJ actually has 2 versions, one free and one paid. However, as a student, JetBrains gives you access to the paid version for free. There are 2 easy ways to get access to this version. One, sign up for a GitHub Student Pack. This pack also includes other goodies you might find useful for your coursework at Brown or for your personal projects. Two, sign up for a JetBrains account using your Brown.edu email. Note that either option gives you access to JetBrain's full line of products, in case you are interested in any of their other IDEs or other tools.
2. Installing IntelliJ: You can download IntelliJ here. Grab the Ultimate edition, and then follow the installer's prompts to finish installing the software. The standard plugins are sufficient, but feel free to add any additional plugins you want.
3. Importing a Maven project: To import a Maven project, we need to first tell IntelliJ
where it is.
From the "Welcome to IntelliJ" screen, go to
Import Project. If you have another project
already open in IntelliJ, you may need to click
File → Close Project to see the welcome screen.
Navigate to the directory containing the pom.xml file for your project.
For this example, my project is located at the top level of my hard drive.
Once you have found the directory, make sure to select the pom.xml file and then click
Now import the project using the settings below. We marked the settings that are not selected by default in red.
Now, you can simply keep clicking
Next to finish importing the project. The pop-ups follow
- What Maven project to import (there should only be one)
- What SDK to use. IntelliJ should automatically detect any installed Java SDKs. If you have more than one, make sure to select the Java 1.8 SDK.
- What to call the project and where to keep it. You can keep the default values, or change the
project name or location to your liking. You should see the
Finishbutton on this pop-up window.
Once you finish importing the project, a screen similar to this should show up:
Setting Up Checkstyle for IntelliJ
We recommend this plugin for
managing checkstyle on IntelliJ.
You can manually install the plugin from the zip file. Alternatively, navigate to
File → Settings... → Plugins and install the plugin directly from the JetBrains
You may also need to accept the license pop-up that shows up. Finally, restart the IDE to finish
installing the plugin. Note that you will need to re-do this process whenever you import a new Maven
1. Importing the Checkstyle file:Navigate to
File → Settings... → Checkstyle to manage/add a checkstyle file.
Feel free to call the checkstyle profile whatever you want. The checkstyle file is located in the config
directory of your project
(for Boggle, this would be /boggle/config/cs32_intellij_checks.xml, assuming you did not change the
boggle project structure),
and should be called cs32_intellij_checks. We provide this second checkstyle configuration for IntelliJ because
it has slightly different rules than Maven. Follow the steps below and hit
Finish to finish
2. Marking the Checkstyle profile as active:Next, simply select the newly import checkstyle profile and mark it as active. Then apply the changes.
3. Using the Checkstyle profile:If you click Checkstyle at the bottom of IntelliJ, a box
should pop up. The active configuration should be the CS32 one you just imported and marked as active.
If you aren't show what the active configuration is, you can manually select the CS32 Checkstyle profile
Rules drop-down box.
The buttons on the side scan your project directory for Checkstyle violations and report them to you in
the box. If you aren't show what a side button does, hover over the button for an informative pop-up.
Finally, you can click on a violation, which will cause IntelliJ to take you directly to the line that
is causing the violation. Using this, you should be able to find and resolve most Checkstyle issues.
As always, use the Checkstyle report from
mvn site to make sure you have no Checkstyle
error before you handin, as the plugin may not catch every error.
What is Maven
Maven is a project management tool developed by the Apache Foundation. It is designed for use in projects that are primarily written in Java. Maven keeps track of key information about a project, including its name, version, and dependencies.
Why use Maven
Maven allows us to quickly organize and build projects by automating tasks such as including libraries and packaging projects into a finalized version. Among other things, this enables us to quickly and reliably transfer projects between computers.
Maven File Structure
The default structure for a Maven project is your project directory which contains a pom.xml file and a src directory. Inside src you can find a src/main/ directory and a src/test/ directory. Inside the main directory you can find a src/main/java/ directory and src/main/resources directory. The java directory can be expanded further to find your classes and the resources directory contains files used the build the frontend portions of your projects for this class. Unit tests can be found in /src/tests/.
|-- pom.xml // pom for maven `-- src // upper level src directory |-- main | `-- java | `-- edu | `-- brown | `-- cs | `-- <your username> // contains your classes and packages | `-- <project name> | `-- Main.java `-- test // contains unit tests, same directory structure as main `-- java `-- edu `-- brown `-- cs `-- <your username> `-- <project name> `-- AppTest.java
Make sure you've already installed maven using the instructions above. Maven is used via the mvn command, which is already installed on department machines. Maven commands take the form of mvn <command> <arguments>. The most commonly used commands are listed below.
|compile||Compiles project but does not run unit tests.|
|package||Compiles project, runs tests, and creates a JAR file to be run.|
|test||Compiles test sources and runs units tests.|
|clean||Removes the target directory containing build data.|
|site||Generates pages in /target/site/ directory where you can see reports from plugins such as checkstyle.|
After building your project with Maven, a .jar file will be generated in the target directory of your project. This is the compiled version of your code, ready to be run. The best way to run this code is with the run shell script, which is already included in the Stars project. For a description of how it works, see its in-line comments.
Building your project
We usually supply a
mvn packagefrom inside the project directory (e.g. Boggle, Stars) to compile the project and produce an output .jar file (in the target/ directory). The first time you run
mvn package, you'll see maven downloading a lot of libraries. That takes a while, but don't worry, that will only need to happen once.
You can run
mvn clean to start fresh (which you
should do after you change class or package names, for example). For
more information about maven, see the useful
links at the bottom of this page.
Checking style errors
Normally, we expect you to write extensive test cases for your code. That's the best way to be confident that your code is correct. However, there are some tools that we've set up for you that will pick up some simple mistakes, both in formatting and in common error-prone code patterns (also known as "anti-patterns").
You can invoke these tools my running
That command tries to generate a complete website for the code being
built and puts the results in the target/site subdirectory
of your project. (Again, the first run will do some downloading.)
Visit the generated site by using a "file://" url. Use something
You'll have to change that depending on where you put your project directory. Once you open the site, you should see something like this:
At the lower left, click on "Project Reports". You should see five reports.
- Source Xref is a clickable version of your source code. The other reports point here to show you their results.
- JavaDocs is the generated documentation from the JavaDoc comments you have in your code.
- Checkstyle is a report generated using a set of rules that the course staff has developed for cs32 code. Until you become used to these rules, we suggest you consult this report often. You will lose points if you violate these simple code formatting rules!
- PMD is static checker that looks for bad programming practices.
- SpotBugs reports on code patterns that often lead to
subtle bugs. SpotBugs works on .class files, not
.java files, so you'll have to recompile (
mvn package) before you'll see your changes in
- Surefire Report reports on the success / failure of your unit tests.
- JaCoCo This is a “coverage report”. It can help you find code that you haven't really tested. It shows you which lines of code were actually executed during all of your unit tests.
Some of these reports disappear if they have no errors to report. That's a good goal! The first thing we'll do when looking at your handins is to run these reports and check the output. If you leave code in your handin that violates any of these rules, expect to lose points unless you have a very good reason.
As questions arise, we will update this section.
|Unknown Build Issues||If you're ever stuck, the first thing you should do is a complete rebuild of your project. This can be accomplished by running mvn clean before you run mvn package.|
|Invalid Target Release: 11||Visit the "Setting Up" section of the Boggle project and ensure that you've properly followed the given instructions.|
Git is one of the most commonly used systems for version control which allows us to manage changes in our code and collaborate with others. You'll want to make sure that git is set up on your machine, and start getting familiar with the basic git commands.
Before installing Git, you first want to check if it is already installed on your machine. To do so, open
terminal and type
git --version. If terminal echoes out the version, then Git is installed.
Essential Git Commands
||Clone a repository. This makes a new folder in the current directory containing the files in the repository in which you can work on the code.|
||Add the given file to the repository so that it will be
tracked by git. Use this when you author a new code file and
want to include it in a commit. Alternatively, include
|git commit||Finalize the current changes to your code as a commit to
your current branch and repo on your local
|git pull||Pull any changes that have happened on the remote server you
initially cloned and bring them into your local
repository. You will need to have a clean repo so you will
probably want to commit first if you have changes (or stash
|git push||Push whatever commits you have made locally to the remote repository that you cloned previously. You may need to pull first to ensure that you are in sync with the repo.|
|git log||View history of commits that you have made. They will be displayed with their unique identifier (a big hex mess like 766f98f32fa...) and their commit message.|
Check out the Git Reference page for more information on git commands.
After you finish making any major changes to your project, you will want to update the remote repo on GitHub using the following steps:
git add -Ato add all changed files. Or, you can selectively add files with
git add /path/to/file.
git commit -m "<DESCRIPTIVE SUMMARY>"to save your changes locally. Think of this as setting a checkpoint that you'll be able to return to whenever you'd like. You'll need to add any files you want to save before making a commit. Be sure to include a short summary of your changes.
git pushto upload your changes to the remote repo on Github. You can log on to Github and navigate to the repository to see your changes.
You can also run
git status to check that all your changes have been pushed
and that your working tree is clean.
Git is a powerful version control system, and we've only cracked the surface. Since you're the only one editing this repo, you won't have to worry about what happens when someone else wants to make a change to the same file you're working on. We'll explore other features of Git later, but you're encouraged to learn more here.
When someone does want to make a change to the same file you're working on, you might get a merge conflict. Here is the course page about this unhappy event.
This Weird Window Opened!
If you enter a command like
git commit (without the
-m) flag, git will
open up a text editor to ask you what message you want to provide with the commit.
If you haven't already specified it, this text editor could look one of a few ways:
If your terminal looks like this, there's a few steps to add a commit message.
i (to enter "insert" mode). Then, type your commit message.
ESC (the escape key), and then
If you terminal looks like this (with the commands at the bottom), just type your commit message, type
CTRL-O (press the control key and the o key at the same time),
press enter, and type
Other Useful Features
We don't necessarily expect you know these but it wouldn't hurt to be aware of them because you will find them useful.
||View the difference between the current code and the latest commit. You can also enter two commit IDs to see the difference between the code at each of those commits.|
||Reset the state of your repo to that of a specific commit from the past.|
|git stash||Stash away the latest uncommitted changes. Later, you
|git config --global core.editor $editor||Change the default editor to one of your choice. By default git uses vi as an editor, but if you're uncomfortable with it you can use this command to switch to something like emacs|
- The department's Sunlab resources will help you set up ssh so that you'll be able to login and work on department machines from elsewhere. You should follow the advice about setting up ssh, but be wary of following the advice for setting up remote desktops or access to X applications. Using GUI applications like Eclipse or a web browser will be painfully slow over a remote link.
- Wikipedia page - Surprisingly good overview on Maven basics, pom.xml structure, and philosophy. (Recommended Read)
- Maven's Getting Started Guide - Official in depth tutorial if you're interested but also does some things different than what's needed for us.
- M2Eclipse - If you're looking to use Eclipse, this is official plugin for maven integration.
- Official documentation for Spark. Please be aware that they use Java 8's new lambda expressions to neaten the syntax of route handlers. To avoid overwhelming you we have implemented our Boggle code without this syntax. It's up to you which syntax to use — but we want you to understand that lambda expressions are transformed to code you could write with the older syntax.