[docs] Update the getting started guide and LLVM compilation guide.

Author: tritao

docs/BuildingLLVM.md

@@ -3,88 +3,67 @@
 This document explains how to build LLVM and Clang from source code.
 
 It's a process only recommended for developers that need to make changes to LLVM or Clang, or
-build the binary packages needed for the CI system.
+build the binary packages needed for the CI system. If you just want to build CppSharp, then
+check out the getting started guide section on how to download our pre-compiled LLVM packages.
 
-Git repository URLs found here: [http://llvm.org/docs/GettingStarted.html#git-mirror]
-(http://llvm.org/docs/GettingStarted.html#git-mirror)
+## Compiling using the build script
 
-1. Clone LLVM to `<CppSharp>\deps\llvm`
-2. Clone Clang to `<CppSharp>\deps\llvm\tools\clang`
+This is the preferred way to compile LLVM for usage by CppSharp.
 
-Required LLVM/Clang commits:
+1. Before building, ensure Git, CMake and Ninja are installed and acessible from the command line.
 
-[LLVM: see /build/LLVM-commit.](https://github.com/mono/CppSharp/tree/master/build/LLVM-commit)
-
-[Clang: see /build/Clang-commit.](https://github.com/mono/CppSharp/tree/master/build/Clang-commit)
+Check the official download pages for each project for further instructions:
 
-## Compiling on Windows/Visual Studio
+- [Git](https://git-scm.com/downloads)
+- [Ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages)
+- [CMake](https://cmake.org/download/)
 
-```shell
-cd <CppSharp>\deps\llvm\build
-
-cmake -G "Visual Studio 12" -DCLANG_BUILD_EXAMPLES=false -DCLANG_INCLUDE_DOCS=false -DCLANG_INCLUDE_TESTS=false -DCLANG_INCLUDE_DOCS=false -DCLANG_BUILD_EXAMPLES=false -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_INCLUDE_EXAMPLES=false -DLLVM_INCLUDE_DOCS=false -DLLVM_INCLUDE_TESTS=false ..
-
-msbuild LLVM.sln /p:Configuration=RelWithDebInfo;Platform=Win32 /m
+2. Navigate to the `<CppSharp>/build` directory
+3. Clone, build and package LLVM with
 ```
-
-Or, if you need 64-bit binaries:
-
-```shell
-cd <CppSharp>\deps\llvm\build
-
-cmake -G "Visual Studio 12 Win64" -DCLANG_BUILD_EXAMPLES=false -DCLANG_INCLUDE_DOCS=false -DCLANG_INCLUDE_TESTS=false -DCLANG_INCLUDE_DOCS=false -DCLANG_BUILD_EXAMPLES=false -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_INCLUDE_EXAMPLES=false -DLLVM_INCLUDE_DOCS=false -DLLVM_INCLUDE_TESTS=false ..
-
-msbuild LLVM.sln /p:Configuration=RelWithDebInfo;Platform=x64 /m
+$PREMAKE --file=scripts/LLVM.lua clone_llvm
+$PREMAKE --file=scripts/LLVM.lua build_llvm
+$PREMAKE --file=scripts/LLVM.lua package_llvm
 ```
 
-## Compiling on Mac OS X
+`$PREMAKE` should be replaced with `premake5.exe`, `premake5-osx` or `premake5-linux-64` depending on environment.
 
-### Compiling manually
+You can specify an `--arch=x86` or `--arch=x64` flag to the invocations above to specify an explicit build architecture.  
 
-1. Compile LLVM solution in *RelWithDebInfo* mode
-   The following CMake variables should be enabled:
-    - LLVM_ENABLE_LIBCXX (enables libc++ standard library support)
-    - LLVM_BUILD_32_BITS for 32-bit builds (defaults to 64-bit)
+If the `clone_llvm` step fails, you can try to manually clone LLVM and Clang as explained below.
+You should still run clone_llvm to ensure that you are on the correct revision.
 
-```shell
-mkdir -p deps/llvm/build && cd deps/llvm/build
+## Cloning from Git
 
-cmake -G "Unix Makefiles" -DLLVM_ENABLE_LIBCXX=true -DLLVM_BUILD_32_BITS=true -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
+1. Clone LLVM to `<CppSharp>\deps\llvm`
 
-make
+```
+git clone http://llvm.org/git/llvm.git
 ```
 
-### Compiling using the build script
-
-Before building, ensure cmake is installed under Applications/Cmake.app and Ninja is installed in your PATH.
+2. Clone Clang to `<CppSharp>\deps\llvm\tools\clang`
 
-1. Navigate to `build/scripts`
-2. Clone, build and package LLVM with
 ```
-../premake5-osx --file=LLVM.lua clone_llvm
-../premake5-osx --file=LLVM.lua build_llvm
-../premake5-osx --file=LLVM.lua package_llvm
+cd llvm/tools
+git clone http://llvm.org/git/clang.git
 ```
 
-You can specify an `--arch=x86` or `--arch=x64` flag to the invocations above to specify an explicit build architecture.  
+Official LLVM instructions can be found here: [http://llvm.org/docs/GettingStarted.html#git-mirror]
+(http://llvm.org/docs/GettingStarted.html#git-mirror)
 
-If the clone_llvm step fails, you can try to manually clone LLVM and Clang as explained above. You should still run clone_llvm to ensure that you are on the correct revision.
+Make sure to use the revisions specified below, or you will most likely get compilation errors.
 
+Required LLVM/Clang commits:
 
-## Compiling on Linux
+[LLVM: see /build/LLVM-commit.](https://github.com/mono/CppSharp/tree/master/build/LLVM-commit)
+[Clang: see /build/Clang-commit.](https://github.com/mono/CppSharp/tree/master/build/Clang-commit)
 
-If you do not have native build tools you can install them first with:
+To change to the revisions specified above you can run the following commands:
 
-```shell
-sudo apt-get install cmake ninja-build build-essential
+```
+git -C deps/llvm reset --hard <llvm-rev>
+git -C deps/llvm/tools/clang reset --hard <clang-rev>
 ```
 
-And then build LLVM with:
-
-```shell
-cd deps/llvm/build
 
-cmake -G Ninja -DCLANG_BUILD_EXAMPLES=false -DCLANG_INCLUDE_DOCS=false -DCLANG_INCLUDE_TESTS=false -DCLANG_INCLUDE_DOCS=false -DCLANG_BUILD_EXAMPLES=false -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_INCLUDE_EXAMPLES=false -DLLVM_INCLUDE_DOCS=false -DLLVM_INCLUDE_TESTS=false ..
 
-ninja
-```

docs/GettingStarted.md

@@ -36,7 +36,8 @@ premake5-osx --file=scripts/LLVM.lua download_llvm # on OSX
 premake5-linux-64 --file=scripts/LLVM.lua download_llvm # on Linux
 ```
 
-Alternatively, if on Windows, just double click on `<CppSharp>/build/DownloadDeps.bat`.
+Alternatively, if on Windows, just run `<CppSharp>/build/DownloadDeps.bat` from a Visual Studio command prompt
+corresponding to the VS version you want to use.
 
 After this, you should end up with one or multiple `<CppSharp>/build/scripts/llvm-<revision>-<os>-<configuration>` folders
 containing the headers and libraries for LLVM.
@@ -50,64 +51,66 @@ Please check the guide in [Compiling LLVM and Clang from source](BuildingLLVM.md
 
 ## Compiling on Windows/Visual Studio
 
+1. Generate the VS solution and project files 
+
 ```shell
 cd <CppSharp>\build
-
 GenerateProjects.bat
-msbuild vs2013\CppSharp.sln /p:Configuration=Release;Platform=x86
 ```
 
-Building in *Release* is recommended because else the Clang parser will be
-excruciatingly slow.
+2. Compile the project
 
-It has been reported that running the solution upgrade process under VS 2013 breaks the build due
-to an incompatibility of .NET versions between projects (4.5 and 4.0). If you experience this
-problem you can change the targetted .NET version of the projects to be the same or just do not
-run the upgrade process after generation. 
+You can open `CppSharp.sln` and hit F5 or compile via the command line:
 
-## Compiling on Mac OS X
+```
+msbuild vs2017\CppSharp.sln /p:Configuration=Release;Platform=x86
+```
 
-1. Run `./premake5-osx gmake` in `<CppSharp>\build`
-2. Build the generated makefiles:
-    - 32-bit builds: `config=release_x86 make -C gmake`
-    - 64-bit builds: `config=release_x64 make -C gmake`
+Building in *Release* is recommended because else we will use the Clang parser
+debug configuration, which will be too slow for practical use beyond debugging.
 
-The version you compile needs to match the version of the Mono VM installed on your 
-system which you can find by running `mono --version`. The reason for this is because
-a 32-bit VM will only be able to load 32-bit shared libraries and vice-versa for 64-bits.
+## Compiling on macOS or Linux
 
-## Compiling on Linux
+1. Change directory to `<CppSharp>\build`
+2. Run `./Compile.sh` to generate the project files and compile the code.
 
-Only 64-bits builds are supported at the moment. 
+If the above script fails, you can try these equivalent manual steps:
 
-We depend on a somewhat recent version of Mono (.NET 4.5).
-Ubuntu 14.04 contains recent enough Mono by default, which you can install with:
+1. Generate the Makefiles
 
-```shell
-sudo apt-get install mono-devel
+```
+./premake5-osx gmake # if on OSX
+./premake5-linux-64 gmake # if on Linux
 ```
 
-If you are using another distribution then please look into the [download page](http://www.mono-project.com/download/#download-lin) on the Mono website.
-
-Generate the makefiles, and build CppSharp:
+2. Build the generated makefiles:
+    - 32-bit builds: `make -C gmake config=release_x86`
+    - 64-bit builds: `make -C gmake config=release_x64`
 
-```shell
-cd <CppSharp>/build
-./premake5-linux-64 gmake
-make -C gmake config=release_x64
-```
+The version you compile needs to match the version of the Mono VM installed on your 
+system which you can find by running `mono --version`. The reason for this is because
+a 32-bit VM will only be able to load 32-bit shared libraries and vice-versa for 64-bits.
 
 If you need more verbosity from the builds invoke `make` as:
 
 ```shell
-verbose=true make -C gmake config=release_x64
+make -C gmake config=release_x64 verbose=true
 ```
 
-If you get the following error, please see [issue #625](https://github.com/mono/CppSharp/issues/625#issuecomment-189283549):
+## Running the testsuite
 
-```
-/usr/include/wchar.h(39,11): fatal: 'stdarg.h' file not found CppSharp has encountered an error while parsing code.
-```
+1. Change directory to `<CppSharp>\build`
+2. Run `./InstallNugets.sh` to install the NUnit test runner from Nuget.
+3. Run `./RunTests.sh` to run the tests.
+
+## Linux notes
+
+Only 64-bits builds are supported. 
+
+We depend on a recent version of Mono.
+
+Please look into the [download page](http://www.mono-project.com/download/#download-lin) on the
+Mono website for official install instructions.
 
 # Generating bindings