Since there are no TA Hours scheduled before the term starts, feel free to ask us questions on our course piazza. In addition to boggle-specific questions, we’re also happy to answer any set-up questions about Linux or compiling Java code!
Welcome to CS32! This is an optional (but recommended) assignment for those who are unsure if they are prepared for CS32, want a quick refresher on their Java skills, or want to prove they are awesome. If you are well-prepared to take this course, you should be able to complete the majority of the requirements for this assignment in a few hours. A great Boggle implementation, particularly one with a complicated graphical user interface (GUI), would take considerably longer. But don't worry too much about that yet, we'll be building on this code base throughout the term in labs.
Don't know/remember how to play Boggle? Play a round or two on this website for a quick introduction.
In this assignment, your main task is implementing a single
examines the Board's state and returns
Set<String> containing all of the words that
can be found there according to Boggle rules. But besides
play(), we encourage you to read all of
the provided code. It contains a lot of comments and questions that you
should at least be able to understand, even if you can't always
answer the questions perfectly.
There are a few things about this project that will be new to you. Don't panic! First, we are using Maven to manage library dependencies and to build the project. You can certainly use an IDE like Eclipse, but all of your submissions must also compile using maven so that we can automate testing. You'll also need to use Maven to run some tools against your code. These tools will analyze your code looking for common mistakes, and code that violates our style guide. You can avoid losing easy points by listening to what these tools tell you. Run these tools early and often, so that simple mistakes don't pile up.
Maven makes it easy to add needed libraries to your projects. In general, CS32 encourages the use of standard libraries. We've included several that we like in this build (JUnit, Guava, Gson, JOptSimple). You'll be getting to know all of them better over the course of the semester.
Another surprise is Spark.
Spark is a small library that makes it easy to run a web server
inside your program. This way, your program can communicate with
the user by producing HTML pages (like Boggle boards) and take input
Before we start you must configure your environment to use Maven 3 and Java 11, which are installed by default on department machines.
Confirm that you are using the proper versions by running
mvn -version. The first line should mention Maven
3.X.X Next, run
java -version. The first line should
mention version 11.0.XX. Version 11.* of Java is commonly referred to
as "Java 11." If these versions aren't right, get help now.
If you want to develop on your own computer rather than by remotely using a department machine, you'll need to install the JDK (version 11), Maven (version 3), and perhaps Eclipse. But there are quite a few IDEs out there so feel free to work on whichever one works the best for you (e.g. IntelliJ) or none at all (e.g. emacs or vim). Check out our Getting Set Up lab for detailed information about working on your personal computer.
If you have questions, feel free to ask us on piazza!
For this project (and only this one) we're providing most of the skeleton code.
First, we recommend creating a work directory for cs032 work. For
mkdir ~/cs0320 to make a cs032 directory in
your home directory. Then
cd ~/cs0320. Now that you're
in your work directory, you can download the boggle zip file here.
If you are trying boggle from home, you can still download the boggle file.
Once you've downloaded and unzipped the file, dig around for the Java files and start exploring. You should rename the student directories to your own username. On a department machine, run:
mv boggle/src/main/java/edu/brown/cs/student boggle/src/main/java/edu/brown/cs/$USER mv boggle/src/test/java/edu/brown/cs/student boggle/src/test/java/edu/brown/cs/$USER(on a home machine, substitute your login for $USER manually).
Then make the associated changes to package names as well. Here's a handy shell command (for Mac) that looks through all files contained in your current directory and replaces any instances of "student" with your username:
grep -rl 'student' . | LC_CTYPE=C xargs sed -i '' "s/student/your-login/g"Use this version of the command for Linux (department machines):
grep -rl 'student' . | xargs sed -i "s/student/`whoami`/g"Make sure you only run this command once you're inside your boggle directory, otherwise you'll end up searching through your entire home directory. NOTE: This command only works for Linux and Mac (OSX).
Alternatively, you can use the following command to find all the files containing "student", and then edit them by hand.
find boggle -name "*.java" | xargs grep student
Keep the basic directory structure, because maven is picky about that.
We supplied a
mvn packagefrom inside the boggle directory 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.
In the stencil for this project, we have provided a sample executable
./run). For all of your projects in CS32, we will expect you
to turn in a similar executable. Even if you use an IDE, you must ensure
that your command-line script works, as it allows the staff to run and
test your code. If you take a look at that file, you will notice
it's pretty straight-forward, with each line explained. Use the provided shell
script run to invoke your build. For example,
./run --generateshould output a random Boggle board. The first time you use
./runit will be slow. It is figuring out which libraries need to be available for your code. It'll be faster next time.
./run with no extra arguments.
You should get a message printed that tells provides a url like
http://127.0.0.1:4567/ or http://localhost:4567/
(which are equivalent). Visit play page of the printed
URL with your a web browser (i.e. http://localhost:4567/play).
You can enter a list of words there,
but they won't be scored properly until you implement
Here's what we've left for you to do:
Board.play()to return all legal words for the board. Words must appear in the dictionary created at the start of the Board class, and can be formed by connecting letters vertically, horizontally, or diagonally. You may not "backtrack" or "circle around" to use the same position twice. Once you're done, a command like
./run --solve=msap,tett,yate,zvoeshould print all legal words for the board made up of the given four rows of letters.
- Test your program. In most projects, we'll ask you to write
tests that show your individual classes work well (those
are unit tests) and that your entire program works properly
(those are system tests. We've provided some unit tests
here, but we'll cover both in more depth in the first lab. For
mvn testto see how unit tests work. They will all succeed, but that's only because we haven't implemented a good set of tests yet. Add some tests. Two good ones are a test to see if a word is properly found in a board, and test to ensure that a non-existent word is not found in a board.
Checking for style errors
All projects have a style component based on Maven Project reports. Here 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").
With every project, we expect you to include a README file describing:
- Known bugs.
- Design details specific to your code.
- Your testing plan — what tests did you write (unit and system), and why?.
However, you won't need to hand in boggle since it won't be graded. Good luck!