Sandbox Setup

This document describes how to set up the sandbox project that you will use for the first part of this course. You can use the sandbox for experimentation and as a kind of scratch pad for working through homework assignments. Later in the course we will use a full, graphical integrated development environment (IDE) suitable for working on large programs (namely, IntelliJ).

In the sandbox project we will use a build tool that is popular in the Scala community called sbt. This tool, like all build tools, coordinates the construction of your programs. Also, like other build tools, it is very flexible and can be used to build many kinds of artifacts. In fact, sbt is a professional quality tool that can be used for building very large applications. A graphical IDE is never necessary. The name "sandbox" is not meant to minimize the power and funtionality of sbt. Instead it is only a reminder that we will start this course by just tinkering with the language. You can use sbt later on to create other projects, including very complicated projects (actually, we will configure IntelliJ to use sbt behind the scenes).

The following steps assume you are using a Windows 10 machine, but they should largely work with, or be adaptable to, other systems (such as Linux).

Install a Java Development Kit. Depending on how you use your machine, you may already have a suitable JDK installed. For this course you must use a JDK that is at least version 8. I am using version 11.0.1 (the latest available version at the time of this writing). Download the JDK installer from Oracle and run it to install the JDK.
Set up the Java environment. You need to be sure the Java tools are available in a console prompt. You can check if they are by opening a console window and typing the commands:
```
        > java -version
        > javac -version
      
```
You should see a banner displayed by each command with information about which version of the JVM and the Java compiler you are using. If you see the wrong version (something different than the version you installed) you may have to uninstall an older JDK or perhaps manually delete java.exe from your Windows folder. You may get an error message about the command not being found. If that is so, proceed with the following steps:

In the Settings App, search for "environment." Select "edit the system environment variables." In the dialog box that appears, click on "Environment Variables." The system variables are in the lower pane. Click on "New..." and create an environment variable named JAVA_HOME with a value that is the path to your JDK installation (such as C:\Program Files\Java\jdk-11.0.1). Edit the Path environment variable to include a path component of %JAVA_HOME%\bin.

After completing the steps above you should be able to open a console window and run the commands above successfully. Note that you will need to use a new console window for the changes to take effect.
Install sbt. Download the appropriate sbt installer and execute it to install sbt. The installer adds sbt to the Path automatically so you don't need to manually adjust the environment as described in the previous step.
Create the Sandbox project. Create an empty folder in some suitable location. I suggest calling the folder sandbox, but you can name it whatever you like. This folder will hold the Sandbox project.

Next, create a text file named build.sbt in the folder you just created. That file should include the following contents:
```
ThisBuild / scalaVersion := "2.12.8"
ThisBuild / organization := "edu.vtc"

lazy val sandbox = (project in file("."))
  .settings(
    name := "Sandbox"
  )
      
```
We will talk about the meaning of build.sbt in more detail later. However, what you need to know now is that it describes your project. In this case we will be using Scala version 2.12.8, and the project is named "Sandbox." Notice that sbt allows you to use different Scala versions with different projects. It will download (and cache) the appropriate Scala version on demand. You do not need to install Scala manually.
Start sbt. Open a Windows console and change to the sandbox folder (the place where your build.sbt file exists. At first the build file should be the only file in that folder. Execute the command:
```
        > sbt
      
```
to start the sbt tool interactively. The first time you do this, sbt will complete its installation. This will entail copying some files and downloading various supporting packages. This may take some time. However, sbt will cache all the downloaded material. Future invocations of the tool will not take so long.

When sbt is finished starting you should see some informational messages related to the project and the "sbt server" followed by a prompt such as:
```
        sbt:Sandbox>
      
```
In this mode, sbt is running interactively. You can now type in various commands to build your program, test it, and run it. Of course at the moment we haven't created any source files, but sbt doesn't care about that right now.
Start the Scala REPL. Use the sbt "console" command as follows:
```
        sbt:Sandbox> console
      
```
to start Scala's Read-Evaluate-Print-Loop (REPL). Note that sbt will automatically download the appropriate Scala version. You should see something like:
```
        Welcome to Scala 2.12.8 (Java HotSpot(TM) 64-Bit Server VM, Java 11.0.1).
        Type in expressions for evaluation. Or try :help.

        scala>        
      
```
The version number of Scala should reflect what you specified in the build.sbt file. The version number for Java should reflect your installed JDK version.

The Scala REPL is not part of sbt. It is part of the Scala distribution. It allows you to enter arbitrary Scala expressions and have them evaluated. It prints the results of those evaluations, looping back after each to read the next expression. It thus Reads an expression, Evaluates it, Prints the result, and then Loops back to get another expression.

Try typing this expression into the REPL:
```
        scala> 1 + 2
      
```
You should see:
```
        res0: Int = 3
      
```
This says the result, named "res0" is an integer with the value of 3.

Don't underestimate the power of the REPL. You have access to all of Scala's many features and can execute code fragments of arbitrary complexity. Although you may not understand some of the following features yet, try this expression to get an idea of what can be accomplished:
```
        scala> (1 to 100) filter { 100 % _ == 0 }
      
```
The result is a vector containing all the factors of 100.
Exit the tools. The REPL and sbt are entirely separate tools and have different command languages. To exit the REPL use :quit. To exit sbt use exit.