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.

Shell

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

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

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 ./run 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. If ./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.