glslc/README.asciidoc

= glslc Manual

:numbered:
:source-highlighter: pygments

== Name

`glslc` - A command-line GLSL/HLSL to SPIR-V compiler with
Clang-compatible arguments.

== Synopsis

----
glslc [-c|-S|-E]
      [-x ...] [-std=standard]
      [-fshader-stage=...]
      [-fentry-point=...]
      [--target-env=...]
      [-g]
      [-O0|-Os]
      [-Idirectory...]
      [-Dmacroname[=value]...]
      [-w] [-Werror]
      [-o outfile]
      shader...
----

== Description

=== Input file languages

glslc accepts both GLSL/HLSL source and SPIR-V assembly files as inputs.

==== Shader stage specification

glslc provides three ways to specify the shader stage of a GLSL source file:
`-fshader-stage=<stage>`, `#pragma shader_stage(<stage>)`, and file extension.
The `-fshader-stage=` option overrides `#pragma shader_stage()`, which overrides
the file extension.

Shader stages can be specified by naming a file with an appropriate extension
as shown in the following table. `-fshader-stage=` and `#pragma shader_stage()`,
on the other hand, enable you to specify shader stages from the command line
and within the source file. Possible ``stage``s for them are also listed in
the following table. Details about `-fshader-stage=` can be found in
<<option-f-shader-stage,its own section>>.

[[shader-stage-selection]]
.Shader Stage Selection
|===
|Shader Stage |Shader File Extension |`<stage>`

|vertex                 |`.vert` |`vertex`
|fragment               |`.frag` |`fragment`
|tesselation control    |`.tesc` |`tesscontrol`
|tesselation evaluation |`.tese` |`tesseval`
|geometry               |`.geom` |`geometry`
|compute                |`.comp` |`compute`
|===

`#pragma shader_stage()` relies on the `#pragma` preprocessor directive; thus,
the token inside `shader_stage()` is not subject to preprocessor macro
expansion. It must be exactly one of the ``stage``s in the above table.

`#pragma shader_stage()` behaves as follows:

* The first `#pragma shader_stage()` directive in a translation unit must
  precede any non-preprocessor tokens.
* If there is more than one `#pragma shader_stage()` directive in the same
  translation unit, all the ``stage``s specified must be the same. Otherwise,
  glslc will issue an error.

==== SPIR-V assembly files

SPIR-V assembly input files should follow the
https://github.com/KhronosGroup/SPIRV-Tools/blob/master/syntax.md[syntax]
defined in the https://github.com/KhronosGroup/SPIRV-Tools[SPIRV-Tools]
project and have the `.spvasm` extension. Command line options treat SPIR-V
assembly files differently; some may ignore them, e.g., `<<option-cap-e,-E>>`,
`<<option-cap-s,-S>>`, and some may even treat them not as SPIR-V assembly
files, e.g., `<<shader-stage-with-spirv-assembly,-fshader-stage\=>>`.

[[output-file-naming]]
=== Output file naming

If a name is specified via `-o`, the output file will be given that name.
Otherwise,

* If a compilation stage selection option is given (`-S` or `-c`), there will
  be one output file generated per input shader file. The generated output file
  will end with a file extension that matches the compilation stage, which is
  `.spvasm` for `-S` and `.spv` for `-c`. The name will depend on the original
  file's name and extension.
** If the input file has a <<shader-stage-selection,shader stage selection
   extension>>, the output file will be named as by appending the file extension
   for the compilation stage to the input file's name. E.g., `glslc -c foo.vert`
   will generate `foo.vert.spv`, and `glslc -s bar.frag` will generate
   `bar.frag.spvasm`.
** Otherwise, the output file will be named as by replacing the input file's
   file extension, if any, with the file extension for the compilation stage.
   E.g., `glslc -c foo` will generate `foo.spv`, and `glslc -s bar.glsl` will
   generate `bar.spvasm`.
* If no compilation stage is selected, the output file will be named `a.spv`.

== Command Line Options

=== Overall Options

==== `--help`

`--help` tells the glslc compiler to display all available options and exit.

==== `-o`

`-o` lets you specify the output file's name. It cannot be used when there are
multiple files generated. A filename of `-` represents standard output.

=== Language and Mode Selection Options

[[option-f-shader-stage]]
==== `-fshader-stage=`

`-fshader-stage=<stage>` lets you specify the shader stage for one or more
inputs from the command line.

Possible values for ``<stage>`` are listed in the <<shader-stage-selection,
Shader Stage Selection>> table.

`-fshader-stage=` behaves as follows:

* `-fshader-stage=` sets the shader stage for subsequent input files. It does
  not affect the stages of any preceding inputs on the command line.
* When supplying more than one `-fshader-stage=` argument, the most recent
  argument preceding an input file applies.
* A shader file not ending with <<shader-stage-selection,known shader file
  extensions>> must have a `-fshader-stage=` argument ahead of it to specify
  its stage.
* If there is a `-fshader-stage=` before a file in which there is a `#pragma
  shader_stage()` directive, the directive is ignored and the `-fshader-stage=`
  argument is used instead.
* If there is a `-fshader-stage=` before a file with a known shader file
  extension, the file extension is ignored and the `-fshader-stage=` argument
  is used instead.

[[shader-stage-with-spirv-assembly]]
CAUTION: `-fshader-stage=` overrides file extension; that means it should not
be used together with SPIR-V assembly files because glslc will treat the given
SPIR-V assembly files as GLSL source code of the given shader stage. If you
need to supply both SPIR-V assembly files and `-fshader-stage=` on the same
command line, please put SPIR-V assembly files ahead of the first
`-fshader-stage=`, since `-fshader-stage=` only affects the treatment of
subsequent files.

[[option-f-entry-point]]
==== `-fentry-point=`

`-fentry-point=<name>` lets you specify the entry point name.  This is only
significant for HLSL compilation.  The default is "main".

==== `-std=`

`-std=<value>` lets you specify a shader version and profile on the command
line. ``<value>`` can be any valid concatenation of a GLSL version number and
profile, e.g., `310es`, `450core`, etc. The profile can be omitted as allowed by
GLSL, e.g., `450`.

`-std=` behaves as follows:

* `-std=` affects the version of all GLSL inputs passed to `glslc`.
* `-std=` is ignored for HLSL inputs.
* `-std=` overwrites `#version` directives in all input shaders, including those
  preceding the argument.
* If a `-std=` argument specifies a different version from a `#version`
  directive in an input file, `glslc` will issue a warning.
* If multiple `-std=` arguments are specified on the command line, only the last
  one takes effect.

CAUTION: `-std=` does not affect the `#version` directive in the preprocessed
output. That is, when `-std=` specifies a version different from the shader
source code, the `#version` directive in preprocessed output will still be the
one in the source code. But `-std=` does affect the behavior of `#line`
directives in the preprocessed output. Behavior of `#line` directives will
follow the version specified by `-std=`.

==== `--target-env=`

`--target-env=<value>` lets you specify a target environment on the command line.
This affects the generation of warnings and errors. ``<value>`` can be one of
the following:

* `vulkan`: create SPIR-V under Vulkan semantics.
* `opengl`: create SPIR-V under OpenGL semantics.
* `opengl_compat`: create SPIR-V under OpenGL semantics, including compatibility
  profile functions.

By default, the ``<value>`` is set to `vulkan` and the compiler creates SPIR-V
under Vulkan semantics.

==== `-x`

`-x` lets you specify the language of the input shader files. Valid languages
are `glsl` and `hlsl`.  If the file extension is `hlsl` then the default language
is HLSL.  Otherwise the default is 'glsl'.

[[compilation-stage-selection-options]]
=== Compilation Stage Selection Options

==== `-c`

`-c` tells the glslc compiler to run the preprocessing and compiling stage.
Each input shader file results in a SPIR-V binary file; these SPIR-V binary
files are named by the rules in the <<output-file-naming,Output File Naming>>
section.

[[option-cap-e]]
==== `-E`

`-E` tells the glslc compiler to run only the preprocessing stage. It overrides
`-c` and `-S`. Preprocessed output is written to standard output, while
preprocessing errors are written to standard error. If multiple input shader
files are given, their preprocessed output are all written to standard output,
in the order specified on the command line.

glslc will do nothing for SPIR-V assembly files with this option.

[[option-cap-s]]
==== `-S`

`-S` tells the glslc compiler to run the preprocessing, compiling, and then
disassembling stage. It overrides `-c`. Each input shader file results in a
SPIR-V assembly file; these SPIR-V assembly files are named by the rules in the
<<output-file-naming,Output File Naming>> section.

glslc will do nothing for SPIR-V assembly files with this option.

==== No Compilation Stage Selection

If none of the above options is given, the glslc compiler will run
preprocessing, compiling, and linking stages.

WARNING: Linking of multiple input shader files are not supported yet.

=== Preprocessor Options

==== `-D`

`-Dmacroname[=[value]]` lets you define a preprocessor macro before input shader
files are preprocessed. If `value` is omitted, the macro is defined with an
empty value.

==== `-I`

`-Idirectory` or `-I directory` adds the specified directory to the search path
for include files.  The directory may be an absolute path or a relative path to
the current working directory.

=== Code Generation Options

==== `-g`

Requests that the compiler place source-level debug information into the object
code, such as identifier names and line numbers.

This option restrains `-O` from turning on the strip-debug-info optimization
pass.

NOTE: Currently this option has no effect.  Full functionality depends on
glslang support for generating debug info.

==== `-O0`, `-Os`

`-O` specifies which optimization level to use:

* `-O0` means "no optimization". This level generates the most debuggable code.
* `-Os` enables optimizations to reduce code size.

==== `-mfmt=<format>`

`-mfmt=<format>` selects output format for compilation output in SPIR-V binary
code form.  Supported options are listed in the
<<binary-output-format-options,binary output format options>> table. This
option is only valid to be used when the compilation output is SPIR-V binary
code. Specifying any options listed below when the output is not SPIR-V binary
code, like disassembly (with `-S` specified), text (with `-M`, `-MM` or `-E`
specified) will trigger an error.

[[binary-output-format-options]]
.Binary Output Format Options
[cols="20%,80%"]
|===
|Format option  |Description

|bin            |Output SPIR-V binary code as a sequence of binary 32-bitwords
                 in host native endianness. This is the default format for
                 SPIR-V binary compilation output.
|num            |Output SPIR-V binary code as a text file containing a list of
                 comma-separated hex numbers. +
                 Example: `glslc -c -mfmt=num main.vert -o output_file.txt` +
                 Content of the output_file.txt: +
                 0x07230203,0x00010000,0x00080001,0x00000006...
|c              |Output SPIR-V binary code as a text file containing C-style +
                 initializer list. +
                 This is just wrapping the output of `num` option with curly
                 brackets. +
                 Example: `glslc -c -mfmt=c main.vert -o output_file.txt` +
                 Content of output_file.txt: +
                 {0x07230203, 0x00010000, 0x00080001, 0x00000006...}
|===

=== Warning and Error Options

==== `-w`

`-w` suppresses all warning output from `glslc`. Any warning that would have
been generated is silently ignored.

==== `-Werror`

`-Werror` forces any warning to be treated as an error in `glslc`. This means
that all `warning:` messages are shown as `error:` and any warnings will cause
a non-zero exit code from `glslc`. If `-w` is specified the warnings
generated are suppressed before they are converted to errors.

=== Dependency Generation Options

==== `-M` or `-MM`

`-M` generates *make* dependencies. It outputs a rule suitable for *make*
describing the dependencies of the input file. Instead of outputting the result
of preprocessing, the preprocessor outputs one *make* rule containing the
SPIR-V object file name for that source file, a colon, and the names of all the
included files.

Unless specified explicitly (with `-MT`), the SPIR-V object file name in the
generated *make* rules follows the rules of  <<output-file-naming,Output File
Naming>> as in `-c` compilation stage.

Specifying `-M` implies `-E`, and suppresses warnings with an implicit `-w`.
By default the output will be written to stdout, unless `-MF` or `-o` is
specified.

The dependency info file name can be specified by `-o` and `-MF` options. When
both are specified, `-o` option is ignored.

Specifying multiple input files is valid when the *make* rules are written to
stdout, which means neither `-MF` nor `-o` is specified. When `-o` or `-MF` is
specified, only one input file is allowed.

`-MM` is an alias for `-M`.

E.g., `glslc -M main.vert` will dump `main.vert.spv: main.vert <other included
files>` to stdout. More examples are listed in
<<dependency-generation-examples,Dependency Generation Examples>>

==== `-MD`

`-MD` tells the glslc compiler to both compile the source and generate *make*
dependencies. Dependencies are written to a file whose name is determined as
follows: If option `-MF` is specified, use its argument. Otherwise, use the
filename formed by appending *.d* to the name of the file containing
compilation results.

Specifying multiple input files is valid when neither `-MF` nor `-o` is
specified. When `-o` or `-MF` is specified, only one input file is allowed.

E.g., `glslc -c -MD main.vert` will generate `main.vert.spv` as the SPIR-V
object file and `main.vert.spv.d` as the dependency info file. More examples
are listed in <<dependency-generation-examples,Dependency Generation Examples>>

==== `-MF`

`-MF` lets you specify the dependency info file name when used with `-M` or
`-MD`. This option is invalid when used with multiple input files.

E.g., `glslc -c -MD main.vert -MF dep_info` will generate `main.vert.spv` as
the SPIR-V object file and `dep_info` as the dependency info file.

==== `-MT`

`-MT` lets you specify the target of the rule emitted by dependency generation
when used with `-M` or `-MD`.  This option is invalid when used with multiple
input files.

E.g., `glslc -M main.vert -MT target` will dump following dependency info to
stdout: `target: main.vert <other dependent files>`.

[[dependency-generation-examples]]
.Dependency Generation Examples
|===
|Command Line Input|Compilation Output File|Dependency Output File|Dependency Info

|glslc -M main.vert             | <NA> | <Stdout> | main.vert.spv: main.vert
.2+|glslc -M a.vert b.vert         | <NA> | <Stdout> | a.vert.spv: a.vert
                                   | <NA> | <Stdout> | b.vert.spv: b.vert
|glslc -M main.vert -o dep_info | <NA> | dep_info | main.vert.spv: main.vert
|glslc -M main.vert -MF dep_info| <NA> | dep_info | main.vert.spv: main.vert
|glslc -M main.vert -MT target  | <NA> | <Stdout> | target: main.vert
|glslc -MD main.vert    |a.spv  |main.vert.spv.d|main.vert.spv: main.vert
|glslc -c -MD main.vert |main.vert.spv|main.vert.spv.d|main.vert.spv: main.vert
.2+|glslc -c -MD a.vert b.vert | a.vert.spv | a.vert.spv.d | a.vert.spv: a.vert
                               | b.vert.spv | b.vert.spv.d | b.vert.spv: b.vert
|glslc -S -MD main.vert |main.vert.spvasm  |main.vert.spvasm.d  |main.vert.spvasm: main.vert
|glslc -c -MD main.vert -MF dep_info  |main.vert.spv|dep_info|main.vert.spv: main.vert
|glslc -c -MD main.vert -o obj  |obj  |obj.d  |obj: main.vert
|glslc -c -MD main.vert -o obj -MF dep_info -MT target|obj|dep_info|target: main.vert
|===

== Divergence from and extensions to GLSL specifications

=== Source-filename-based `#line` and `\\__FILE__`

This section describes how the glslc compiler extends the syntax for the `#line`
directive and the `\\__FILE__` macro. By default, the glslc compiler enables
the `GL_GOOGLE_cpp_style_line_directive` extension. It will generate this
extended syntax in the preprocessed output (obtained via the `-E` option).

WARNING: This section is still evolving. Expect changes.

GLSL specifications have a notion of source strings.

[quote, Section 3.2 of both version 3.30 and 4.50]
____
The source for a single shader is an array of strings of characters from the
character set. A single shader is made from the concatenation of these strings.
____

With the above notion, the second parameter to the `#line` directive should
be a constant integer expressions representing the source string number. Also
the `\\__FILE__` macro will "substitute a decimal integer constant that says
which source string number is currently being processed."

The glslc compiler implements the standard `#line` and `\\__FILE__` syntax. It
also provides an extension, `GL_GOOGLE_cpp_style_line_directive`, to allow
source filenames to be used instead of integer source string indices.
Specifically, the `#line` directive can have, after macro substitution, one of
the following three forms:

[source,glsl]
----
#line line-number
#line line-number integer-source-string-index
#line line-number "source-filename"
----

where `source-filename` can be any combinations of characters except double
quotation marks. (Note that according to the GLSL specification, "there are
no escape sequences or other uses of the backslash beyond use as the
line-continuation character".)

And if source-filename-based `#line` is used, the `\\__FILE__` macro expands to
a string whose contents are the filename quoted with double quotation marks.
The filename is dertermined as the last of

* The filename given to the glslc compiler,
* The filename argument of the most recent `#line` directive, if any.

[[include-directive]]
=== `#include`

The glslc compiler extends GLSL with the include syntax by turning on the
`GL_GOOGLE_include_directive` extension. It will preprocess and substitute
`#include` directives properly with the following behaviors.

WARNING: This section is still evolving. Expect changes.

If `#include` directives are used in a shader, there will be an `#extension
GL_GOOGLE_include_directive : enable` line generated into the preprocessed
output.

The `GL_GOOGLE_cpp_style_line_directive` extension is implicitly turned on by
the `GL_GOOGLE_include_directive` extension.

The file argument to `#include` must be enclosed in double quotes.  It must be a
relative path, using whatever path separator the OS supports.  However, the last
path element -- the name of the file itself -- must not contain either '/' or
'\', regardless of which path separator is used.  This will not be flagged as an
error but will instead trigger undefined behavior.  For example, let's say there
is a file named `f\ilename.vert` on a Unix OS.  It is not possible to craft a
`#include` that includes that file.

Furthermore, it is not possible to escape any characters in a `#include`
directive, so the file argument cannot contain any special characters that need
escaping in C.

The file argument is a relative path that is matched first against the including
file's own directory and then against all `-I` arguments in order of their
appearance on the command line.  If the file cannot be found, `glslc` aborts
with an error.