README instructions for installing with Scala FIRRTL

1 files changed, 149 insertions, 23 deletions

diff --git a/README.md b/README.md
index d473cd62..cd6762da 100644
--- a/README.md
+++ b/README.md
@@ -7,13 +7,13 @@ It is currently in ALPHA VERSION, so many Chisel features may change in the comi
 ## Chisel2 Migration
 For those moving from Chisel2, there were some backwards incompatible changes
 and your RTL needs to be modified to work with Chisel3. The required
-modifications are: 
+modifications are:
 
- - Wire declaration style:  
+ - Wire declaration style:
    ```
    val wire = Bits(width = 15)
-   ```  
-   becomes (in Chisel3):  
+   ```
+   becomes (in Chisel3):
    ```
    val wire = Wire(Bits(width = 15))
    ```
@@ -30,12 +30,11 @@ modifications are:
    val mem = SeqMem(1024, UInt(width=8))
    val dout = mem.read(addr, enable)
    ```
+
    Notice the address register is now internal to the SeqMem(), but the data
-   will still return on the subsequent cycle. 
-  
-## Getting Started
+   will still return on the subsequent cycle.
 
-### Overview
+## Overview
 Chisel3 is much more modular than Chisel2, and the compilation pipeline looks
 like:
  - Chisel3 (Scala) to FIRRTL (this is your "Chisel RTL").
@@ -44,16 +43,143 @@ like:
  - Verilog to C++ for simulation and testing using
  [Verilator](http://www.veripool.org/wiki/verilator).
 
-### Installation
-To compile down to Verilog for either simulation or synthesis, you will need to 
-download and install [FIRRTL](https://github.com/ucb-bar/firrtl). Currently,
-FIRRTL is written in Stanza, which means it only runs on Linux or OS X. A
-future Scala rewrite is planned which should also allow Windows compatibility.
+## Installation
+This will walk you through installing Chisel and its dependencies:
+- [sbt](http://www.scala-sbt.org/), which is the preferred Scala build system
+  and what Chisel uses.
+- [FIRRTL](https://github.com/ucb-bar/firrtl), which compile Chisel's IR down
+  to Verilog. A alpha version of FIRRTL written in Scala is available.
+  - FIRRTL is currently a separate repository but may eventually be made
+    available as a standalone program through system package managers and/or
+    included in the Chisel source tree.
+  - FIRRTL has known issues compiling under JDK 8, which manifests as an
+    infinite recursion / stack overflow exception. Instructions for selecting
+    JDK 7 are included.
+- [Verilator](http://www.veripool.org/wiki/verilator), which compiles Verilog
+  down to C++ for simulation. The included unit testing infrastructure uses
+  this.
+
+### (Ubuntu-like) Linux
+
+1. [Install sbt](http://www.scala-sbt.org/release/docs/Installing-sbt-on-Linux.html),
+  which isn't available by default in the system package manager:
+
+  ```
+  echo "deb https://dl.bintray.com/sbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
+  sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 642AC823
+  sudo apt-get update
+  sudo apt-get install sbt
+  ```
+1. Install FIRRTL.
+  1. Clone the FIRRTL repository:
+
+    ```
+    git clone git@github.com:ucb-bar/firrtl.git
+    ```
+  1. Build Scala-FIRRTL. In the cloned FIRRTL repository:
+
+    ```
+    make build-scala
+    ```
+    * This compiles FIRRTL into a JAR and creates a wrapper script `firrtl` to
+      make the JAR executable. The generated files are in `firrtl/utils/bin`.
+    * If this fails with an infinite recursion / stack overflow exception, this
+      is a known bug with JDK 8. You can either increase the stack size by
+      invoking:
+
+      ```
+      JAVA_OPTS=-Xss256m make build-scala
+      ```
+    * Or, revert to JDK 7:
+      1. Install JDK 7 (if not installed already):
+
+        ```
+        sudo apt-get install openjdk-7-jdk
+        ```
+      2. Select JDK 7 as the default JDK:
+
+        ```
+        sudo update-alternatives --config java
+        ```
+  1. Add the FIRRTL executable to your PATH. One way is to add this line to your
+    `.bashrc`:
+
+    ```
+    export PATH=$PATH:<path-to-your-firrtl-repository>/utils/bin
+    ```
+1. Install Verilator. As of February 2016, the version of Verilator included by
+  in Ubuntu's default package repositories are too out of date, so it must be
+  compiled from source.
+  1. Install prerequisites (if not installed already):
+
+    ```
+    sudo apt-get install git make autoconf g++ flex bison
+    ```
+  1. Clone the Verilator repository:
+
+    ```
+    git clone http://git.veripool.org/git/verilator
+    ```
+  1. In the Verilator repository directory, check out a known good version:
+
+    ```
+    git pull
+    git checkout verilator_3_880
+    ```
+  1. In the Verilator repository directory, build and install:
+
+    ```
+    unset VERILATOR_ROOT # For bash, unsetenv for csh
+    autoconf # Create ./configure script
+    ./configure
+    make
+    sudo make install
+    ```
+
+### Windows
+
+*TODO: write me. If you __really__ want to see this happen, let us know by filing a bug report!*
+
+### Mac OS X
+
+1. Install sbt:
+
+  ```
+  brew cask install sbt
+  ```
+1. Install FIRRTL:
+  1. Clone the FIRRTL repository:
+
+    ```
+    git clone git@github.com:ucb-bar/firrtl.git
+    ```
+  1. Build Scala-FIRRTL. In the cloned FIRRTL repository:
+
+    ```
+    make build-scala
+    ```
+    * This compiles FIRRTL into a JAR and creates a wrapper script `firrtl` to
+      make the JAR executable. The generated files are in `firrtl/utils/bin`.
+    * If this fails with an infinite recursion / stack overflow exception, this
+      is a known bug with JDK 8. You can either increase the stack size by
+      invoking
+
+      ```
+      JAVA_OPTS=-Xss256m make build-scala`
+      ```
+    * Or, revert to JDK 7:
+
+      ```
+      brew install caskroom/versions/java7
+      ```
+  1. Add the FIRRTL executable to your PATH. *TODO: someone with a Mac needs to write this part*
+1. Install Verilator:
+
+  ```
+  brew install verilator
+  ```
 
-To compile Verilog down to C++ for simulation (like the included unit testing
-infrastructure uses), you will need to have
-[Verilator](http://www.veripool.org/wiki/verilator) installed and in your
-PATH. Verilator is available via the package manager for some operating systems.
+## Getting Started
 
 ### Data Types Overview
 These are the base data types for defining circuit wires (abstract types which
@@ -69,7 +195,7 @@ This section describes how to get started using Chisel to create a new RTL
 design from scratch.
 
 ### Project Setup
-*TODO: recommended sbt style, project structure* 
+*TODO: recommended sbt style, project structure*
 
 ### RTL
 *TODO: toy example*
@@ -82,7 +208,7 @@ pretty bare-bones unittest which also somewhat verifies the testing system
 itself.
 
 Unit tests are written with the ScalaTest unit testing framework, optionally
-with ScalaCheck generators to sweep the parameter space where desired. 
+with ScalaCheck generators to sweep the parameter space where desired.
 
 `BasicTester`-based tests run a single circuit in simulation until either the
 test finishes or times out after a set amount of cycles. After compilation,
@@ -100,7 +226,7 @@ a class that extends either `ChiselFlatSpec` (BDD-style testing) or
 `ChiselPropSpec` (ScalaCheck generators). In the test content, use
 ```
 assert(execute{ new MyTestModule })
-``` 
+```
 where `MyTestModule` is your top-level test circuit that extends
 `BasicTester`.
 
@@ -125,11 +251,11 @@ to compile the Chisel library. If the compilation succeeded, you can then run
 the included unit tests by invoking:
 ```
 sbt test
-``` 
+```
 
 ### Running Projects Against Local Chisel
 To publish your version of Chisel to the local Ivy (sbt's dependency manager)
-repository, run:  
+repository, run:
 ```
 sbt publish-local
 ```
@@ -140,7 +266,7 @@ becomes `sbt ~publish-local`.
 
 [sbt's manual](http://www.scala-sbt.org/0.13/docs/Publishing.html#Publishing+Locally)
 recommends that you use a `SNAPSHOT` version suffix to ensure that the local
-repository is checked for updates. 
+repository is checked for updates.
 
 The compiled version gets placed in `~/.ivy2/local/`. You can nuke the relevant
 subfolder to un-publish your local copy of Chisel.