OSX Build/glslang premake fix (#1641)

* #include an absolute path didn't work - because paths were taken to always be relative.

* Improve docs.
Fix premake build of glslang.

* More improvements to the building.md doc.

1 files changed, 48 insertions, 16 deletions

diff --git a/docs/building.md b/docs/building.md
index 316a48e75..5e1658c14 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -4,7 +4,9 @@
 
 Clone [this](https://github.com/shader-slang/slang) repository, and then run:
 
-    git submodule update --init
+```
+% git submodule update --init
+```
 
 The submodule update step is required to pull in dependencies used for testing infrastructure as well as the `glslang` compiler that we currently use for generating SPIR-V. 
 
@@ -25,25 +27,55 @@ Some targets below are described as 'unofficial'. In practice this means that th
 
 ### Generated Files
 
-Slang as part of it's build process generates header files, which are then used to compile the main Slang project. If you use `premake` to create your project, it will automatically generate these files before compiling the rest of the Slang. These are the current header generations which are created via the `slang-generate` tool... 
+Slang as part of it's build process generates header files, which are then used to compile the main Slang project. If you use `premake` to create your project, it will automatically generate these files before compiling the rest of the Slang. These are the current header generations which are created via the `slang-generate` and other tools... 
 
 * core.meta.slang -> core.meta.slang.h
 * hlsl.meta.slang -> hlsl.meta.slang.h 
 
+Other files that are generated have `generated` as part of their name.
+
 It may be necessary or desirable to create a build of Slang without using `premake`. 
 
 One way to do this would be to first compile slang-generate and then invoke it directly or as a dependency in your build. Another perhaps simpler way would be to first compile the same Slang source on another system that does support `premake`, or using a preexisting build mechanism (such as Visual Studio projects on Windows). Then copy the generated header files to your target system. This is appropriate because the generated files are indentical across platforms. It does of course mean that if `core.meta.slang` or `hlsl.meta.slang` files change the headers will need to be regenerated. 
 
 ## Premake
 
-Slang uses the tool [`premake5`](https://premake.github.io/) in order to generate projects that can be built on different targets. On Linux premake will generate Makefile/s and on windows it will generate a Visual Studio solution. Information on invoking premake for different kinds of targets can be found [here](https://github.com/premake/premake-core/wiki/Using-Premake). You can also run with `--help` to see available command line options
+Slang uses the tool [`premake5`](https://premake.github.io/) in order to generate projects that can be built on different targets. On Linux premake will generate Makefile/s and on windows it will generate a Visual Studio solution. Information on invoking premake for different kinds of targets can be found [here](https://github.com/premake/premake-core/wiki/Using-Premake). 
+
+Slang includes `premake5` as part of `slang-binaries` which is in the `external` directory. For the external directory to be setup it is necessary to have updated submodules with `git submodule update --init`. 
+
+If you are on a unix-like operating system such as OSX/Linux, it may be necesary to make premake5 executable. Use 
 
 ```
+% chmod u+x external/slang-binaries/premake/***path to premake version and os***/premake5
+```
+
+Alternatively you can download and install [`premake5`](https://premake.github.io/) on your build system. 
+
+You can run `premake5` with `--help` to see available command line options (assuming premake5 is in your `PATH`):
+ 
+```
 % premake5 --help
 ```
 
+For Unix like targets that might have `clang` or `gcc` compilers available you can select which one via the `-cc` option. For example...
+
+```
+% premake5 gmake --cc=clang
+```
+
+or 
+
+```
+% premake5 gmake --cc=clang
+```
+
+If you want to build the [`glslang`](https://github.com/KhronosGroup/glslang) library that Slang uses, add the option `--build-glslang=true`.
+
 # Projects using `make`
 
+The Slang project does not include Makefiles by default - they need to be generated via `premake`. Please read the section on your target operating system on how to use `premake` to create Makefiles. 
+
 If building a Makefile based project, for example on Linux, OSX or [Cygwin](https://cygwin.com/), the configuration needs to be specified when invoking make, the following are typical...
 
 ```
@@ -81,16 +113,12 @@ These should create a slang.sln in the same directory and which you can then ope
 
 ### Linux 
 
-First download and install [`premake5`](https://premake.github.io/) on your build system. In the terminal go to the root directory of the slang source tree (ie the directory containing `slang.h`). Assuming premake5 is in your `PATH` use  
+On Linux we need to generate Makefiles using `premake`. Please read the `premake` section for more details. 
 
-```
-% premake5 gmake 
-```
- 
-You can vary the compiler to use via the --cc option with 'gcc' or 'clang' for example
+In the terminal go to the root directory of the slang source tree (ie the directory containing `slang.h`). Assuming `premake5` is in your `PATH` use  
 
 ```
-% premake5 gmake --cc=clang
+% premake5 gmake 
 ```
 
 To create a release build use
@@ -98,20 +126,26 @@ To create a release build use
 ```
 % make config=release_x64
 ```
+ 
+You can vary the compiler to use via the --cc option with 'gcc' or 'clang' for example
 
 ### Mac OSX
 
 Note that OSX isn't an official target. 
 
-First download and install [`premake5`](https://premake.github.io/) on your build system. Open up a command line and go to the root directory of the slang source tree (ie the directory containing `slang.h`).
- 
-Assuming premake5 is in your `PATH`, you can create a `Makefile` to build slang and tests components with
+On Mac OSX to generate Makefiles or an XCode project we use `premake`. Please read the `premake` section for more details. 
 
 ```
 % premake5 gmake 
 ```
 
-To build with
+If you want to build `glslang` (necessary for Slang to output SPIR-V for example), then the additional `--build-glslang` option should be used
+
+```
+% premake5 gmake --build-glslang=true
+```
+
+To build for release you can use...
 
 ```
 % make config=release_x64
@@ -135,8 +169,6 @@ One issue with building on [Cygwin](https://cygwin.com/), is that there isn't a
 % premake5 --target-detail=cygwin gmake
 ```
 
-If you want to specify the toolset use `--cc=gcc` or `--cc=clang` on the command line. 
-
 ## Testing
 
 When slang is built from source it also builds tools to be able to test the Slang compiler. Testing is achieved using the `slang-test` tool. The binaries are placed in the appropriate directory underneath `bin`. It is important that you initiate the test binary from the root directory of the slang source tree, such that all tests can be correctly located.