Add developer instructions to documentation

Author: Herman Venter

README.md

@@ -10,11 +10,13 @@ The initial focus will be on taint analyis.
 ## Requirements
 __________ requires or works with
 * Mac OS X or Linux
-* ...
+* ... -->
 
-## Building __________
-...
+## Building
+See the [developer guide](https://github.com/facebookexperimental/MIRAI/blob/master/documentation//DeveloperGuide.md)
+for instructions on how to build, run and debug MIRAI.
 
+<!--
 ## Installing __________
 ...
 
@@ -32,7 +34,7 @@ __________ requires or works with
 * Facebook page:
 * Mailing list
 * irc:  -->
-See the CONTRIBUTING file for how to help out.
+See the [CONTRIBUTING](https://github.com/facebookexperimental/MIRAI/blob/master/CONTRIBUTING.md) file for how to help out.
 
 ## License
-Mirai is MIT licensed, as found in the LICENSE file.
+Mirai is MIT licensed, as found in the [LICENSE](https://github.com/facebookexperimental/MIRAI/blob/master/LICENSE) file.

documentation/DebuggingRustc.md

@@ -0,0 +1,72 @@
+# Debugging Rustc
+
+Since Mirai makes use of a private and unstable API with sparse documentation, it can be very helpful to debug
+Mirai while seeing the actual rustc sources in the debugger. By default, this does not happen.
+
+To work around this some painful steps need to be taken. First of all, get the sources of rustc and build them.
+
+```
+# cd to the directory where you want to keep the rust compiler sources
+git clone https://github.com/rust-lang/rust/ rustc
+cd rustc
+cp config.toml.example config.toml
+# Now edit config.toml and set debug, debug-assertions, debuginfo, and debuginfo-lines to true
+./x.py build src/rustc
+# You may have to change the architecture in the next command
+rustup toolchain link custom build/nightly-x86_64-apple-darwin/stage2
+```
+
+If you have done the above previously, be sure to pull down the latest changes from the github repo.
+
+Next build the Mirai sources.
+
+```
+# cd to your mirai directory
+rustup override set custom
+cargo clean
+cargo build
+```
+
+Now switch back to using the nightly build, or the Rust Language Service (RLS) will crash when you try to load VSCode or 
+Clion.
+
+```
+rustup override set nightly
+```
+
+Now close and reload VSCode (Clion does not support this scenario) and modify the configuration to reference the custom 
+build of rustc
+
+```    {
+        "type": "lldb",
+        "request": "launch",
+        "name": "Debug executable 'mirai'",
+        "cargo": {
+            "args": [
+                "build",
+                "--bin=mirai",
+                "--package=Mirai"
+            ],
+            "filter": {
+                "kind": "bin"
+            }
+        },
+        "env": {
+           "DYLD_LIBRARY_PATH": "${env:HOME}/.rustup/toolchains/custom/lib",
+        },
+        "sourceLanguages": ["rust"],
+        "args": [<what you'll give to rustc, split into an array of strings using space as the delimiter>],
+        "cwd": "${workspaceFolder}",
+    },
+```
+
+Now switch back to the custom build, otherwise mirai wont load.
+
+```
+rustup override set custom
+```
+
+And now you can finally debug while seeing rustc sources. Be aware, however, that doing anything in the editor that
+invokes the RLS will cause it to crash, which sooner or later causes all sorts of trouble.
+
+When you are done debugging, revert to the nightly build.

documentation/DeveloperGuide.md

@@ -0,0 +1,74 @@
+# Developer Guide
+
+## Building
+
+You'll need to have Rust installed on your system. See 
+[here](https://doc.rust-lang.org/book/2018-edition/ch01-01-installation.html) for instructions.
+
+Mirai depends on unstable private APIs of the rust compiler to do things like parsing, type checking and
+lowering to MIR. These can only be accessed by using the nightly build of the compiler. So use rustup to set
+the nightly build as the default for the mirai project.
+
+```rustup override set nightly```
+
+That done, all you need to do to build Mirai is to type `cargo build` in your command shell. Generally building happens 
+automatically as you run tests.
+
+
+## Editing
+
+The best editing experience seems to be with [Clion](https://www.jetbrains.com/clion/). 
+
+Alternatively there is also
+[VSCode](https://code.visualstudio.com/). You'll want to install these extensions: 
+[Rust (rls)](https://github.com/rust-lang-nursery/rls-vscode), [CodeLLDB](https://github.com/vadimcn/vscode-lldb) and
+[Better TOML](https://github.com/bungcip/better-toml).
+
+There is also [Nuclide](https://nuclide.io/). You'll want to install the [Rust](https://atom.io/packages/language-rust)
+extension. This option is pretty basic and not recommended right now. It does have a better integration with Git, so I
+actually use Clion for editing, VSCode for debugging and Nuclide for doing source control.
+
+## Running
+
+Run the mirai binary as if it were rustc. To do this via cargo, set the `RUSTC_WRAPPER` environment variable to `mirai`.
+
+At the moment you'll also need to set the `DYLD_LIBRARY_PATH` environment variable to
+`~/.rustup/toolchains/nightly-x86_64-apple-darwin/lib`. This is a bit strange and I'd love to find out how to avoid
+it.
+
+## Debugging
+
+VSCode gives a better experience than Clion at the moment. To use VSCode you'll need to add the following to the
+configurations property of the content of the launch.json file in the .vscode directory of your project directory:
+```    {
+        "type": "lldb",
+        "request": "launch",
+        "name": "Debug executable 'mirai'",
+        "cargo": {
+            "args": [
+                "build",
+                "--bin=mirai",
+                "--package=Mirai"
+            ],
+            "filter": {
+                "kind": "bin"
+            }
+        },
+        "env": {
+           "DYLD_LIBRARY_PATH": "${env:HOME}/.rustup/toolchains/nightly-x86_64-apple-darwin/lib",
+        },
+        "sourceLanguages": ["rust"],
+        "args": [<what you'll give to rustc, split into an array of strings using space as the delimiter>],
+        "cwd": "${workspaceFolder}",
+    },
+```
+
+Since Mirai makes use of a private and unstable API with sparse documentation, it can be very helpful to debug
+Mirai while seeing the actual rustc sources in the debugger. By default, this does not happen. To make it happen, see 
+[debugging](https://github.com/facebookexperimental/MIRAI/blob/master/documentation/DebuggingRustc.md) with Rustc 
+sources.
+
+## Testing
+
+For now we test mirai by running it on itself, by doing `cargo build` in the mirai directory while setting the 
+`RUSTC_WRAPPER` environment variable to `mirai`.