CS32 uses a lot of tools and libraries that you may have not seen before. This guide is intended to give you a brief overview of all of these tools so that when you run into problems, you have a basic understanding of how things work and what might have gone wrong. We talk more about how to set up these tools on your own computer here. If any of the topics covered here are unclear or you run into problems you don't know how to handle on your own, don't hesitate to ask questions on Piazza.
The "shell" refers to a suite of command-line interfaces; ways of interacting with your computer without using graphical applications. You interact with the shell using the "Terminal" application. If you have a Windows computer, you'll have to install Git Bash or the Windows Subsystem for Linux to follow our guides. Linux shells (including the ones on the department machines) use a language called bash, while Macs use zsh by default. The actual differences between the languages are minimal - we have a guide here that should get you familiar with basic file operations.
Git is a powerful tool that helps programmers control versions of their code. To explain why it's useful, let's say you've thought of a fix
for a bug you have, but you're not sure if it'll work or not. You can try to implement this fix, but if it doesn't work, you've written
a lot of new code that you'll have to remember to remove, or else risk adding new bugs. Git lets you save a working state in a "commit"
so that throughout your project, all of the states your code has been in are saved. This is also powerful when you're working in a team.
You can "commit" a new feature and "push" it to Github - the online git client we use in this class - so your partner can "pull" it. If
code they've written conflicts with one of your changes, it will highlight the conflict in a way that's very easy to notice.
We have a more detailed explanation of the commands you might use here and a guide on resolving merge conflicts (when your partner and you have written conflicting code) here.
Maven is what's referred to as a "project management tool". This means that it manages all of the parts of a project that programmers
shouldn't have to deal with. What's this, you might ask? Well, the most significant feature (for this class) is that it manages your
dependencies. When you import a class that's not in Java's standard library (i.e. Spark or Guava), you would normally have to
download that file and put it in your project folder. Maven handles all of that for you. This is especially important when moving from
computer to computer. If you're working on your laptop and import a package, then run
mvn package, you'll see a couple of lines that
mention "downloading" a "dependency". When you move to a department machine, you'll see the same lines. But all of that is done without
you thinking about it. These dependencies are downloaded to your
~/.m2 folder. If you start having problems that look like they're coming
from within a library, a good first step is to try deleting that folder (
rm -rf ~/.m2 in a shell).
Our guide on how to use Maven commands is here.
Spark and FreeMarker
Spark is a Java framework that lets you create a web server using Java. Unlike Python, which has
overwhelmingly popular libraries for this purpose like Flask and Django, there is no one popular web framework for Java. We've
decided to use Spark in CS32 because it requires a small amount of code to start and it's very easy to add new pages. At its simplest,
everywhere you see
Spark.get, we are creating a new page that the user can go to. Every time a user visits your page,
for example by typing
localhost:4567/boggle in a browser, the handler that you passed into the
Spark.get call will be
invoked. Think of it like someone typing a command into your REPL, only Spark handles the mechanics for you.
FreeMarker is a "templating engine" you'll interact with more and more as the course goes on. It works with Spark to help translate between Java and HTML, the language of the web. We'll explain how to use it more in a lab, but for now you can think of it as a way to fill in parts of a webpage using Java objects.
./run and cs32-test
If you took CS15, you'll remember using the
java command to run your code. In CS32, we've written the
script so you don't have to worry about some messy side-effects of Maven. In short, the run script finds where Maven installed the
dependencies your project requires and finds your Main.java file. It constructs the
.mvn-classpath file so your
compiled code knows where to look for its dependencies and tells the jar compiled by
mvn package which file to run first.
./run complains that it can't find files, your best bet is to run
rm .mvn-classpath .classpath from a shell.
cs32-test is another custom script we've written for your system tests. We've written an extensive guide on why it's necessary and how
to use it here.