SPIRV-Tools/test/diff/diff_files/README.md

# Diff tests

This directory contains files used to ensure correctness of the `spirv-diff` implementation.  The
`generate_tests.py` script takes `name_src.spvasm` and `name_dst.spvasm` (for each `name`) and
produces unit test files in the form of `name_autogen.cpp`.

The unit test files test the diff between the src and dst inputs, as well as between debug-stripped
versions of those.  Additionally, based on the `{variant}_TESTS` lists defined in
`generate_tests.py`, extra unit tests are added to exercise different options of spirv-diff.

New tests are added simply by placing a new `name_src.spvasm` and `name_dst.spvasm` pair in this
directory and running `generate_tests.py`.  Note that this script needs the path to the spirv-diff
executable that is built.

The `generate_tests.py` script additionally expects `name_src.spvasm` to include a heading where the
purpose of the test is explained.  This heading is parsed as a block of lines starting with `;;` at
the top of the file.
Introduce spirv-diff (#4611) spirv-diff is a new tool that produces diff-style output comparing two SPIR-V modules. The instructions between the src and dst modules are matched as best as the tool can, and output is produced (in src id-space) that shows which instructions are removed in src, added in dst or modified between them. The order of instructions are not retained. Matching instructions between two SPIR-V modules is not trivial, and thus a number of heuristics are applied in this tool. In particular, without debug information, it's hard to match functions as they can be reordered. As such, this tool is primarily useful to produce the diff of two SPIR-V modules derived from the same source. This tool can be useful in a number of scenarios: - Compare the SPIR-V before and after modifying a shader - Compare the SPIR-V produced from a shader before and after compiler codegen changes. - Compare the SPIR-V produced from a shader before and after some transformation or optimization. - Compare the SPIR-V produced from a shader with different compilers. 2022-02-02 15:33:18 +00:00			`# Diff tests`

			This directory contains files used to ensure correctness of the `spirv-diff` implementation. The
			`generate_tests.py` script takes `name_src.spvasm` and `name_dst.spvasm` (for each `name`) and
			produces unit test files in the form of `name_autogen.cpp`.

			`The unit test files test the diff between the src and dst inputs, as well as between debug-stripped`
			versions of those. Additionally, based on the `{variant}_TESTS` lists defined in
			`generate_tests.py`, extra unit tests are added to exercise different options of spirv-diff.

			New tests are added simply by placing a new `name_src.spvasm` and `name_dst.spvasm` pair in this
			directory and running `generate_tests.py`. Note that this script needs the path to the spirv-diff
			`executable that is built.`

			The `generate_tests.py` script additionally expects `name_src.spvasm` to include a heading where the
			purpose of the test is explained. This heading is parsed as a block of lines starting with `;;` at
			`the top of the file.`