Table Of Contents

Basic Expectations

I assume you are comfortable with the following tools. If not, you should familiarize yourself with them ASAP. The semester will go much smoother if you invest a small amount of time learning to effectively use the necessary tools.

• Basic BASH shell commands and either the Emacs or Atom editor.

• The standard git commands:

  $ git clone REPOSITORY
  $ git status
  $ git add
  $ git commit -m MESSAGE -a
  $ git push
  $ git pull

You can find more details on git in the CS434 tutorial for git, as well as the GitLab server we are using.

• Writing Markdown documents.
• Java, C, and x86 assembly code, at the level of CS 136 and 237.
• The Scala language.
• The IntelliJ IDEA programming environment.

You may have seen Scala in CS 334. That background is sufficient. If you did not, you probably used F#, which shares many basic features, although with a different syntax. You should go through the Scala materials from Week 1 to get yourself up to speed if you have not already.

IntelliJ IDEA has integrated support for editing, compiling, test, debugging code, as well as source control. All of these can significantly help increase your productivity in this project. We will spend part of the first lab setting up IntelliJ and configuring the project you will use for PA 1.

Working in IntelliJ IDEA

(Note: These steps are written for the lab Unix computers — there may be some minor differences in the names of menus if you are using your own computer.)

Setting Up You Environment

1. Launch IntelliJ by running the command idea in a terminal window.
2. Select “Do no import settings” and click OK.
3. Accept License Agreement.
4. Choose “Don’t send” for “Data Sharing” in the next dialog box.
5. Choose your UI Theme – I will be able to read over your code much better if you choose “Light”.
6. Leave “Create Desktop Entry” settings with their defaults and select “Next: Launcher Script”.
7. Leave “Create Launcher Script” settings with their defaults and select “Next: Default plugins”.
8. Leave “Tune IDEA to you tasks” settings with their defaults and select “Next: Featured plugins”.
9. In the “Download featured plugins” settings, click “Install” under Scala. Select “Start using IntelliJ IDEA” onces it completes installing Scala.

Opening and Configuring Your IC Project

Note: As you change settings, IntelliJ may ask you about adding additional .xml files to your git repository — cancel those requests, since we don’t want to add those files.

1. After completing the above steps, choose “Open” from the Welcome dialog box.
2. Select the project folder you would like to open (eg: PA1, PA2, etc.) and click “OK”.

3. Configure Scala:

   • Select “File | Settings”
   • “Preferences | Build, Execution, Deployment | Compiler”
     • Enable “Build project automatically”
   • “Preferences | Build, Execution, Deployment | Compiler | Scala Compiler | Scala Compile Server”:
     • Change “JVM options” to “-server -Xss256m”
     • Change “JVM maximum heap size, MB” to 2048.
   • “Preferences | Languages & Frameworks | Scala”:
     • Enable “Show type info on mouse hover …”
   • “Tools | External Tools”
     • Click “+”.
     • Name: “make gen”
     • Program: “make”
     • Arguments: “gen”
     • Click “OK”
   • “Keymap”
     • Double click on “make gen” inside “External Tools | External Tools”. If you can’t find that choice, you may want to close the preferences and re-open them.
     • Click Add Keyboard shortcut.
     • Assign “Ctrl-8” and Click “OK”.
     • Click “Remove” to delete old binding.
4. Set Up Scala
   • Click the Project tab on the left edge of the window
   • Select “PA1 | src | ic | Compiler”
   • If a yellow bar appears at the top of the editor pane showing the Compiler.scala source saying “Projet JDK is not defined”, click on “Setup JDK” and choose 1.8.
   • Another yellow bar should appear at the top of the editor pane showing the Compiler.scala source saying that Scala is not set up yet.
   • Click “Setup Scala SDK” in that bar.

   • Click “Create…” If the 2.12.6 option is available, use that.

     • Otherwise… Click “Download…”, then choose “2.12.6” from the popup menu and click “OK”.
       
     • Click “OK” once the download is complete. It may take a couple minutes to download.
5. Other Plugins
   • As you open different extensions – eg, .md or .flex – IntelliJ may ask if you wish to install plugins to support compiling those files by showing a similar yellow bar at the top of the editor with a message like “Plugins supporting *.flex files not found“. You should click”Ignore extension" in that yellow bar to prevent IntelliJ from downloading anything else. You should similarly not download other plugins it may ask you about.
   • The one exception is Markdown files. If you open the README.md file it will bring up a similar message about plugins. This time, click “Install plugins”. Check only the “Markdown support” plugin and then click OK. Then restart IntelliJ and open README.md again. You will now see the rendered Markdown next to the source.

Building

• First, run the external builder to generate your Lexer code by hitting “Ctrl-8” or choosing “Tools | External Tools | make gen.” You will see output like the following:

  make gen
  java -jar tools/JFlex.jar src/ic/lex/ic.flex
  Reading "src/ic/lex/ic.flex"
  Constructing NFA : 8 states in NFA
  Converting NFA to DFA : 
  ...
  5 states before minimization, 4 states in minimized DFA
  Old file "src/ic/lex/Lexer.java" saved as "src/ic/lex/Lexer.java~"
  Writing code to "src/ic/lex/Lexer.java"
  
  Process finished with exit code 0

• Then build the project by hitting “Ctrl-F9” or choosing “Build | Build Project”. Any errors encountered will appear in the Build panel at the bottom of the IntelliJ window. (I usually remap Build Project to Ctrl-9 in the Keymap Preferences to avoid annoying function key issues on other platforms. That also lets you build the whole project by hitting Ctrl-8 following by Ctrl-9.) In general, IntelliJ will rebuild the project in the background as you type, but you can always force it to do so with this command.

Running

1. From the Configurations pop-up menu, select “Edit Configurations…”
2. Click “+”
3. Selection “Application” from the popup menu
4. Change the Name to something descriptive
5. Main Class: ic.Compiler
6. Program arguments. Something like test/test1.ic
7. Click “OK”
8. The green play button will then run the program. It will likely crash with an exception until you complete more of the code.
9. You can create multiple configurations for different input files.

As you work on the compiler, I have found it easiest to write the code in IntelliJ and then switch to the command line to run the compiler, as outlined below. That avoids having to create Run Configurations for every input file. However, you can run things in IntelliJ in order to use the debugger, etc. More on that below…

Unit Tests

Unit tests are designed to test individual components in a system. They help tease out errors without running the whole project. Having good unit tests is essential for catching mistakes early and effectively debugging them. Your IntelliJ project is set up to run unit tests for your scanner. The unit test library we’re using is ScalaTest. You may find their user guide helpful when designing more sophisticated tests.

1. Look at “src | tests | LexicalTests” for example tests.
2. Create run configuration
   • Click the configuration pop-up menu again and select “Edit Configurations…”.
   • Click “+”
   • Select “ScalaTest”
     • Name: “Unit Tests”
     • Kind: “All in Package”
     • Test Package: “tests”
     • Click OK.
   • You can always change/edit your choices by using that pop-up menu.
3. Run by hitting Green play button to right of Configuration name in Toolbar.
   • The bottom of the screen will show the unit test output.
   • To see the results of all tests, click the gray check sign in the bottom left panel.
     
   • You should now see that two tests passed, and one did not. Clicking on the test names shows the output for that test (if any).
   • You should write unit tests early and often – they are one of the best defenses against bugs…

Debugging

1. Choose your application configuration from the pop up, and then click the little bug icon in the toolbar rather than the play button. This runs in the debugger. Nothing interesting will happen yet.
2. Now add a breakpoint by clicking in the editor margin next to the line number to make a red circle appear. Do this to the first line of the Compiler object’s main method. Run the debugger again
3. When you reach a breakpoint the debugging panel at the bottom of the window provides access to the standard debugging commands and variable inspection.
4. Play around with the debugger a bit this week – it will be handy when the code gets more sophisticated later.

Working in a Shell

You can do all of the above operations, except running the debugger, using command line utilities as well. The following summarizes how.

Some of these commands require you to set the SCALA_HOME environment variable to the location of the scala compiler and libraries. On the lab machines, this is /usr/share/scala/, so you should add the line

export SCALA_HOME=/usr/share/scala/

to the .local_bashrc file in your home directory. You’ll need to open a new terminal window for that addition to appear in the shell’s environment variables. If working on you own machine, you’ll need to set the variable to the directory containing lib/scala-library.jar.

Building

There are several commands to build the project.

• run “make” or “make icc” to build the scanner/parser and source files
• run “make gen” to run JFlex but nothing else.
• run “make dump” to see JavaCup output. [PA 2 and later…]
• run “make clean” to remove unnecessary files
• run “make all” to do all of the above

Running

The following runs the compiler on the file test/test1.ic.

scala -classpath "bin:tools/*" ic.Compiler test/test1.ic

Unit Testing

The following command runs all unit tests in the src/tests directory:

make tests

---