glslc/README.asciidoc - third_party/shaderc - Git at Google

 = glslc Manual

 :numbered:
 :source-highlighter: pygments

 == Name

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

 == Synopsis

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

 == Description

 === Shader stage specification

 glslc provides three ways to specify the shader stage of an input shader 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.

 [[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.

 ==== `-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 inputs passed to `glslc`.
 * `-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. Right now, the
 only accepted argument 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.

 ==== `-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.

 ==== `-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.

 ==== 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`

 `-I` adds the specified directory to the search path for include files.

 Only `""` style includes are permitted. When searching for included files, first
 the directory of the current file is attempted. If this fails each directory
 supplied via `-I` on the command line is searched in the given order for the
 file.

 === Code Generation Options

 ==== `-g`

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

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

 === 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.

 TODO: Expected behaviors of the `#include` directive.

 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.

 It is invalid to have any '\' or '/' characters in any filename provided to
 an `#include` directive. The presence of any such characters may lead to
 unexpected behavior on different systems.

 Furthermore it is not possible to escape any characters in an `#include`
 directive and as such, any special characters that would have to be escaped in
 C may not show up in file names either.
	= glslc Manual

	:numbered:
	:source-highlighter: pygments

	== Name

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

	== Synopsis

	----
	glslc [-c\|-S\|-E]
	[-Dmacroname[=value]...]
	[-std=standard] [-x glsl]
	[-fshader-stage=...]
	[--target-env=...]
	[-g]
	[-w] [-Werror]
	[-o outfile] shader...
	----

	== Description

	=== Shader stage specification

	glslc provides three ways to specify the shader stage of an input shader 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.

	[[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.

	==== `-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 inputs passed to `glslc`.
	* `-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. Right now, the
	only accepted argument 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.

	==== `-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.

	==== `-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.

	==== 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`

	`-I` adds the specified directory to the search path for include files.

	Only `""` style includes are permitted. When searching for included files, first
	the directory of the current file is attempted. If this fails each directory
	supplied via `-I` on the command line is searched in the given order for the
	file.

	=== Code Generation Options

	==== `-g`

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

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

	=== 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.

	TODO: Expected behaviors of the `#include` directive.

	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.

	It is invalid to have any '\' or '/' characters in any filename provided to
	an `#include` directive. The presence of any such characters may lead to
	unexpected behavior on different systems.

	Furthermore it is not possible to escape any characters in an `#include`
	directive and as such, any special characters that would have to be escaped in
	C may not show up in file names either.