Specify downstream compiler include paths (#2517)

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

* WIP around testing with NVAPI.

* Make -I work for downstream compilers.
Update docs.

* Small improvement around ignoring tests.

2 files changed, 20 insertions, 5 deletions

diff --git a/docs/command-line-slangc.md b/docs/command-line-slangc.md
index 22266a139..2947c8184 100644
--- a/docs/command-line-slangc.md
+++ b/docs/command-line-slangc.md
@@ -151,6 +151,7 @@ For completeness, here are the options that `slangc` currently accepts:
 
 * -Xname to specify arguments to downstream tool `name` (covered in more detail in "Downstream Arguments")
 
+<a id="downstream-arguments"></a>
 ### Downstream Arguments
 
 During a Slang compilation work may be performed by multiple other stages including downstream compilers and linkers. It isn't possible in general or perhaps even desirable to provide Slang command line equivalents of every option available at every stage of compilation. It is useful to be able to set options specific to a particular compilation stage - to alter code generation, linkage and other options.
@@ -234,6 +235,16 @@ Means that the dxc compilation in the render test (assuming dxc is invoked) will
 -Gfa
 ```
 
+Some options are made available via the same mechanism for all downstream compilers. 
+
+* Use `-I` to specify include path for downstream compilers
+
+For example to specify an include path "somePath" to DXC you can use...
+
+```
+-Xdxc -IsomePath
+```
+
 ### Specifying where dlls/shared libraries are loaded from
 
 On windows if you want a dll loaded from a specific path, the path must be specified absolutely. See the [LoadLibrary documentation](https://docs.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibrarya) for more details. A relative path will cause Windows to check all locations along it's search procedure.
diff --git a/docs/nvapi-support.md b/docs/nvapi-support.md
index 58f73634e..ac3a2e943 100644
--- a/docs/nvapi-support.md
+++ b/docs/nvapi-support.md
@@ -63,19 +63,23 @@ The astute reader may have noticed that the default Slang HLSL prelude *does* co
 #endif
 ```
 
-This means that the *downstream* compiler (such as DXC and FXC) must be able to handle this include. 
+This means that the *downstream* compiler (such as DXC and FXC) must be able to handle this include. Include paths can be specified for downstream compilers via the [-X mechanism](command-line-slangc.md#downstream-arguments). So for example...
 
-As it turns out all the includes specified to Slang (via command line -I or through the API), are passed down to the include handlers for FXC and DXC. 
+```
+-Xfxc -IpathTo/nvapi -Xdxc -IpathTo/nvapi
+```
 
-In the simplest use case where the path to `nvHLSLExtns.h` is specified in the include paths everything should 'just work' - as both Slang and the downstream compilers will see these include paths and so can handle the include. 
+In the explicit scenario where `nvHLSLExtns.h` is included in Slang source, the include path must be specified in Slang through the regular mechanisms. 
 
-Things are more complicated if there is mixed implicit/explicit NVAPI usage and in the Slang source the include path is set up such that NVAPI is included with 
+In a scenario with both implicit and explicit use, both Slang *and* the downstream compiler need to have a suitable path specified. Things can be more complicated if there is mixed implicit/explicit NVAPI usage and in the Slang source the include path is set up such that NVAPI is included with 
 
 ```
 #include "nvapi/nvHLSLExtns.h"
 ```
 
-This won't work directly with the implicit usage, as the downstream compiler includes as `"nvHLSLExtns.h"`. One way to work around this by altering the HLSL prelude such as the same `#include` is used. 
+Since Slang and the downstream compilers can specify different include paths, the downstream compiler include path can be such that `#include "nvHLSLExtns.h"` works with the default prelude.
+
+Another way of working around this issue is to alter the prelude for downstream compilers such that it contains an absolute path for the `#include`. This is the mechanism that is currently used with the Slang test infrastructure. 
 
 Links
 -----