diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/command-line-slangc.md | 49 |
1 files changed, 40 insertions, 9 deletions
diff --git a/docs/command-line-slangc.md b/docs/command-line-slangc.md index 9eaf2343a..5d4119db7 100644 --- a/docs/command-line-slangc.md +++ b/docs/command-line-slangc.md @@ -161,7 +161,7 @@ The mechanism used here is based on the `-X` mechanism used in GCC, to specify a -Xlinker option ``` -When used, option is not interpreted by GCC, but is passed to the linker once compilation is complete. Slang extends this idea in several ways. First there are many more 'downstream' stages available to Slang. These different stages are known as `SlangPassThrough` types in the API and have the following names +When used, `option` is not interpreted by GCC, but is passed to the linker once compilation is complete. Slang extends this idea in several ways. First there are many more 'downstream' stages available to Slang than just `linker`. These different stages are known as `SlangPassThrough` types in the API and have the following names * `fxc` - FXC HLSL compiler * `dxc` - DXC HLSL compiler @@ -172,13 +172,13 @@ When used, option is not interpreted by GCC, but is passed to the linker once co * `genericcpp` - A generic C++ compiler (can be any one of visual studio, clang or gcc depending on system and availability) * `nvrtc` - NVRTC CUDA compiler -The Slang command line allows you to specify an argument to these downstream compilers, by using their name after the -X. So for example to send an option `-Gfa` through to DXC you can use +The Slang command line allows you to specify an argument to these downstream compilers, by using their name after the `-X`. So for example to send an option `-Gfa` through to DXC you can use ``` -Xdxc -Gfa ``` -Note that if an option is available via normal Slang command line options then these should be used. This will work on multiple targets, but also avoids options clashing. As it stands Slang does not determine if a command line setting using the `-X` option clashes with regular Slang options in any way. This mechanism is best used for options that are unavailable through normal Slang mechanisms. +Note that if an option is available via normal Slang command line options then these should be used. This will generally work across multiple targets, but also avoids options clashing which is undefined behavior currently. The `-X` mechanism is best used for options that are unavailable through normal Slang mechanisms. If you want to pass multiple options using this mechanism the `-Xdxc` needs to be in front of every options. For example @@ -186,30 +186,53 @@ If you want to pass multiple options using this mechanism the `-Xdxc` needs to b -Xdxc -Gfa -Xdxc -Vd ``` +Would reach `dxc` as + +``` +-Gfa -Vd +``` + This can get a little repetitive especially if there are many parameters, so Slang adds a mechanism to have multiple options passed by using an ellipsis `...`. The syntax is as follows ``` -Xdxc... -Gfa -Vd -X. ``` -The `...` at the end indicates all the following parameters should be sent to DXC until it reaches the terminating `-X` or the end of the command line. +The `...` at the end indicates all the following parameters should be sent to `dxc` until it reaches the matching terminating `-X.` or the end of the command line. It is also worth noting that `-X...` options can be nested. This would allow a GCC downstream compilation to control linking, for example with ``` --Xgcc -Xlinker --split -X +-Xgcc -Xlinker --split -X. +``` + +In this example gcc would see + +``` +-Xlinker --split +``` + +And the linker would see (as passed through by gcc) + +``` +--split ``` Setting options for tools that aren't used in a Slang compilation has no effect. This allows for setting `-X` options specific for all downstream tools on a command line, and they are only used as part of a compilation that needs them. -NOTE! Not all tools that Slang uses downstream make command line argument parsing available. Of note `FXC` and `GLSLANG` currently do not have any command line argument passing as part of their integration. +NOTE! Not all tools that Slang uses downstream make command line argument parsing available. `FXC` and `GLSLANG` currently do not have any command line argument passing as part of their integration, although this could change in the future. -The `-X` mechanism is also supported by render-test tool. In this usage `slang` becomes a downstream tool. Thus you can use the DXC option `-Gfa` in a render-test via +The `-X` mechanism is also supported by render-test tool. In this usage `slang` becomes a downstream tool. Thus you can use the `dxc` option `-Gfa` in a render-test via ``` -Xslang... -Xdxc -Gfa -X. ``` +Means that the dxc compilation in the render test (assuming dxc is invoked) will receive + +``` +-Gfa +``` ### Specifying where dlls/shared libraries are loaded from @@ -217,11 +240,19 @@ On windows if you want a dll loaded from a specific path, the path must be speci On linux it's similar, but any path (relative or not) will override the regular search mechanism. See *'dlopen'* for more details. -* `-dxc-path`: Sets the path where dxc dlls are loaded from (dxcompiler.dll & dxil). +* `-dxc-path`: Sets the path where dxc dll/shared libraries are loaded from (dxcompiler & dxil). * `-fxc-path`: Sets the path where fxc dll is loaded from (d3dcompiler_47.dll). -* `-glslang-path`: Sets where the slang specific 'slang-glslang' is loaded from +* `-glslang-path`: Sets where the Slang specific 'slang-glslang' is loaded from + +Paths can specify a directory that holds the appropriate binaries. It can also be used to name a specific downstream binary - be it a shared library or an executable. Note that if it is a shared library, it is not necessary to provide the full filesystem name - just the path and/or name that will be used to load it. For example on windows `fxc` can be loaded from `D:/mydlls` with + +* `D:/mydlls' - will look for `d3dcompiler_47.dll` in this directory +* `D:/mydlls/d3dcompiler_47` - it's not necessary to specify .dll to load a dll on windows +* `D:/mydlls/d3dcompiler_47.dll` - it is also possible name the shared library explicitly for example + +That if you name the shared library/executable you can use a name other than the default for a specific version, for example by using `D:/mydlls/dxcompiler-some-version` for a specific version of `dxc`. Limitations ----------- |