Better Building of FIRRTL From Source (#1563)

Using JVM system properties sbt.sourcemode and sbt.workspace, one can now
easily build chisel3 with firrtl from source

Example use:

Assuming firrtl is cloned into the chisel3 root directory:
$ sbt -Dsbt.sourcemode=true -Dsbt.workspace=$PWD

Alternatively, one can set these properties in .sbtopts which can then
be committed, enabling building from source by default

1 files changed, 26 insertions, 3 deletions

diff --git a/README.md b/README.md
index 9ff5f0e3..0dce401c 100644
--- a/README.md
+++ b/README.md
@@ -169,11 +169,11 @@ sbt test
 ### Running Projects Against Local Chisel
 
 To use the development version of Chisel (`master` branch), you will need to build from source and `publishLocal`.
-The repository version can be found in the build.sbt file.
+The repository version can be found in the [build.sbt](build.sbt) file.
 As of the time of writing it was:
 
 ```
-version := "3.2-SNAPSHOT"
+version := "3.4-SNAPSHOT"
 ```
 
 To publish your version of Chisel to the local Ivy (sbt's dependency manager) repository, run:
@@ -188,9 +188,32 @@ If you need to un-publish your local copy of Chisel, remove the directory genera
 In order to have your projects use this version of Chisel, you should update the `libraryDependencies` setting in your project's build.sbt file to:
 
 ```
-libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.2-SNAPSHOT"
+libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.4-SNAPSHOT"
+```
+
+### Building Chisel with FIRRTL in the same SBT Project
+
+While we recommend using the library dependency approach as described above, it is possible to build Chisel and FIRRTL in a single SBT project.
+
+**Caveats**
+* This only works for the "main" configuration; you cannot build the Chisel tests this way because `treadle` is only supported as a library dependency.
+* Do not `publishLocal` when building this way. The published artifact will be missing the FIRRTL dependency.
+
+This works by using [sbt-sriracha](http://eed3si9n.com/hot-source-dependencies-using-sbt-sriracha), an SBT plugin for toggling between source and library dependencies.
+It provides two JVM system properties that, when set, will tell SBT to include FIRRTL as a source project:
+* `sbt.sourcemode` - when set to true, SBT will look for FIRRTL in the workspace
+* `sbt.workspace` - sets the root directory of the workspace
+
+Example use:
+```bash
+# From root of this repo
+git clone git@github.com:freechipsproject/firrtl.git
+sbt -Dsbt.sourcemode=true -Dsbt.workspace=$PWD
 ```
 
+This is primarily useful for building projects that themselves want to include Chisel as a source dependency.
+As an example, see [Rocket Chip](https://github.com/chipsalliance/rocket-chip)
+
 ### Chisel3 Architecture Overview
 
 The Chisel3 compiler consists of these main parts: