CSCI 136

CSCI 136 :: Spring 2021

Data Structures & Advanced Programming

Document Overview

"Structure5" is the name of the software library that includes the code associated with the course textbook. Since we will be using data structures from the textbook throughout the semester, it is important that we are all able to compile programs that rely on structure5 code. This document includes backround on the various structure5 resources, as well as instructions that let you compile structure5-based programs on your personal computing environment.

Structure 5 Background

There are several download links that refer to various parts of the structure5 software. You should be familiar with them all; they are all useful resources. Here we describe the ways that we hope you will use them.

The textbook describes the data structures and their implementations in the structure5 software package. The textbook is an incredibly useful resource for understanding designs and tradeoffs, but the textbook is not necessary for running programs.
The structure5 class documentation is presented in the standard "Javadoc web" format; it consists of a series of .html pages hosted on a webserver. This documentation is useful when figuring out how to write code that uses the structure5 software, but it is not necessary when running your code.
The structure5 source code is downloadable as a "gzipped tar archive" (a file with the .tgz extension can be expanded by first "unzipping it" to decompress it and then "untarring it" to reconstruct the constituent files from the TAR archive format). The source code is useful when we want to dive into specific details about the class implementations. Having access to the source code is also useful if we want to experiment by making changes/additions to the default structure5 class implementations. In theory, we can compile our lab programs against any source code, including structure5's source code, but that is not the easiest way to set up our programming environments for this course.
Finally, bailey.jar is a single file that contains all of the structure5 classes in a format that the Java compiler can use to build our lab programs when we import structure5 classes into our Java files. (Duane Bailey is the author of the textbook and the structure5 source code, hence the "bailey" part of the name. The .jar extension is commonly used for Java ARchives.) The rest of the instructions in this document will explain how to download bailey.jar and set up our computing environments so that the Java compiler (i.e., javac) knows where to find it.

Setup Instructions

The first step is to download bailey.jar and move that file to a location on your computer that you would like it to "live" for the duration of the semester. (Note: For these instructions, I will use my setup as an example, so whenever you see a path to bailey.jar, you should replace that path with the location of bailey.jar on your machine.) I have a directory called cs136/ inside my home directory where I placed the file. From the terminal, I can navigate to that directory using cd and then type pwd; after doing so, I am told that the location of this directory is /Users/bill/cs136/. Do this yourself and take note of your directory's path; we will use it later.

The rest of the steps are logically similar for macOS, Linux, and Windows, but the particulars of the "preferred approach" vary slightly. Therefore we have created two sets of instructions below, one for macOS/Linux users and one for Windows users. Follow the instructions that apply to your operating system.

At a high level, the steps below will guide you through the process of setting up the environment variable that Java uses to determine the location of imported libraries. Since the structure5 libraries are not part of the default Java installation, we need to add the location of the structure5 libraries to this environment variable so that javac knows where to find it.

Note: All instructions assume you have completed your environment setup according to the instructions in Lab 0.

MacOS and Linux users

When we lauch a new "shell" (aka terminal) in a Unix-like operating system, a lot of things happen in the background. Many of those are explored in detail in the course CSCI 432: Operating Systems, but the "initialization" steps are important to us now. A particular instance of the terminal has a its own "environment" that includes a set of so-called "environment variables". The CLASSPATH environment variable is where javac looks to find imported classes. These instructions explain how to set the CLASSPATH environment variable so that it includes a reference to structure5.

First, we will determine which "shell" we are using. The Unix command echo can be used to display a value to the terminal. The dollar sign $ is used to tell the shell that you don't want it to interpret a string as literal text, but instead to interpret that string as a variable and to evaluate that variable. Type the command echo "$SHELL" in your terminal to print the value of the "SHELL" variable to your terminal. When I do so on macOS, I see:
```
% echo "$SHELL"
      /bin/zsh
      
```
If you are on Linux (or a slightly older version of macOS), you will likely see:
```
% echo "$SHELL"
/bin/bash
```
Take note of which shell you are using: "zsh" or "bash".
When a new shell starts, it reads from a set of pre-determined configuration files as part of its initialization process. Depending on your shell, the names of those configuration files differ. What we want to do in this step is add the line:
```
export CLASSPATH=".:/Users/bill/cs136/bailey.jar:$CLASSPATH"
```
to your shell's default cofiguration file (except you will replace /Users/bill/cs136/bailey.jar with the path to bailey.jar that you noted when you downloaded the file).

If your terminal uses "zsh", you can update your initialization files by typing the following command:
```
echo "export CLASSPATH=\".:/Users/bill/cs136/bailey.jar:\$CLASSPATH\"" >> ~/.zshrc
```
If your terminal uses "bash", you can update your initialization files by typing the following command:
```
echo "export CLASSPATH=\".:/Users/bill/cs136/bailey.jar:\$CLASSPATH\"" >> ~/.bash_profile
```
The "echo "..."" portion of the command will print everything in the ""..."" part to the terminal. The ">> ~/some/file" part of the command tells the shell to take what was printed by echo and append it to the file specified after the >>. This command will preserve the old contents of the configuration file, but add your classpath definition to the end.
Now that you've updated your shell's initialization scripts, we want to check that we did so correctly. First, we can use the cat utility to inspect the contents of our configuration files. Execute either:
```
% cat ~/.zshrc
```
or
```
% cat ~/.bash_profile
```
Do the contents match what you'd expect? If not, you can open the file in a text editor and edit the file by hand.

If the output finally looks OK, we will next check whether the shell initialization process correctly interprets our command. Open a new terminal window and type:
```
% echo "$CLASSPATH"
```
Does the output match what you'd expect? If not, send us or the TAs an email or Slack message, and we can debug.
Now we can try compiling a simple program that uses a structure5 class. We have included the contents a sample program below that you can save into a file called Sample.java and compile with % javac Sample.java. If it successfully compiles, you are done!

Windows Users

When we open a new Git-Bash window (aka terminal) in Windows, the operating system initializes a set of variables, called environment variables that hold information that various commands need to function properly. Some of these, like the $Path variable that you might have modified when you installed Java, are system-wide, while others are user-specific. To allow your program to access the compiled Java classes contained in bailey.jar, you will need to create (or modify) one such user-specific environment variable, the CLASSPATH variable.

To begin, let's assume that you have created a cs136 directory somewhere in your file system. First be sure to move the bailey.jar file to that directory. For example, if your bailey.jar file is in your Downloads folder and your cs136 directory is in your Documents folder, you can open a Git-Bash window and type


          >mv Downloads/bailey.jar Documents/cs136

To get the full name of that directory, in the same Git-Bash window, move to the directory containing bailey.jar then type the pwd command. For example


          >cd Documents/cs136
          >pwd
          /c/Users/Bill/Documents/cs136

Now, following the approach taken to install Java, type env into the Windows 10 search box and select Set the system environment variables. Select the Advanced tab and press the Environment Variables... button.

In the dialog box that appears, there should be two lists of variables: user variables and system variables. You will need to add a new user variable (the upper list) called CLASSPATH. Press the New button below the user variables list and a dialog box appears. Enter CLASSPATH for the variable name and enter %CD%;C:\Users\Bill\Documents\cs136\bailey.jar for the variable value. Then select ok in each dialog box to close them all.

Changes to environment variables only take effect in Git-Bash windows that are opened after the variable is created/edited. So, close any open Git-Bash windows and open a new one. Then type echo $CLASSPATH. The result should be


          >echo $CLASSPATH
          %CD%;C:\Users\Bill\Documents\cs136\bailey.jar

If this is the case, you should now be able to test whether Java can successfully access the structure5 classes by following the instructions below.

Sample Testing Program

You can copy and paste this program into a file called Sample.java. If you can successfully compile that program, then you are done!


        import structure5.Vector;

        public class Sample {
    	     public static void main(String[] args) {
    		       Vector<String> v = new Vector<String>();
    		       System.out.println("Success!");
    	     }
       }