Imported Upstream version 5.0.0.42

Former-commit-id: fd56571888259555122d8a0f58c68838229cea2b

external/corert/Documentation/README.md

@@ -0,0 +1,17 @@
+# Introduction to CoreRT Repo
+
+This is the repo for CoreRT, the .NET Core runtime optimized for AOT (Ahead of Time) compilation scenarios. This project is in early stages of its development. [The high-level engineering plan](high-level-engineering-plan.md) lists major parts that needs to come together for it to become a complete runtime for .NET Core.
+
+## Architecture
+
+- [Intro to .NET Native and CoreRT](intro-to-corert.md)
+- [High-level Engineering Plan](high-level-engineering-plan.md)
+
+## Developer Guide
+
+- [Prerequisites for building](prerequisites-for-building.md)
+- [How to build and run from the Command Line](how-to-build-and-run-ilcompiler-in-console-shell-prompt.md)
+- [How to build and run from Visual Studio](how-to-build-and-run-ilcompiler-in-visual-studio-2015.md)
+- [How to build and run from VSCode](how-to-build-and-run-ilcompiler-in-vscode.md)
+- [How to run tests](how-to-run-tests.md)
+- [Cross Compilation for ARM on Linux](cross-building.md)

external/corert/Documentation/botr/type-system.md

@@ -0,0 +1,99 @@
+# Type System Overview
+
+Author: Michal Strehovsky ([@MichalStrehovsky](https://github.com/MichalStrehovsky)) - 2016
+
+## Introduction
+
+The type system is a major component of CoreRT. It represents the modules, types, methods, and fields within a program and provides higher level services to the type system users that lets them get answers to various interesting questions.
+
+Some of the high level services the type system provides are:
+
+* Loading new types from the metadata
+* Computing set of interfaces implemented by a specific type
+* Computing static and instance field layout (assigning offsets to individual fields)
+* Computing static and instance GC layout of types (identifying GC pointers within object/class data)
+* Computing VTable layout (assigning slots to virtual methods) and resolving virtual methods to slots
+* Deciding whether a type can be stored to a location of another type
+
+Three major themes drive the design of the type system:
+
+1. Low overhead and high performance
+2. Concurrency
+3. Extensibility and reusability
+
+Low overhead is achieved by lazy loading - instead of eagerly populating the types with fields, various attributes, names, etc. these are read on demand from the underlying data source (metadata). Caching is used conservatively.
+
+Where necessary, partial classes, extension methods, and pluggable algorithms are used to achieve goal 3 instead of polymorphism and object hierarchies. The reusability of the type system is at the source level (source-including different sets of files to get different features). This allows extensibility without making sacrifices that would take us away from goal 1.
+
+The type system in its purest form (i.e. without any partial class extensions) tries to avoid introducing concepts that are not defined in the [ECMA-335 specification](http://www.ecma-international.org/publications/standards/Ecma-335.htm). The specification is a suggested prerequisite reading to this document and provides definitions to various terms used in this document.
+
+## Relationship with metadata
+
+While metadata (such as the file formats described in the ECMA-335 specification) has a close relationship with the type system, there is a clear distinction between these two: the metadata describes physical shape of the type (e.g. what is the base class of the type; or what fields does it have), but the type system builds higher level concepts on top of the shape (e.g. how many bytes are required to store an instance of the type at runtime; what interfaces does the type implement, including the inherited ones).
+
+The type system provides access to most of the underlying metadata, but abstracts the way it was obtained. This allows types and members that are backed by metadata in other formats, or in no physical format at all (such as methods on array types), to be representable within the same type system context.
+
+## Type system class hierarchy
+
+The classes that represent types within the type system are:
+
+![hierarchy](../images/typesystem-hierarchy.png)
+
+Most of the classes in this hierarchy are not supposed to be derived by the type system user and many of them are sealed to prevent that.
+
+The classes that are extensible (and are actually abstract classes) are shown with dark background above. The concrete class should provide implementation of the abstract and virtual methods based on some logic, such as reading metadata from an ECMA-335 module file (the type system already provides such implementation of `MetadataType` in its `EcmaType`, for example). Ideally, the type system consumers should operate on the abstract classes and use the concrete class only when creating a new instance. Casting to the concrete implementation type such as `EcmaType` is discouraged.
+
+## Type system classes
+
+Following section goes briefly over the classes representing types within the type system.
+
+### TypeDesc
+
+`TypeDesc` is the base class of all types within the type system. It defines a list of operations all classes must support. Not all operations might make sense for all the children of `TypeDesc` (for example, it doesn't make sense to request a list of methods on a pointer type), but care is taken to provide an implementation that makes sense for each particular child (i.e. the list of methods on a pointer type is empty).
+
+### ParameterizedType (ArrayType, ByRefType, PointerType)
+
+These are constructed types with a single parameter:
+
+* an array (either multi-dimensional, or a vector - a single dimensional array with an implicit zero lower bound),
+* a managed reference, or
+* an unmanaged pointer type.
+
+Note the distinction between multidimensional arrays of rank 1 and vectors is a crucial one, and a source of potential bugs for the type system users. Type system users should take special care.
+
+### DefType (NoMetadataType, MetadataType)
+
+`DefType` represents a value type, interface, or a class. While most instances of `DefType` will be of children of `MetadataType` (a type that is based off of some concrete metadata describing the type in full), there will be scenarios where full metadata is no longer available. In those cases, only restricted information (such as the number of bytes occupied by the instance of the type on the GC heap, or whether the type is a value type) is available. It is important that the type system is able to operate on such types. E.g. it should be possible for a type with restricted metadata to be a base type for a type with full metadata and the field layout algorithm should be able to compute the field layout of such a type.
+
+### GenericParameter
+
+Represents a generic parameter, along with its constraints. Generic definitions are represented as instantiations over generic parameters.
+
+Note for readers familiar with the .NET reflection type system: while the .NET reflection type system doesn't distinguish between a generic definition (e.g. `List<T>`) and an open instantiation of a generic type (e.g. `List<!0>`), the CoreRT type system draws a distinction between those two. This distinction is important when representing member references from within IL method bodies - e.g. an IL reference using an LDTOKEN instruction to `List<T>.Add` should always refer to the uninstantiated definition, while a reference to `List<!0>.Add` will refer to a concrete method after substituting the signature variable.
+
+### SignatureVariable (SignatureTypeVariable, SignatureMethodVariable)
+
+Signature variables represent variables that can be substituted by other types within the system. They differ from generic parameters (because e.g. they don't have constraints or variance). They are simply placeholders to be replaced by other types as part of a process called instantiation. Signature variables have an index that refers to a position within the instantiation context.
+
+## Other type system classes
+
+Each use of a type system starts with creating a type system context. A type system context represents a type universe across which all types share reference identity (two `TypeDesc` objects represent identical types if and only if they are the same object instance). Type system context is used to resolve all modules and constructed types within the universe. It's not legal to create new instances of constructed types outside of the type system context.
+
+Other important classes within the type system are a `MethodDesc` (represents a method within the type system) and `FieldDesc` (represents a field within the type system). A `ModuleDesc` describes a single module which can optionally implement `IAssemblyDesc` interface if the module is an assembly. `ModuleDesc` is typically the owner of the type/method/field definitions within the module. It's the responsibility of the `ModuleDesc` to maintain the reference identity of those.
+
+## Pluggable algorithms
+
+Most algorithms (e.g. the field layout algorithm) provided by the type system are pluggable. The type system context can influence the choice of the algorithm by providing different implementations of it.
+
+The algorithms are used as an extensibility mechanism in places where partial classes and source inclusion wouldn't be sufficient. The choice of the particular algorithm might depend on multiple factors and the type system user might want to use multiple algorithms depending on a certain set of conditions determined at runtime (e.g. computing the list of runtime interfaces of regular `DefTypes` vs. the runtime interfaces of array types).
+
+## Hash codes within the type system
+
+An interesting property of the type system lays in its ability to compute hash codes that can be reliably computed for any type or method represented within the system at compile time and at runtime. Having the same hash code available at both compile time and runtime is leveraged to build high performance lookup tables used by the CoreRT runtime. The hash code is computed from type names and gets preserved as part of the runtime data structures so that it's available in situations when the type name has been optimized away by the compiler.
+
+## Physical architecture
+
+The type system implementation is found in:
+* `src/Common/src/TypeSystem/Common`: most of the common type system is here
+* `src/Common/src/TypeSystem/Ecma`: concrete implementations of `MetadataType`, `MethodDesc`, `FieldDesc` etc. that read metadata from ECMA-335 module files is here
+* `src/ILCompiler.TypeSystem/tests`: unit tests that shed some light into the operation and features of the type system. This is a good starting point to learn about the code.

external/corert/Documentation/cross-building.md

@@ -0,0 +1,51 @@
+Cross Compilation for ARM on Linux
+==================================
+
+Through cross compilation, on Linux it is possible to build CoreCLR for arm or arm64.
+
+Requirements
+------------
+
+You need a Debian based host and the following packages needs to be installed:
+
+    $ sudo apt-get install qemu qemu-user-static binfmt-support debootstrap
+
+In addition, to cross compile CoreCLR the binutils for the target are required. So for arm you need:
+
+    $ sudo apt-get install binutils-arm-linux-gnueabihf
+
+and conversely for arm64:
+
+    $ sudo apt-get install binutils-aarch64-linux-gnu
+
+
+Generating the rootfs
+---------------------
+The `cross\build-rootfs.sh` script can be used to download the files needed for cross compilation. It will generate an Ubuntu 14.04 rootfs as this is what CoreCLR targets.
+
+    Usage: build-rootfs.sh [BuildArch]
+    BuildArch can be: arm, arm64
+
+The `build-rootfs.sh` script must be run as root as it has to make some symlinks to the system, it will by default generate the rootfs in `cross\rootfs\<BuildArch>` however this can be changed by setting the `ROOTFS_DIR` environment variable.
+
+For example, to generate an arm rootfs:
+
+    $ sudo ./cross/build-rootfs.sh arm
+
+and if you wanted to generate the rootfs elsewhere:
+
+    $ sudo ROOTFS_DIR=~/coreclr-cross/arm ./build-rootfs.sh arm
+
+Cross compiling CoreCLR
+-----------------------
+Once the rootfs has been generated, it will be possible to cross compile CoreCLR. If `ROOTFS_DIR` was set when generating the rootfs, then it must also be set when running `build.sh`.
+
+So, without `ROOTFS_DIR`:
+
+    $ ./build.sh arm debug verbose clean cross
+
+And with:
+
+    $ ROOTFS_DIR=~/coreclr-cross/arm ./build.sh arm debug verbose clean cross
+
+As usual the resulting binaries will be found in `bin/Product/BuildOS.BuildArch.BuildType/`

external/corert/Documentation/design-docs/diagnostics/diagnostics-tools-contract.md

@@ -0,0 +1,26 @@
+# Diagnostics Tools Contract
+ 
+To perform its function, diagnostics tools need to make assumptions on how the compiler, runtime, and framework works. This was done in various obscure ways. Often, the dependency is taken in another code base such that breaking changes are detected only in runtime during integration tests, which is often too late. 
+ 
+The crux of the problem is that the contract is implicit. Therefore, we are making changes to the product so that we establish a formal and explicit contract between the components and the diagnostics tools. For example, certain kind of breaking changes can now be detected during build time. You are reading this probably because you have made a change that broke the contract. In the sequel of the document, we will talk about why your change is breaking and what can you do about it.
+ 
+## Overall Principle
+At a breakpoint when the debuggee stops. We can look at any memory freely in the debuggee. This is often the most convenient way to perform any debugging operation. Therefore, unlike other applications, debuggers are mostly interested in the fields of the debuggee, not the APIs. This is especially true in the AOT scenario where we do not have support for true function evaluation in the debuggee, yet.
+
+The debugger accesses the field through symbols, so this is mostly a no-op for the framework developers. But there are a few exceptions because the debugger is trying to make sense of those objects and give better diagnostics experience, for example:
+ 
+### Strings
+In a typical application, you have many strings. Strings are just another managed object such that we can inspect all the fields out of it. There is a character array, we can inspect the characters. But that would be an awful experience. The user will want to just look at the string. In order to do that, the debugger makes an assumption that `System.String._firstChar` represent the head of the character array and get the string out the debuggee memory and display as a string. 
+ 
+Now imagine what would happen if the field is renamed? The debugger will not be able to find the string, and it may fallback any other approach. That is fundamentally why we need to keep the fields unchanged. Not only the name and its existence, but also its meaning. If `_firstChar` is repurposed to mean something else, the debugger would output something wrong, which is arguably worse.
+ 
+### StringBuilder
+Most data structures are linked, in a typical debugging scenario, you would want to know the list content without having to traverse a tree of pointers. Luckily, the code that is required to traverse the pointer is in the debuggee itself, so mostly the debugger do not need to take a dependency on the semantic structure of the tree, by just leveraging the capability of the debuggee to decode its own data. An interesting example would be the `StringBuilder`. A debugging developer would most likely want to know what is the string that is currently in the `StringBuilder`, not the chunks. Because the debuggee is stopped, we cannot run the debuggee code, but we could run those code out of the debuggee process and access memory as those code being run. The key challenges for that is that, as of now (1st July 2016), we do not support inspecting ThreadStatic fields, so whenever such an out of process execution need a thread static field, it will need to fall back to some other means to simulate it. That is why the diagnostics tool is taking a dependency on the various ThreadStatic fields. 
+ 
+Note that this is just a temporary restriction and we are looking forward to eliminating these dependencies in the future.
+ 
+### Async Stepping
+Not just inspection, sometimes other operations need to take dependencies on fields as well. A good example would be async stepping. Where would you like to stop when you try to step out an async call, you would like to get back to the next line of the caller, right? In order to do that, the debugger needs to know which thread to go back to, and this is done by inspecting the data structure generated by the compiler and the framework.
+
+## Questions?
+If you are trying to make a change that you have to break the contract, please contact us, @dotnet/dotnet-diag.

external/corert/Documentation/engineering/updating-coreclr-tests.md

@@ -0,0 +1,14 @@
+# Updating CoreCLR Tests Zip
+
+The set of CoreCLR tests run as part of CoreRT's CI and available via `tests\runtest.cmd /coreclr` download are downloaded as a zip file from the CoreCLR build. We use a specific build number to ensure we're running against a set of tests known to be compatible with CoreRT. Rolling forward to a new set of tests involves these steps:
+
+1. Find a known good tests.zip from the CoreCLR build
+   1. Go to https://github.com/dotnet/coreclr/pulls and open the most-recently passing PR (it should have a green check mark next to it)
+   2. In the CI checks, open the details for `Windows_NT x64 Debug Build and Test`
+   3. Navigate through `Build Artifacts` -> `bin` -> `tests`
+   4. Copy the URL to `tests.zip`
+2. Retain the CI build so Jenkins doesn't delete `tests.zip`
+   1. In the PR job page (where you clicked `Build Artifacts` earlier) ensure you're logged in to Jenkins
+   2. Click the `Keep this build forever` button at the top-right
+3. Paste the `tests.zip` URL into `CoreCLRTestsURL.txt`
+4. Check your work by building and then running `tests\runtest.cmd /coreclr`

external/corert/Documentation/high-level-engineering-plan.md

@@ -0,0 +1,61 @@
+##Runtime
+
+- Build managed parts
+	- Build language source to IL
+	- Compile IL assembly with ILC compiler
+- Unix
+	- Runtime Unix PAL
+	- Assembly port
+	- Thread suspension - hijacking
+- RyuJIT EH
+	- Define Runtime/Codegen contract
+- Stack unwinding
+	- JIT: Produce platform-specific unwind info
+	- Runtime to consume the platform specific unwind info
+- Managed/native transitions helpers (both pinvoke and reverse pinvoke)
+	- JIT: emit the right transition helpers
+	- Implement the transition helpers
+- GC info encoding (for precise GC)
+	- Enable conservative GC
+	- Toolchain support to write the GCInfo into final binary
+	- Runtime to consume GCInfo produced by RyuJIT today for precise GC
+
+##Toolchain
+
+- Split compilation
+	- Design document
+		- Robust name mangling
+		- Generics (comdat foldable section, or special module)
+	- Implementation
+		- Phase 1 - Single obj for System.Private.CoreLib
+		- Phase 2 - Respective object file for everything else (1:1 Assembly:ObjectFile mapping)
+- Produce complete EE types in the toolchain
+- Stubs - Delegates, etc.
+- Adjustments for RyuJIT / UTC difference
+
+##Reflection
+
+- Produce compact metadata in the final binary
+- Produce mapping tables
+- Runtime consumption
+
+##Interop
+
+- Move MCG [Marshaling Code Generator](http://blogs.msdn.com/b/dotnet/archive/2014/06/13/net-native-deep-dive-debugging-into-interop-code.aspx) to github
+- Package MCG as standalone tool
+- Integrate MCG with ILToNative toolchain
+
+##Framework
+
+- Move all .NET Native System.Private* libraries over to github
+- Complete .NET Native specific libraries in corefx (build, port to Unix)
+- Port to Win32/Unix
+
+##Shared generics
+
+- Toolchain - produce supporting tables and fixups
+
+##CPPCodegen
+
+- Complete IL to CPP codegenerator
+- Portable EH

external/corert/Documentation/how-to-build-and-run-ilcompiler-in-console-shell-prompt.md

@@ -0,0 +1,110 @@
+_Please ensure that [pre-requisites](prerequisites-for-building.md) are installed for a successful build of the repo._
+
+# Build ILCompiler #
+
+Build your repo by issuing the following command at repo root:
+
+```
+build[.cmd|.sh] clean [Debug|Release]
+```
+
+This will result in the following:
+
+- Restore nuget packages required for building
+- Build native and managed components of ILCompiler. The final binaries are placed to `<repo_root>\bin\Product\<OS>.<arch>.<Config>\packaging\publish1`.
+- Build and run tests
+
+# Install latest CLI tools
+
+* Download latest CLI tools from [https://github.com/dotnet/cli/](https://github.com/dotnet/cli/) and add them to the path. The latest CLI tools include MSBuild support that the native compilation build integration depends on.
+* On windows ensure you are using the 'VS2015 x64 Native Tools Command Prompt'
+    (This is distinct from the 'Developer Command Prompt for VS2015')
+
+You should now be able to use the `dotnet` commands of the CLI tools.
+
+# Compiling source to native code using the ILCompiler you built#
+
+* Ensure that you have done a repo build per the instructions above.
+* Create a new folder and switch into it. 
+* Run `dotnet new` on the command/shell prompt. This will add a project template. If you get an error, please ensure the [pre-requisites](prerequisites-for-building.md) are installed. 
+* Modify `.csproj` file that is part of your project. A few lines at the top and at the bottom are different from the default template.
+
+```
+<Project ToolsVersion="15.0">
+  <Import Project="$(MSBuildSDKsPath)\Microsoft.NET.Sdk\Sdk\Sdk.props" />
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp1.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Include="**\*.cs" />
+    <EmbeddedResource Include="**\*.resx" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NETCore.App" Version="1.0.1" />
+  </ItemGroup>
+
+  <Import Project="$(MSBuildSDKsPath)\Microsoft.NET.Sdk\Sdk\Sdk.targets" />
+  <Import Project="$(IlcPath)\Microsoft.NETCore.Native.targets" />
+</Project>
+
+```
+
+* Set IlcPath environment variable to point to the built binaries. Alternatively, pass an extra `/p:IlcPath=<repo_root>\bin\Product\Windows_NT.x64.Debug\packaging\publish1` argument to all dotnet commands below.
+
+    * Unix: `export IlcPath=<repo_root>/bin/Product/Linux.x64.Debug/packaging/publish1`
+
+    * Windows: `set IlcPath=<repo_root>\bin\Product\Windows_NT.x64.Debug\packaging\publish1`
+
+* Run `dotnet restore`. This will download nuget packages required for compilation.
+
+* Please [open an issue](https://github.com/dotnet/corert/issues) if these instructions do not work anymore. .NET Core integration with MSBuild is work in progress and these instructions need updating accordingly from time to time.
+
+## Using RyuJIT ##
+
+This approach uses the same code-generator (RyuJIT), as [CoreCLR](https://github.com/dotnet/coreclr), for compiling the application. Linking is done using the platform specific linker.
+
+From the shell/command prompt, issue the following commands, from the folder containing your project, to generate the native executable
+
+``` 
+    dotnet build /t:LinkNative
+``` 
+
+Native executable will be dropped in `./bin/[configuration]/native/` folder and will have the same name as the folder in which your source file is present.
+
+## Using CPP Code Generator ##
+
+This approach uses platform specific C++ compiler and linker for compiling/linking the application.
+
+From the shell/command prompt, issue the following commands to generate the native executable:
+
+``` 
+    dotnet build /t:LinkNative /p:NativeCodeGen=cpp
+```
+
+For CoreRT debug build on Windows, add an extra `/p:AdditionalCppCompilerFlags=/MTd` argument.
+
+## Workarounds for build errors on Windows ##
+
+If you are seeing errors such as:
+
+```
+    LNK2038: mismatch detected for 'RuntimeLibrary': value 'MTd_StaticDebug' doesn't match value 'MT_StaticRelease'
+```
+
+- Make sure to use release build, or pass the extra `/p:AdditionalCppCompilerFlags=/MTd` argument above.
+
+If you are seeing errors such as: 
+
+```
+    LINK : fatal error LNK1104: cannot open file 'kernel32.lib'
+    Linking of intermediate files failed.
+```
+
+ - Make sure you run these commands from the 'VS2015 x64 Native Tools Command Prompt' instead of a vanilla command prompt
+ - Search for the missing lib files in your SDK, for example under C:\Program Files (x86)\Windows Kits\10\lib. Make sure the path to these libraries is included in the LIB environment variable. It appears VS 2015 RTM developer command prompt does not correctly set the LIB paths for the 10586 Windows SDK. VS 2015 Update 1 resolves that issue, so installing it is another alternative.
+
+For more details see the discussion in issue #606

external/corert/Documentation/how-to-build-and-run-ilcompiler-in-visual-studio-2015.md

@@ -0,0 +1,65 @@
+_Please ensure that [pre-requisites](prerequisites-for-building.md) are installed for a successful build of the repo._
+
+_Note_:
+
+* Instructions below assume `c:\corert` is the repo root.
+
+# Build ILCompiler #
+
+Build your repo by issuing the following command at repo root:
+
+```
+build.cmd
+```
+
+If you changed `c:\corert\src\ILCompiler\repro\project.json`
+
+```
+build.cmd clean
+```
+
+_Note: The size of NuGet packages is approximately 2.75 GB, so download might take a few moments based on the speed of your internet connection. The build artifacts require additional ~1 GB, thus make sure you have at least 4 GB of free space._
+
+## Using RyuJIT ##
+
+1. Open c:\corert\src\ILCompiler\ILCompiler.sln in VS
+
+  - Set "desktop" project in solution explorer as your startup project
+
+  - Set startup command line to:
+`@c:\corert\bin\obj\Windows_NT.x64.Debug\ryujit.rsp`
+
+  - Build & run using **F5**
+    - This will run the compiler. The output is `c:\corert\bin\obj\Windows_NT.x64.Debug\repro\native\repro.obj` file.
+
+  - The repro project has a dummy program that you can modify for ad-hoc testing
+
+  - To suppress spew from NuGet during the build, go to NuGet Package Manager in Options, and uncheck `Allow NuGet to download missing packages`.
+
+2. Open `c:\corert\src\ILCompiler\reproNative\reproNative.vcxproj`
+
+  - Set breakpoint at ```__managed__Main``` in main.cpp
+  - Build & run using **F5**
+    - Once you hit the breakpoint, go to disassembly and step into - you are looking at the code generated by RyuJIT
+
+
+## Using CPP Code Generator ##
+
+1. Open `c:\corert\src\ILCompiler\ILCompiler.sln` in VS
+
+  - Set "desktop" project in solution explorer as your startup project
+
+  - Set startup command line to:
+`@c:\corert\bin\obj\Windows_NT.x64.Debug\cpp.rsp`
+
+    - `--codegenopt:nolinenumbers` command line option can be used to suppress generation of line number mappings in C++ files - useful for debugging
+
+  - Build & run using **F5**
+    - This will run the compiler. The output is `c:\corert\bin\obj\Windows_NT.x64.Debug\repro\native\repro.cpp` file.
+
+  - The repro project has a dummy program that you can modify for ad-hoc testing
+
+2. Open `c:\corert\src\ILCompiler\reproNative\reproNativeCpp.vcxproj`
+
+  - Set breakpoint at repro::Program::Main in main.cpp
+  - Build, run & step through as with any other C++ program

external/corert/Documentation/how-to-build-and-run-ilcompiler-in-vscode.md

@@ -0,0 +1,54 @@
+_Please ensure that [pre-requisites](prerequisites-for-building.md) are installed for a successful build of the repo._
+
+_Note_:
+
+* Instructions below assume ```~/corert``` is the repo root.
+
+# Setting up #
+
+Please make sure you have latest VS Code, C# extension, and .NET Core available. This guide is tested under C# 1.6.2 + VS Code 1.8.1 + CLI 1.0.0-preview4-004233.
+
+This guide assumes that your VS code workspace is set to the root of the repo. 
+
+# Running VS Code
+
+We've checked-in reasonable default ```launch.json``` and ```tasks.json``` under ```corert/.vscode``` directory. You only need to run vscode form corert root:
+
+```
+code ~/corert
+```
+
+And then press SHIFT+COMMAND+B to start the build.
+
+# Debugging ILC.exe using .NET Core Debugger #
+
+Go to the debug pane and click Debug, choose .NET Core as the environment. If needed, you can change program property in launch.json (the gear button) to point to a different flavor of ilc:
+
+```json
+            "osx": {
+                "program": "${workspaceRoot}/bin/Product/OSX.x64.Debug/packaging/publish1/ilc.dll"
+            },
+            "linux": {
+                "program": "${workspaceRoot}/bin/Product/Linux.x64.Debug/packaging/publish1/ilc.dll"
+            },
+```
+
+By default we've disabled automatic build before debug. If you want to change that, you can change the ```preLaunchTask``` property to ```"build"```. But this is not currently recommended.
+
+# Getting ILC response files
+
+A ```.ilc.rsp``` file path can be easily obtained from a .NET core project that you want to debug by following command:
+
+```
+dotnet build /t:LinkNative /t:Rebuild /v:Detailed | grep ".ilc.rsp"
+```
+
+Once you have the ilc path, you can change ```launch.json``` accordingly:
+
+```json
+            "args": ["@obj/Debug/netcoreapp1.0/native/<netcore_app_name>.ilc.rsp"],
+            "cwd": "<netcore_app_root_folder>",
+```
+
+* ```args``` - the argument to ILC
+* ```cwd``` - the current directory where ILC is running. You can set it to the .NET Core project root. 

external/corert/Documentation/how-to-run-tests.md

@@ -0,0 +1,91 @@
+# Testing CoreRT
+
+The CoreRT test harness can run in two modes - with the tests local to the CoreRT repo, or with tests from the [CoreCLR](http://github.com/dotnet/coreclr) repo. The local tests only provide basic sanity testing and it's recommended to run the CoreCLR tests which are much more thorough.
+
+The tests exercise both the runtime and the ILC compiler, which compiles IL into native code. The harness can test both the RyuJIT code generation backend, or the C++ backend of the ILC compiler.
+
+## Local Tests
+
+Make sure you have the [prerequisites](prerequisites-for-building.md) to build the repo, and run `build.cmd debug clean` at repo root level. This will build the CoreRT repo, compile the local test sources, and use the newly built ILC compiler to compile the tests to native code and run them. These tests also run as part of the CI.
+
+### How To Run
+
+On Windows:
+```
+cd {corert}
+build.cmd
+tests\runtest.cmd
+```
+
+On Linux / macOS:
+```
+cd {corert}
+./build.sh
+tests\runtest.sh
+```
+
+### Verifying tests pass
+You should see the below message when you build CoreRT or run the local tests manually, otherwise something is broken.
+
+```
+JIT - TOTAL: 7 PASSED: 7
+CPP - TOTAL: 2 PASSED: 2
+```
+
+## External Tests
+
+*Note: These are currently supported only on Windows and Ubuntu/macOS support is coming soon.*
+
+When runtest.cmd is passed the /coreclr switch, the harness will download the CoreCLR project's test suite, compile them to native with the CoreRT compiler, and run them.
+
+### How To Run
+
+Choose the set of tests you want to run. Currently the options are:
+* Top200
+    * Small set of the suite selected to provide broad coverage quickly (Under 10 minutes). These run as part of the CI when submitting a pull request.
+* KnownGood
+    * Subset of the suite previously validated to all pass on CoreRT. If these all pass you can be pretty sure you haven't regressed the compiler.
+* All
+    * The entire suite. Many of the tests will fail since CoreRT is still pre-release and some tests don't play well with an ahead-of-time compiler.
+
+On Windows:
+```
+tests\runtest.cmd /coreclr Top200|All|KnownGood
+```
+
+On Linux / macOS:
+
+**TBD**
+
+### Suppress Windows Error Reporting Dialogs
+It's advisable to use some sort of a dialog killer tool if you see test regressions as many tests fail with pop-ups for Windows Error Reporting. However, the following regedit scripts have also proven to be useful to mask these pop-ups.
+
+Disable WER *temporarily*:
+
+**Contents of disable-wer.reg**
+```
+REGEDIT4
+
+[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting]
+"DontShowUI"="1"
+"Disabled"="1"
+```
+
+Remember to enable:
+
+**Contents of enable-wer.reg**
+```
+REGEDIT4
+
+[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting]
+"DontShowUI"="0"
+"Disabled"=-
+```
+
+### Filtering Tests
+If you know a test is failing for a good reason or you want a clean baseline, please use ```corert\tests\KnownGood.CoreCLR.issues.targets``` to weed out bad tests or infrastructure errors until we fix them.
+
+### Test Logs
+When the tests finish execution, the log location will be written out and should be in bin\Logs:
+
+**Example:** ```corert\bin\Logs\TestRun_Windows_NT__x64__debug.html```

external/corert/Documentation/images/typesystem-hierarchy.svg

@@ -0,0 +1,432 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="856.59027mm"
+   height="156.91768mm"
+   viewBox="0 0 3035.1624 556.00752"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="typesystem-hierarchy.svg">
+  <defs
+     id="defs4">
+    <style
+       type="text/css"
+       id="style3338">
+      rect {
+        fill:#ffffff;
+        stroke:#000000;
+        stroke-width:1.4870007;
+      }
+      
+      text {
+        font-style:normal;
+        font-weight:normal;
+        font-size:40px;
+        line-height:125%;
+        font-family:sans-serif;
+        letter-spacing:0px;
+        word-spacing:0px;
+        fill:#000000;
+        fill-opacity:1;
+        stroke:none;
+        stroke-width:1px;
+        stroke-linecap:butt;
+        stroke-linejoin:miter;
+        stroke-opacity:1;
+      }
+    </style>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.35"
+     inkscape:cx="1235.4055"
+     inkscape:cy="179.08356"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:snap-grids="true"
+     fit-margin-top="10"
+     fit-margin-left="10"
+     fit-margin-right="10"
+     fit-margin-bottom="10"
+     inkscape:window-width="1920"
+     inkscape:window-height="1147"
+     inkscape:window-x="1912"
+     inkscape:window-y="-8"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(1361.0522,12.57084)">
+    <g
+       id="g3499"
+       transform="translate(-94.28572,14.285714)">
+      <rect
+         y="9.3199863"
+         x="233.10065"
+         height="118.51301"
+         width="238.513"
+         id="rect3338" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340"
+         y="79.09407"
+         x="258.1091"
+         xml:space="preserve"
+         ><tspan
+           y="79.09407"
+           x="258.1091"
+           id="tspan3342"
+           sodipodi:role="line">TypeDesc</tspan></text>
+    </g>
+    <g
+       id="g3504"
+       transform="translate(-580.00003,-13.991366)">
+      <rect
+         y="219.74541"
+         x="-478.96786"
+         height="118.04868"
+         width="432.33441"
+         id="rect3338-1" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6"
+         y="289.94162"
+         x="-452.25378"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369"
+           y="289.94162"
+           x="-452.25378"
+           sodipodi:role="line">ParameterizedType</tspan></text>
+    </g>
+    <g
+       id="g3534"
+       transform="translate(-742.85719,-12.562792)">
+      <rect
+         y="218.08467"
+         x="696.60431"
+         height="118.51301"
+         width="238.513"
+         id="rect3338-6" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-7"
+         y="288.61072"
+         x="733.90771"
+         xml:space="preserve"
+         ><tspan
+           y="288.61072"
+           x="733.90771"
+           id="tspan3342-3"
+           sodipodi:role="line">DefType</tspan></text>
+    </g>
+    <g
+       id="g3509"
+       transform="translate(-580.00003,-17.870354)">
+      <rect
+         y="406.69479"
+         x="-744.87561"
+         height="118.43563"
+         width="264.14993"
+         id="rect3338-1-1" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-3"
+         y="476.43018"
+         x="-712.82019"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-0"
+           y="476.43018"
+           x="-712.82019"
+           sodipodi:role="line">ArrayType</tspan></text>
+    </g>
+    <g
+       id="g3519"
+       transform="translate(-574.55175,-17.870323)">
+      <rect
+         y="406.69476"
+         x="-434.87561"
+         height="118.43563"
+         width="264.14993"
+         id="rect3338-1-1-1" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-3-8"
+         y="477.1821"
+         x="-408.30844"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-0-4"
+           y="477.1821"
+           x="-408.30844"
+           sodipodi:role="line">ByRefType</tspan></text>
+    </g>
+    <g
+       id="g3514"
+       transform="translate(-579.14428,-16.44178)">
+      <rect
+         y="405.30704"
+         x="-114.83482"
+         height="118.354"
+         width="292.63974"
+         id="rect3338-1-1-3" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-3-1"
+         y="475.09927"
+         x="-86.288383"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-0-0"
+           y="475.09927"
+           x="-86.288383"
+           sodipodi:role="line">PointerType</tspan></text>
+    </g>
+    <g
+       id="g3529"
+       transform="translate(-827.71076,-18.4315)">
+      <rect
+         y="407.3858"
+         x="941.30249"
+         height="118.1759"
+         width="359.93369"
+         id="rect3338-1-8"
+		 style="fill:#e0e0e0" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-35"
+         y="477.64563"
+         x="980.56622"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-9"
+           y="477.64563"
+           x="980.56622"
+           sodipodi:role="line">MetadataType</tspan></text>
+    </g>
+    <g
+       id="g3524"
+       transform="translate(-709.5593,-12.370545)">
+      <rect
+         y="401.38846"
+         x="359.51825"
+         height="118.04868"
+         width="412.33441"
+         id="rect3338-1-8-3"
+		 style="fill:#e0e0e0" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-35-3"
+         y="471.58469"
+         x="398.71832"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-9-5"
+           y="471.58469"
+           x="398.71832"
+           sodipodi:role="line">NoMetadataType</tspan></text>
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 138.81493,102.12998 -646.63348,229.0316"
+       id="path3539"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3499"
+       inkscape:connection-end="#g3504" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m -962.30549,323.80272 -120.63141,65.02172"
+       id="path3541"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3504"
+       inkscape:connection-end="#g3509" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m -860.85251,323.80272 -8.86996,65.02172"
+       id="path3543"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3504"
+       inkscape:connection-end="#g3519" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 3.1979053,324.03489 -73.353798,389.01791"
+       id="path3547"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3534"
+       inkscape:connection-end="#g3524" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 144.03951,324.03489 77.82452,64.91941"
+       id="path3549"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3534"
+       inkscape:connection-end="#g3529" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 197.78833,142.11871 -64.50161,63.40317"
+       id="path3551"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3499"
+       inkscape:connection-end="#g3534" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m -754.79849,323.80272 108.02783,65.06254"
+       id="path3553"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3504"
+       inkscape:connection-end="#g3514" />
+    <g
+       id="g3504-9"
+       transform="translate(816.73045,-13.991366)">
+      <rect
+         y="219.74541"
+         x="-478.96786"
+         height="118.04868"
+         width="412.33441"
+         id="rect3338-1-84"
+		 style="fill:#e0e0e0" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-4"
+         y="289.94162"
+         x="-452.25378"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-7"
+           y="289.94162"
+           x="-452.25378"
+           sodipodi:role="line">GenericParameter</tspan></text>
+    </g>
+    <g
+       id="g3504-8"
+       transform="translate(1374.5673,-13.991366)">
+      <rect
+         y="219.74541"
+         x="-478.96786"
+         height="118.04868"
+         width="412.33441"
+         id="rect3338-1-14" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-1"
+         y="289.94162"
+         x="-452.25378"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-4"
+           y="289.94162"
+           x="-452.25378"
+           sodipodi:role="line">SignatureVariable</tspan></text>
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 348.61951,142.11871 97.23925,63.63533"
+       id="path3418"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-end="#g3504-9"
+       inkscape:connection-start="#g3499" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 377.32793,108.5761 895.59944,220.32498"
+       id="path3420"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3499"
+       inkscape:connection-end="#g3504-8" />
+    <g
+       id="g3449"
+       transform="translate(74.938853,880.59448)">
+      <rect
+         y="-491.45618"
+         x="450.00528"
+         height="117.80791"
+         width="557.80792"
+         id="rect3338-1-14-2" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-1-4"
+         y="-421.38037"
+         x="476.59897"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-4-4"
+           y="-421.38037"
+           x="476.59897"
+           sodipodi:role="line">SignatureMethodVariable</tspan></text>
+    </g>
+    <g
+       id="g3481"
+       transform="translate(657.14297,729.16594)">
+      <rect
+         y="-340.07037"
+         x="477.10538"
+         height="117.89339"
+         width="503.6077"
+         id="rect3338-1-14-2-7" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3340-6-1-4-7"
+         y="-269.95181"
+         x="503.74182"
+         xml:space="preserve"
+         ><tspan
+           id="tspan3369-4-4-2"
+           y="-269.95181"
+           x="503.74182"
+           sodipodi:role="line">SignatureTypeVariable</tspan></text>
+    </g>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 1005.6048,323.80272 899.1607,389.1383"
+       id="path3486"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3504-8"
+       inkscape:connection-end="#g3449" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 1193.3273,323.80272 101.2846,65.29285"
+       id="path3488"
+       inkscape:connector-type="polyline"
+       inkscape:connector-curvature="3"
+       inkscape:connection-start="#g3504-8"
+       inkscape:connection-end="#g3481" />
+  </g>
+</svg>

external/corert/Documentation/intro-to-corert.md

@@ -0,0 +1,30 @@
+Intro to .NET Native and CoreRT
+===============================
+
+Native compilation is a great scenario addition to .NET Core apps on Windows, OS X and Linux. We've seen significant startup and throughput benefits of native compilation for Windows UWP apps, using .NET Native. Today, many native apps and tools benefit from being compiled by a C++ compiler, and not as much by being written in C++. .NET Native brings much of the performance and all of the deployment benefits of native compilation, while retaining your ability to write in your favorite .NET programming language.
+
+Architecture
+============
+
+[.NET Native](https://msdn.microsoft.com/library/dn584397.aspx) is a native  toolchain that compiles [IL byte code](https://en.wikipedia.org/wiki/Common_Intermediate_Language) to machine code (e.g. X64 instructions). By default, .NET Native (for .NET Core, as opposed to UWP) uses RyuJIT as an ahead-of-time (AOT) compiler, the same one that CoreCLR uses as a just-in-time (JIT) compiler. It can also be used with other compilers, such as [LLILC](https://github.com/dotnet/llilc), UTC for UWP apps and [IL to CPP](https://github.com/dotnet/corert/tree/master/src/ILCompiler.Compiler/src/CppCodeGen) (an IL to textual C++ compiler we have built as a reference prototype).
+
+[CoreRT](https://github.com/dotnet/corert) is the .NET Core runtime that is optimized for AOT scenarios, which .NET Native targets. This is a refactored and layered runtime. The base is a small native execution engine that provides services such as garbage collection(GC). This is the same GC used in CoreCLR. Many other parts of the traditional .NET runtime, such as the [type system](https://github.com/dotnet/corert/tree/master/src/Common/src/TypeSystem), are implemented in C#. We've always wanted to implement runtime functionality in C#. We now have the infrastructure to do that. In addition, library implementations that were built deep into CoreCLR, have also been cleanly refactored and implemented as C# libraries. 
+
+Experience
+==========
+
+.NET Native offers great benefits that are critical for many apps. 
+
+- The native compiler generates a *SINGLE FILE*, including the app, managed dependencies and CoreRT.
+- Native compiled apps startup faster since they execute already compiled code. They don't need to generate machine code at runtime nor load a JIT compiler.
+- Native compiled apps can use an optimizing compiler, resulting in faster throughput from higher quality code (C++ compiler optimizations). Both the LLILLC and IL to CPP compilers rely on optimizing compilers.
+
+These benefits open up some new scenarios for .NET developers
+
+- Copy a single file executable from one machine and run on another (of the same kind) without installing a .NET runtime.
+- Create and run a docker image that contains a single file executable (e.g. one file in addition to Ubuntu 14.04).
+
+Roadmap
+=======
+
+To start, we are targeting native executables (AKA "console apps"). Over time, we'll extend that to include ASP.NET 5 apps. You can continue to use CoreCLR for your .NET Core apps. It remains a great option if native compilation isn't critical for your needs. CoreCLR will also provide a superior debugging experience until we add debugging support to CoreRT.

external/corert/Documentation/prerequisites-for-building.md

@@ -0,0 +1,30 @@
+The following pre-requisites need to be installed for building the repo:
+
+# Windows (Windows 7+)
+
+1. Install [Visual Studio 2015](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx), including Visual C++ support. Visual Studio 2017 RC also works, but you will need to pass `vs2017` as a parameter to the build script to build using this version.
+2. Install [CMake](http://www.cmake.org/download/). We use CMake 3.3.2 but any later version should work.
+3. (Windows 7 only) Install PowerShell 3.0. It's part of [Windows Management Framework 3.0](http://go.microsoft.com/fwlink/?LinkID=240290). Windows 8 or later comes with the right version inbox.
+
+PowerShell also needs to be available from the PATH environment variable (it's the default). Typically it should be %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\.
+
+# Ubuntu (14.04)
+
+Install basic dependency packages:
+
+First add a new package source to be able to install clang-3.9:
+```sh
+echo "deb http://llvm.org/apt/trusty/ llvm-toolchain-trusty-3.9 main" | sudo tee /etc/apt/sources.list.d/llvm.list
+wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add -
+sudo apt-get update
+```
+
+```sh
+sudo apt-get install cmake clang-3.9 libicu52 libunwind8
+```
+
+# Mac OSX (10.11.5+)
+
+1. Install [Command Line Tools for XCode 8](https://developer.apple.com/xcode/download/) or higher. 
+2. Install [CMake](https://cmake.org/download/). Launch `/Applications/CMake.app/Contents/MacOS/CMake` GUI. Goto "OSX App Menu -> Tools -> Install For Command Line Use" and follow the steps. CMake < 3.6 has [a bug](https://cmake.org/Bug/view.php?id=16064) that can make `--install` fail. Do `sudo mkdir /usr/local/bin` to work around.
+3. Install OpenSSL. Build tools have a dependency on OpenSSL. You can use [Homebrew](http://brew.sh/) to install it: with Homebrew installed, run `brew install openssl` followed by `ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/`, followed by `ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/`.