Fix #2184: Hyper Bootstrap! Integrate the backend as a git submodule

The backend lives in the scalac fork at
https://github.com/lampepfl/scala/tree/sharing-backend. Before this
commit, the scala-compiler built from this fork was a dependency of
Scala just to get this backend. This made it much more cumbersome to
test changes to the backend and also forced us to depend on Scala 2.11.5
since that is the version of scalac that the forked backend is based on.

This commit changes this by adding a git submodule in the
`scala-backend` directory that points to the scalac fork. We do not
compile the whole submodule, instead we add the subset of files we need
to the dotty-compiler project in the sbt build. See backend.md for more
information (online at
http://dotty.epfl.ch/docs/contributing/backend.html) once this commit is
merged.

The most important thing to note is that whenever you clone dotty you
should do `git clone --recursive` to also clone the submodule. If you
already have a cloned dotty you'll need to do:

git submodule update --init

You will need to repeat this command anytime you update dotty and the
backend has been updated, otherwise the content of `scala-backend` will
be stale.

4 files changed, 70 insertions, 17 deletions

diff --git a/docs/docs/contributing/backend.md b/docs/docs/contributing/backend.md
new file mode 100644
index 000000000..e7d98bb7f
--- /dev/null
+++ b/docs/docs/contributing/backend.md
@@ -0,0 +1,65 @@
+---
+layout: doc-page
+title: Working with the backend
+---
+
+The compiler backend is based on a fork of the Scala 2.11 `GenBCode` backend and
+lives at https://github.com/lampepfl/scala/tree/sharing-backend. The dotty
+source tree contains a git submodule in the directory
+[scala-backend](https://github.com/lampepfl/dotty/tree/master/scala-backend)
+that points to this fork. We do not compile every file in this submodule,
+instead we add the subset of files we need to the dotty-compiler project in the
+sbt build.
+
+The most important thing to know when working with git submodules is that
+their content is not automatically updated when you do `git checkout` or `git
+pull`, instead everytime you switch branch, you need to do:
+
+``` shell
+git submodule update --init
+```
+
+## Environment setup
+
+1. Set the following git configuration options to make working with submodules
+easier, see the [Git Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+for more information:
+``` shell
+git config --global diff.submodule log
+git config --global status.submodulesummary 1
+git config --global push.recurseSubmodules check
+```
+
+2. Fork https://github.com/lampepfl/scala (in the following commands,
+   `dotty-staging/scala` is used as a placeholder for your
+   own fork).
+3. ```shell
+   cd scala-backend
+   git remote add scala-staging git@github.com:dotty-staging/scala.git
+   cd ..
+   ```
+
+## Workflow when changing to the backend
+
+```shell
+cd scala-backend
+git checkout -b my-feature-branch
+# Make some changes ...
+
+git push -u scala-backend
+# Open a PR against https://github.com/lampepfl/scala/tree/sharing-backend
+cd ..
+```
+
+Once your PR has been merged into the backend, you'll need to make another PR
+against dotty itself to update the backend, the following commands should be run
+in the root dotty repository, not in the submodule:
+
+``` shell
+# The --remote option will update the submodule to the latest commit in the
+# https://github.com/lampepfl/dotty/tree/master/scala-backend branch
+git submodule update --init --remote
+
+git commit -am "Update backend to include ..."
+# Then push and make a PR against dotty as usual
+```
diff --git a/docs/docs/contributing/eclipse.md b/docs/docs/contributing/eclipse.md
index a7deab804..fa59a5dc6 100644
--- a/docs/docs/contributing/eclipse.md
+++ b/docs/docs/contributing/eclipse.md
@@ -5,31 +5,19 @@ title: Building Dotty with Eclipse
 
 Build setup
 -----------
-You may need to redo these steps when the build changes.
 
 1. Run `sbt eclipse`
-2. In dotty, go to `Properties > java build path > Libraries`.
-   Remove the Scala Compiler container (currently 2.11.4) and add as an
-   external jar the latest compiler version in the Ivy cache. This is
-   currently:
 
-   ```
-   .ivy2/cache/me.d-d/scala-compiler/jars/scala-compiler-2.11.5-20160322-171045-e19b30b3cd.jar
-   ```
-
-   But that might change in the future. Or, copy the latest scala compiler from
-   the cache to a stable name and use that as external jar.
-
-3. It is recommended to change the default output folder (in `Properties > java
+2. It is recommended to change the default output folder (in `Properties > java
    build path > Source`) to `dotty/classes` instead of `dotty/bin` because
    `dotty/bin` is reserved for shell scripts.
 
 If you have `CLASSPATH` defined:
 
-4. Update your classpath to contain any new required external libraries to run
+3. Update your classpath to contain any new required external libraries to run
    `./bin/dotc`, `./bin/dotr` outside of Eclipse.
 
-5. Open the `Run Configurations` tab, and edit the `tests` configuration so
+4. Open the `Run Configurations` tab, and edit the `tests` configuration so
    that it contains a `CLASSPATH` variable which reflects the current
    `CLASSPATH`.
 
diff --git a/docs/docs/contributing/getting-started.md b/docs/docs/contributing/getting-started.md
index 26862e790..6f14c8299 100644
--- a/docs/docs/contributing/getting-started.md
+++ b/docs/docs/contributing/getting-started.md
@@ -24,7 +24,7 @@ Compiling and Running
 Start by cloning the repository:
 
 ```bash
-$ git clone https://github.com/lampepfl/dotty.git
+$ git clone --recursive https://github.com/lampepfl/dotty.git
 $ cd dotty
 ```
 
diff --git a/docs/docs/contributing/workflow.md b/docs/docs/contributing/workflow.md
index b277cc243..a8001366a 100644
--- a/docs/docs/contributing/workflow.md
+++ b/docs/docs/contributing/workflow.md
@@ -9,7 +9,7 @@ This document details common workflow patterns when working with Dotty.
 
 ```bash
 # Start by cloning the repository:
-git clone https://github.com/lampepfl/dotty.git
+git clone --recursive https://github.com/lampepfl/dotty.git
 cd dotty
 # Clone dotty-compatible stdlib. Needed for running the test suite.
 git clone -b dotty-library https://github.com/DarkDimius/scala.git scala-scala