IntelliJ at VTC

This document describes how to set up IntelliJ on your own system for use with Scala development. The software components mentioned below may already set up on the lab machines, but even in the lab you will need to go through some additional steps starting with installing the Scala plugin (the steps before that point can be skipped when setting up a lab machine).

These directions are for IntelliJ 13.1 and Scala 2.11 with Java 8. The instructions for similar versions should be similar.

Install the Java Development Kit. Use the latest Java 8; my preconfigured projects expect it (although reconfiguring them to use Java 7 shouldn't be too difficult in most cases).

I suggest that you use the 64 bit Java Development Key (JDK) if you are on a 64 bit system. Installing the JDK will also install a Java Runtime Environment (JRE). You don't need to explicitly install both.

Although not required I find it useful to set the JAVA_HOME environment variable. For example, it should be set to to C:\Program Files\Java\jdk1.8.0_11, or something similar, to specify the location where your JDK is installed. You can also add %JAVA_HOME%\bin to your PATH environment variable. This allows you to run the Java development tools from a console prompt. TODO: Describe how to set environment variables.

If you do add the JDK tools to your PATH you can test your Java installation by opening a console window and typing the following (the ">" below is intended to indicate the command prompt; it is not part of the command).
```
        > java -version
        > javac -version
      
```
Both commands should return a string that shows the version number. Be sure the version number agrees with your expectation.
Install the latest Scala. At the time of this writing the latest official release is 2.11.1 but you can install any 2.11.x version. Be aware that Scala versions are binary incompatible with each other. For example, if you compile part of your program with 2.10 and part with 2.11, the two parts will not be able to communicate. However, within a version the minor releases (2.11.1, 2.11.2, etc) are compatible. My projects expect 2.11.x for any value of "x."

You do need to set the SCALA_HOME environment variable to point to the location of your Scala installation. My projects depend on this. On Windows that would be C:\Program Files (x86)\scala. You do not need to add Scala's bin folder to your path. That is done automatically by the installer.

To test your Scala installation, open a fresh console window (so that PATH changes are visible) and run the command
```
        > scala
      
```
You should see a banner and then a prompt such as "scala>." You are now in the REPL, a simple environment that allows you to experiment with Scala code. Notice the Scala version mentioned in the banner and be sure it agrees with your expectations. Type ":quit" to exit the REPL environment.
Install IntelliJ Community Edition. The Community Edition is free and supports the development of applications in Java, Scala, and two other JVM languages (Groovy and Clojure). It does not support all the web application development features of the commerical "Ultimate Edition" but it has plenty enough functionality for our purposes.

If you are configuring a lab machine start here. Everything above this point should have already been done in the labs.

Start IntelliJ. In the Quick Start menu click "Configure" and then "Plugins." Click on the "Browse repositories..." button at the bottom of the dialog box and scroll to the Scala plugin. Click on the "Install plugin" button to download the plugin. After the download completes, restart IntelliJ so the new plugin is active.
In the Quick Start menu select Configure -> Project Defaults -> Project Structure. Select "SDKs" in the "Platform Settings" section on the left. Click on the plus sign at the top of the dialog box (it's green). Select "JDK" and browse to the top level folder of your JDK installation (for example, C:\Program Files\Java\jdk1.8.0_11). This informs IntelliJ about the location of your Java tools and libraries.
In the same "Project Structure" dialog box, click on "Global Libraries" in the "Platform Settings" section. Click on the plus sign at the top of the dialog box to create an unnamed library. Change the name to "scala-compiler-2.11." It is desirable to include the Scala version number since different versions are binary incompatible with each other and thus shouldn't be confused. Yet you should *not* include the revision number ("scala-compiler-2.11.1") since different revision levels are compatible.

At the top of the right hand pane click the green plus sign to add components to the library. Browse to the location of the Scala libraries (probably C:\Program Files (x86)\scala\lib). Select the following jar files:
```
        scala-compiler.jar
        scala-library.jar
        scala-reflect.jar
      
```

Repeat the above step to create "scala-library-2.11." From the same location select the following jar files:

        akka-actor_2.11-2.3.4.jar
        config-1.2.1jar
        jline-2.12.jar
        scala-actors-2.11.0.jar
        scala-actors-migration_2.11-1.1.0.jar
        scala-library.jar
        scala-parser-combinators_2.11-1.0.2.jar
        scala-reflect.jar
        scala-xml_2.11-1.0.2.jar

Repeat the above step to create "scalatest_2.11-2.1.5" containing only the scalatest_2.11-2.1.5.jar. You can download ScalaTest from its web site. Be sure to match the version numbers exactly.
Some of my projects require that the SCALATEST_JAR operating system environment variable be set containing the full path to the ScalaTest jar file you previously downloaded. The exactly location where the jar file resides on your system is up to you. Don't forget to log out and then log back in so that changes to the environment take full effect.

To verify that everything is working, clone the WriterDaemon project from GitHub. Open the project in IntelliJ and try building it using the Build -> Make Project main menu item. Try building the executable jar file using the Build -> Build Artifacts main menu item. Open the Ant Build tab (on the right) and right click on the scaladoc target to build the scaladoc for the project. Finally create a ScalaTest run configuration that executes all tests in package edu.vtc.writerdaemon and execute that configuration to verify all tests pass.

If everything worked, you are now all set!

Adding a Module

This describes the steps required to add a module to an exisiting IntelliJ project. You might want to maintain a project for a particular class and add a module for each assignment in that class. Be aware that I also use Git in many of my classes so you might want to create a branch before modifying sample projects I provide.

In the project view on the left side of the main window, click on the name of the project and then select File -> New Module from the main menu. Click on "Scala" in the left pane, "Non-SBT" in the right pane, and then click "Next."
Enter a suitable name for the module such as "Hw01." Verify that the Content Root and Module File Location settings are appropriate. Normally each module is put in a subfolder of the project folder.
Under "Scala Settings" select "Existent Library." Verify that the scala-compiler-2.11 and scala-library-2.11 libraries you previously created are selected. Under "More Settings" be sure "Enable type-aware highlighting" is selected. Click on "Finish" to create the module.
At this point you might want to fine tune the settings of your module a little. Select File -> Project Structure. Then in the left pane under "Project Settings" select "Modules." In the middle pane expand the tree beneath your new module (Hw01 in this example) and click on the Scala facet. Suggested adjustments include: Change the Language level to "Scala 2.11," Enable "Deprecation warnings" and "Unchecked warnings." You might also try "Explain type errors" if you are curious.

Although you now have a new module defined, you might also want to include some code in your module.

In the project view, open the module and right click on the src folder. Select New -> Package. Enter a name such as edu.vtc.cis3030.hw01. Note that package names are traditionally all lower case.
Right click on the name of the package and select New -> Scala Class. Use the name Main for the main object and be sure to change the type to Scala Object (you don't really want a class). Now you can write your main method and whatever else you need. When you are ready to run your program you need to create a run configuration.
In the toolbar you'll find a place where you can select the current run configuration (the list box toward the right hand side of the toolbar). Click on it to pull down the list and select Edit Configurations.
Click on the green "+" in the upper left corner and select "Application". Change the name to "Hw01" (or similar). Be sure the "Classpath to module" is set to the correct module (Hw01 in this case). Set the main class to edu.vtc.cis3030.hw01.Main. You can also browse for the main class, letting IntelliJ find suitable classes (only one right now) for you. Clikc "OK."

You can now compile and run your program by pressing the green arrow next to the run configuration selection box. You can debug your program by pressing the green beetle (right next to the green arrow).