### Installing DxrFallback Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/unittests/DxrFallback/CMakeLists.txt

Configures the installation of the test_DxrFallback executable. It will be placed in the 'bin' directory at runtime.

```cmake
install(TARGETS test_DxrFallback
  RUNTIME DESTINATION bin)
```

--------------------------------

### Install dxopt Target

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/dxopt/CMakeLists.txt

Installs the dxopt target, placing the executable in the 'bin' directory at runtime.

```cmake
install(TARGETS dxopt
  RUNTIME DESTINATION bin)

```

--------------------------------

### Basic YAML Configuration Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/ClangFormatStyleOptions.md

A simple example of a .clang-format file using YAML format to define key-value style options.

```yaml
key1: value1
key2: value2
# A comment.
...
```

--------------------------------

### Install clang-format Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/clang-format/CMakeLists.txt

Installs the clang-format executable to the bin directory.

```cmake
install(TARGETS clang-format RUNTIME DESTINATION bin)
```

--------------------------------

### LLC Help Output Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/WritingAnLLVMPass.rst

Example of how a registered custom register allocator appears in the 'llc -help' output.

```console
$ llc -help
  ...
  -regalloc                    - Register allocator to use (default=linearscan)
    =linearscan                -   linear scan register allocator
    =local                     -   local register allocator
    =simple                    -   simple register allocator
    =myregalloc                -   my register allocator help string
  ...

```

--------------------------------

### Install DXL Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/dxl/CMakeLists.txt

Installs the dxl executable to the bin directory.

```cmake
install(TARGETS dxl
  RUNTIME DESTINATION bin)
```

--------------------------------

### Install LLVM with Custom Prefix

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/CMake.rst

This snippet demonstrates how to install LLVM to a specific directory by invoking the 'cmake_install.cmake' script with a custom install prefix. This allows for installation to locations other than the default.

```console
$ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
```

--------------------------------

### Install dxr Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/dxr/CMakeLists.txt

Installs the dxr executable to the 'bin' directory at runtime.

```cmake
install(TARGETS dxr
  RUNTIME DESTINATION bin)

```

--------------------------------

### Installing the clang-check Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/clang-check/CMakeLists.txt

Installs the built clang-check executable to the 'bin' directory at runtime. This makes the tool available in the system's PATH after installation.

```cmake
install(TARGETS clang-check
  RUNTIME DESTINATION bin)
```

--------------------------------

### Install dxv Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/dxv/CMakeLists.txt

Installs the dxv executable to the 'bin' directory at runtime. This is part of the CMake installation rules.

```cmake
install(TARGETS dxv
  RUNTIME DESTINATION bin)
```

--------------------------------

### Install LLVM

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/CMake.rst

After LLVM has been built, use this command to install it. The '--target install' option tells CMake to build the 'install' target.

```console
$ cmake --build . --target install
```

--------------------------------

### Install Clang-C Headers

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/CMakeLists.txt

Installs the 'clang-c' header files to the installation's include directory, matching all '.h' files and excluding '.svn' directories.

```cmake
install(DIRECTORY include/clang-c
  DESTINATION include
  FILES_MATCHING
  PATTERN "*.h"
  PATTERN ".svn" EXCLUDE
  )
```

--------------------------------

### Installing dxc_batch Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/unittests/dxc_batch/CMakeLists.txt

Installs the dxc_batch target to the bin directory at runtime.

```cmake
install(TARGETS dxc_batch
  RUNTIME DESTINATION bin)

```

--------------------------------

### Install OCamldoc HTML Documentation

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/CMakeLists.txt

Installs the generated OCamldoc HTML documentation to the specified destination if LLVM_INSTALL_TOOLCHAIN_ONLY is not enabled.

```cmake
if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html
    DESTINATION docs/ocaml/html)
endif()
```

--------------------------------

### Install clang-format Scripts

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/clang-format/CMakeLists.txt

Installs various clang-format helper scripts to the share/clang directory.

```cmake
install(PROGRAMS clang-format-bbedit.applescript DESTINATION share/clang)
```

```cmake
install(PROGRAMS clang-format-diff.py DESTINATION share/clang)
```

```cmake
install(PROGRAMS clang-format-sublime.py DESTINATION share/clang)
```

```cmake
install(PROGRAMS clang-format.el DESTINATION share/clang)
```

```cmake
install(PROGRAMS clang-format.py DESTINATION share/clang)
```

```cmake
install(PROGRAMS git-clang-format DESTINATION bin)
```

--------------------------------

### Use-list Order Directives Examples

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Examples demonstrating the application of use-list order directives at function and global scopes, including reordering basic block use-lists.

```llvm
define void @foo(i32 %arg1, i32 %arg2) {
entry:
  ; ... instructions ...
bb:
  ; ... instructions ...

  ; At function scope.
  uselistorder i32 %arg1, { 1, 0, 2 }
  uselistorder label %bb, { 1, 0 }
}

; At global scope.
uselistorder i32* @global, { 1, 2, 0 }
uselistorder i32 7, { 1, 0 }
uselistorder i32 (i32) @bar, { 1, 0 }
uselistorder_bb @foo, %bb, { 5, 1, 3, 2, 0, 4 }
```

--------------------------------

### Install dxa Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/tools/dxa/CMakeLists.txt

Installs the dxa executable to the 'bin' directory at runtime. This command ensures the built executable is placed in the correct location for deployment.

```cmake
install(TARGETS dxa
  RUNTIME DESTINATION bin)

```

--------------------------------

### Visual Studio Style Formatting Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/ClangFormatStyleOptions.md

Example C++ code formatted according to the Visual Studio style configuration. Demonstrates indentation and brace placement.

```c++
void test()
{
    switch (suffix)
    {
    case 0:
    case 1:
        do_something();
        break;
    case 2:
        do_something_else();
        break;
    default:
        break;
    }
    if (condition)
        do_somthing_completely_different();

    if (x == y)
    {
        q();
    }
    else if (x > y)
    {
        w();
    }
    else
    {
        r();
    }
}
```

--------------------------------

### Installing CMake Build System

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/LibASTMatchersTutorial.md

Downloads, builds, and installs the CMake build system from its Git repository. This ensures a recent version with Ninja support is available.

```console
cd ~/clang-llvm
git clone git://cmake.org/stage/cmake.git
cd cmake
git checkout next
./bootstrap
make
sudo make install
```

--------------------------------

### Installing Ninja Build Tool

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/LibASTMatchersTutorial.md

Downloads, builds, and installs the Ninja build tool from its Git repository. Ninja is required for efficient builds with CMake.

```console
cd ~/clang-llvm
git clone https://github.com/martine/ninja.git
cd ninja
git checkout release
./bootstrap.py
sudo cp ninja /usr/bin/
```

--------------------------------

### Example YAML Output (Single Document)

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/YamlIO.rst

Example of YAML output generated for a single document, including document start and end markers.

```yaml
---
name:      Tom
hat-size:  7
...
```

--------------------------------

### Clone and Run LibFuzzer Examples

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LibFuzzer.rst

Clone the fuzzing repository and run provided examples using clang-fuzzer. Ensure you have the necessary LLVM tools installed.

```bash
git clone https://github.com/kcc/fuzzing-with-sanitizers.git
bin/clang-format-fuzzer fuzzing-with-sanitizers/llvm/clang-format/C1
bin/clang-fuzzer        fuzzing-with-sanitizers/llvm/clang/C1/
bin/clang-fuzzer        fuzzing-with-sanitizers/llvm/clang/TOK1  -tokens=$LLVM/llvm/lib/Fuzzer/cxx_fuzzer_tokens.txt
```

--------------------------------

### Bitset Coverage Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/SanitizerCoverage.md

Demonstrates how to enable and use bitset coverage. This generates a text file indicating executed blocks.

```console
% clang++ -fsanitize=address -fsanitize-coverage=edge cov.cc
% ASAN_OPTIONS="coverage=1:coverage_bitset=1" ./a.out
main
% ASAN_OPTIONS="coverage=1:coverage_bitset=1" ./a.out 1
foo
main
% head *bitset*
==> a.out.38214.bitset-sancov <==
01101
==> a.out.6128.bitset-sancov <==
11011%
```

--------------------------------

### DXIL Structure Annotation Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/DXIL.rst

Defines a structure annotation starting with its size in bytes, followed by field annotations.

```llvm
!4 = !{i32 12, !5, !6}
!5 = !{i32 6, !"field1", i32 3, i32 0, i32 7, i32 9}
!6 = !{i32 6, !"field2", i32 3, i32 4, i32 7, i32 4}
```

--------------------------------

### Create Build Directory

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/CMake.rst

This snippet shows how to create a directory for building LLVM and navigate into it. Building LLVM is not supported within the source directory.

```console
$ mkdir mybuilddir
$ cd mybuilddir
```

--------------------------------

### Get Status Register (GETSR) Instruction

Source: https://github.com/microsoft/directxshadercompiler/blob/main/test/MC/Disassembler/XCore/xcore.txt

Example of the GETSR instruction used to retrieve values from the status register.

```Assembly
getsr r11, 54
0x36 0x7f
```

```Assembly
getsr r11, 442
0x06 0xf0 0x3a 0x7f
```

--------------------------------

### Build and Test LLVM with Make

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/HowToSetupToolingForLLVM.md

Once the setup is complete, use this command to build and run all tests for the LLVM project using Make.

```bash
make check-all
```

--------------------------------

### Embed LLVM Libraries in a CMake Project

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/CMake.rst

Example CMakeLists.txt to import LLVM libraries and build a simple application. Ensure LLVM is installed or built with CMake for CONFIG mode to work correctly.

```cmake
cmake_minimum_required(VERSION 2.8.8)
project(SimpleProject)

find_package(LLVM REQUIRED CONFIG)

message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")

# Set your project compile flags.
# E.g. if using the C++ header files
# you will need to enable C++11 support
# for your compiler.

include_directories(${LLVM_INCLUDE_DIRS})
add_definitions(${LLVM_DEFINITIONS})

# Now build our tools
add_executable(simple-tool tool.cpp)

# Find the libraries that correspond to the LLVM components
# that we wish to use
llvm_map_components_to_libnames(llvm_libs support core irreader)

# Link against LLVM libraries
target_link_libraries(simple-tool ${llvm_libs})
```

--------------------------------

### Emit Optimization Report for Inliner Pass

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/UsersManual.md

Use -Rpass=inline to get a diagnostic remark when the inliner pass makes a transformation. This example shows how to compile code and the expected output format for an inlining remark.

```console
$ clang -O2 -Rpass=inline code.cc -o code
code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
int bar(int j) { return foo(j, j - 2); }
                        ^
```

--------------------------------

### Dump DXIL Instructions Without Extra Documentation

Source: https://github.com/microsoft/directxshadercompiler/blob/main/utils/hct/hctdb_inst_docs.txt

Use this snippet to list all DXIL instructions that do not have additional documentation. It requires the 'hctdb' library and initializes the DXIL database.

```python
import hctdb
h = hctdb.db_dxil()
```

--------------------------------

### Hello World LLVM Module Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Demonstrates the basic structure of an LLVM module, including global variable declaration, external function declaration, function definition, and named metadata.

```llvm
; Declare the string constant as a global constant.
@.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"

; External declaration of the puts function
declare i32 @puts(i8* nocapture) nounwind

; Definition of main function
define i32 @main() {   ; i32()*
  ; Convert [13 x i8]* to i8  *...
  %cast210 = getelementptr [13 x i8], [13 x i8]* @.str, i64 0, i64 0

  ; Call puts function to write out the string to stdout.
  call i32 @puts(i8* %cast210)
  ret i32 0
}

; Named metadata
!0 = !{i32 42, null, !"string"}
!foo = !{!0}
```

--------------------------------

### Build HTML Documentation

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/README.txt

Install Sphinx and run this command to generate HTML documentation locally. The output will be available in the _build/html directory.

```bash
cd docs/
make -f Makefile.sphinx
$BROWSER _build/html/index.html
```

--------------------------------

### Create a Clang Tool Directory Structure

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/LibASTMatchersTutorial.md

Sets up the necessary directory and CMakeLists.txt file for a new Clang tool within the tools/extra repository.

```bash
cd ~/clang-llvm/llvm/tools/clang
mkdir tools/extra/loop-convert
echo 'add_subdirectory(loop-convert)' >> tools/extra/CMakeLists.txt
vim tools/extra/loop-convert/CMakeLists.txt
```

--------------------------------

### LLVM Landing Pad Instruction Examples

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Demonstrates the syntax and usage of the 'landingpad' instruction in LLVM IR for exception handling. Includes examples for catching specific types, cleanup blocks, and filtering.

```llvm
;; A landing pad which can catch an integer.
%res = landingpad { i8*, i32 }
         catch i8** @_ZTIi

```

```llvm
;; A landing pad that is a cleanup.
%res = landingpad { i8*, i32 }
         cleanup

```

```llvm
;; A landing pad which can catch an integer and can only throw a double.
%res = landingpad { i8*, i32 }
         catch i8** @_ZTIi
         filter [1 x i8**] [@_ZTId]

```

--------------------------------

### Generate LLVMConfig.cmake for Install Tree

Source: https://github.com/microsoft/directxshadercompiler/blob/main/cmake/modules/CMakeLists.txt

Configures the LLVMConfig.cmake file for the install tree. It dynamically computes the installation prefix and sets installation-specific paths for includes, libraries, and binaries.

```cmake
set(LLVM_CONFIG_CODE "
# Compute the installation prefix from this LLVMConfig.cmake file location.
get_filename_component(LLVM_INSTALL_PREFIX \"${CMAKE_CURRENT_LIST_FILE}\" PATH)")
# Construct the proper number of get_filename_component(... PATH)
# calls to compute the installation prefix.
string(REGEX REPLACE "/" ";" _count "${LLVM_INSTALL_PACKAGE_DIR}")
foreach(p ${_count})
  set(LLVM_CONFIG_CODE "${LLVM_CONFIG_CODE}
get_filename_component(LLVM_INSTALL_PREFIX \"${LLVM_INSTALL_PREFIX}\" PATH)")
endforeach(p)
set(LLVM_CONFIG_INCLUDE_DIRS "${LLVM_INSTALL_PREFIX}/include")
set(LLVM_CONFIG_LIBRARY_DIRS "${LLVM_INSTALL_PREFIX}/lib${LLVM_LIBDIR_SUFFIX}")
set(LLVM_CONFIG_CMAKE_DIR "${LLVM_INSTALL_PREFIX}/${LLVM_INSTALL_PACKAGE_DIR}")
set(LLVM_CONFIG_TOOLS_BINARY_DIR "${LLVM_INSTALL_PREFIX}/bin")
set(LLVM_CONFIG_EXPORTS_FILE "${LLVM_CMAKE_DIR}/LLVMExports.cmake")
configure_file(
  LLVMConfig.cmake.in
  ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/LLVMConfig.cmake
  @ONLY)
```

--------------------------------

### Example Tool Execution and Output

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/RAVFrontendAction.md

This demonstrates how to compile and run the clang tool. The tool is executed with a C++ code snippet as input, and the expected output shows the location of the found class declaration.

```Shell
$ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
Found declaration at 1:29
```

--------------------------------

### Module Import Example (Pseudo-code)

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/Modules.md

Illustrates the basic syntax for importing a module using an 'import' declaration, which differs from traditional '#include' directives.

```c
import std.io; // pseudo-code; see below for syntax discussion
```

--------------------------------

### Prepare and Copy TLS Handshake Files

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LibFuzzer.rst

Obtain sample server key and certificate files from the selftls repository and copy them to the current directory for fuzzing.

```bash
# Get examples of key/pem files.
git clone   https://github.com/hannob/selftls
cp selftls/server* . -v
```

--------------------------------

### Install Clang Public Headers

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/CMakeLists.txt

Installs Clang's public header files to the installation's include directory, excluding specific patterns like '.svn' and 'config.h'.

```cmake
if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
  install(DIRECTORY include/clang include/clang-c
    DESTINATION include
    FILES_MATCHING
    PATTERN "*.def"
    PATTERN "*.h"
    PATTERN "config.h" EXCLUDE
    PATTERN ".svn" EXCLUDE
    )

  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include/clang
    DESTINATION include
    FILES_MATCHING
    PATTERN "CMakeFiles" EXCLUDE
    PATTERN "*.inc"
    PATTERN "*.h"
    )
endif()
```

--------------------------------

### Install Ninja binary

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/HowToSetupToolingForLLVM.md

Copy the built Ninja binary to a location in your system's PATH and set the appropriate permissions. This makes the 'ninja' command available system-wide.

```console
$ sudo cp ninja /usr/local/bin/
$ sudo chmod a+rx /usr/local/bin/ninja
```

--------------------------------

### Example Compilation and Execution Commands

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/analyzer/LibASTMatchersTutorial.md

Provides a sequence of shell commands to recompile the tool after changes and then run it against a test file to discover for loops matching the defined criteria.

```Shell
cd ~/clang-llvm/llvm/llvm_build/
ninja loop-convert
vim ~/test-files/simple-loops.cc
bin/loop-convert ~/test-files/simple-loops.cc
```

--------------------------------

### Install HLSLErrors Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/unittests/HLSLErrors/CMakeLists.txt

Installs the HLSLErrors executable to the runtime destination directory.

```cmake
install(TARGETS HLSLErrors
  RUNTIME DESTINATION bin)
```

--------------------------------

### Initialize Worklist with Function Instructions

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/ProgrammersManual.rst

Initializes a worklist with all instructions in a given Function F. Consider using SmallPtrSet for efficiency.

```c++
std::set<Instruction*> worklist;
  // or better yet, SmallPtrSet<Instruction*, 64> worklist;

  for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
    worklist.insert(&*I);
```

--------------------------------

### Pointer to Array Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of a pointer to an array of four 32-bit integers.

```plaintext
[4 x i32]*
```

--------------------------------

### Running opt with -debug option

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/ProgrammersManual.rst

Demonstrates how to execute the 'opt' tool with the '-debug' flag to enable output from DEBUG() macros, contrasting it with execution without the flag.

```none
$ opt < a.bc > /dev/null -mypass
<no output>
$ opt < a.bc > /dev/null -mypass -debug
I am here!
```

--------------------------------

### Clang Driver Compilation Phases Example 1

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/DriverInternals.md

Illustrates the compilation pipeline construction using the -ccc-print-phases flag. This example shows the stages for compiling a C file and assembling another.

```console
$ clang -ccc-print-phases -x c t.c -x assembler t.s
0: input, "t.c", c
1: preprocessor, {0}, cpp-output
2: compiler, {1}, assembler
3: assembler, {2}, object
4: input, "t.s", assembler
5: assembler, {4}, object
6: linker, {3, 5}, image
```

--------------------------------

### Vector of Floats Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of a vector containing 8 32-bit floating-point values.

```plaintext
<8 x float>
```

--------------------------------

### Example DXC Command-Line Compilation

Source: https://github.com/microsoft/directxshadercompiler/wiki/Using-dxc.exe-and-dxcompiler.dll

Demonstrates a typical command-line invocation of dxc.exe for compiling an HLSL shader. This example specifies the entry point, target profile, output file, debug information, and a preprocessor macro.

```text
dxc -E main -T ps_6_0 -Fo myshader.bin -Zi -Fd myshader.pdb -D MYDEFINE=1 myshader.hlsl
```

--------------------------------

### LLVM Pass Execution with Hello World

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/WritingAnLLVMPass.rst

Demonstrates the execution flow of LLVM passes, including the 'Hello World' pass, and shows the impact of analysis preservation.

```console
$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
Module Pass Manager
  Function Pass Manager
    Dominator Set Construction
    Immediate Dominators Construction
    Global Common Subexpression Elimination
--  Dominator Set Construction
--  Immediate Dominators Construction
--  Global Common Subexpression Elimination
    Hello World Pass
--  Hello World Pass
    Dominator Set Construction
    Natural Loop Construction
    Loop Invariant Code Motion
--  Natural Loop Construction
--  Loop Invariant Code Motion
    Module Verifier
--  Dominator Set Construction
--  Module Verifier
  Bitcode Writer
--Bitcode Writer
Hello: __main
Hello: puts
Hello: main
```

--------------------------------

### Vector of Integers Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of a vector containing 4 32-bit integer values.

```plaintext
<4 x i32>
```

--------------------------------

### LLVM Fragment Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/CodeGenerator.rst

An example LLVM fragment demonstrating floating-point arithmetic operations.

```llvm
%t1 = fadd float %W, %X
%t2 = fmul float %t1, %Y
%t3 = fadd float %t2, %Z
```

--------------------------------

### Start GDB on opt Process

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/WritingAnLLVMPass.rst

Begin debugging a transformation by starting GDB attached to the 'opt' process. This may take time due to debugging information.

```console
$ gdb opt
GNU gdb 5.0
Copyright 2000 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "sparc-sun-solaris2.6"...
(gdb) 

```

--------------------------------

### Configure and run a Clang Tool with AST Matchers

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/LibASTMatchersTutorial.md

Sets up a ClangTool, instantiates a MatchFinder and a LoopPrinter callback, adds the LoopMatcher to the finder, and runs the tool on the specified source files.

```C++
int main(int argc, const char **argv) {
  CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
  ClangTool Tool(OptionsParser.getCompilations(),
                 OptionsParser.getSourcePathList());

  LoopPrinter Printer;
  MatchFinder Finder;
  Finder.addMatcher(LoopMatcher, &Printer);

  return Tool.run(newFrontendActionFactory(&Finder).get());
}
```

--------------------------------

### Compiling and Linking with LTO

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LinkTimeOptimization.rst

This console example shows the commands to compile C source files into LLVM bitcode and native object files, and then link them using clang to enable Link Time Optimization.

```console
% clang -emit-llvm -c a.c -o a.o   # <-- a.o is LLVM bitcode file
% clang -c main.c -o main.o        # <-- main.o is native object file
% clang a.o main.o -o main         # <-- standard link command without modifications

```

--------------------------------

### Vector of Pointers Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of a vector containing 4 pointers to 64-bit integer values.

```plaintext
<4 x i64*>
```

--------------------------------

### Clang-cl Command-Line Options List

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/UsersManual.md

A comprehensive list of cl.exe compatibility options supported by clang-cl, covering compilation, preprocessing, optimization, and more.

```default
CL.EXE COMPATIBILITY OPTIONS:
  /?                     Display available options
  /arch:<value>          Set architecture for code generation
  /C                     Don't discard comments when preprocessing
  /c                     Compile only
  /D <macro[=value]>     Define macro
  /EH<value>             Exception handling model
  /EP                    Disable linemarker output and preprocess to stdout
  /E                     Preprocess to stdout
  /fallback              Fall back to cl.exe if clang-cl fails to compile
  /FA                    Output assembly code file during compilation
  /Fa<file or directory> Output assembly code to this file during compilation (with /FA)
  /Fe<file or directory> Set output executable file or directory (ends in / or \)
  /FI <value>            Include file before parsing
  /Fi<file>              Set preprocess output file name (with /P)
  /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
  /fp:except-
  /fp:except
  /fp:fast
  /fp:precise
  /fp:strict
  /GA                    Assume thread-local variables are defined in the executable
  /GF-                   Disable string pooling
  /GR-                   Disable emission of RTTI data
  /GR                    Enable emission of RTTI data
  /Gs<value>             Set stack probe size
  /Gw-                   Don't put each data item in its own section
  /Gw                    Put each data item in its own section
  /Gy-                   Don't put each function in its own section
  /Gy                    Put each function in its own section
  /help                  Display available options
  /I <dir>               Add directory to include search path
  /J                     Make char type unsigned
  /LDd                   Create debug DLL
  /LD                    Create DLL
  /link <options>        Forward options to the linker
  /MDd                   Use DLL debug run-time
  /MD                    Use DLL run-time
  /MTd                   Use static debug run-time
  /MT                    Use static run-time
  /Ob0                   Disable inlining
  /Od                    Disable optimization
  /Oi-                   Disable use of builtin functions
  /Oi                    Enable use of builtin functions
  /Os                    Optimize for size
  /Ot                    Optimize for speed
  /Ox                    Maximum optimization
  /Oy-                   Disable frame pointer omission
  /Oy                    Enable frame pointer omission
  /O<n>                  Optimization level
  /o <file or directory> Set output file or directory (ends in / or \)
  /P                     Preprocess to file
  /Qvec-                 Disable the loop vectorization passes
  /Qvec                  Enable the loop vectorization passes
  /showIncludes          Print info about included files to stderr
  /TC                    Treat all source files as C
  /Tc <filename>         Specify a C source file
  /TP                    Treat all source files as C++
  /Tp <filename>         Specify a C++ source file
  /U <macro>             Undefine macro
  /vd<value>             Control vtordisp placement
  /vmb                   Use a best-case representation method for member pointers
  /vmg                   Use a most-general representation for member pointers
  /vmm                   Set the default most-general representation to multiple inheritance
  /vms                   Set the default most-general representation to single inheritance
  /vmv                   Set the default most-general representation to virtual inheritance
  /volatile:iso          Volatile loads and stores have standard semantics
  /volatile:ms           Volatile loads and stores have acquire and release semantics
  /W0                    Disable all warnings
  /W1                    Enable -Wall
  /W2                    Enable -Wall
```

--------------------------------

### Build Manpage Documentation

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/README.txt

Use the 'man' makefile target to build man pages locally. The generated man pages will be in the _build/man directory.

```bash
cd docs/
make -f Makefile.sphinx man
man -l _build/man/FileCheck.1
```

--------------------------------

### Vector of 64-bit Integers Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of a vector containing 2 64-bit integer values.

```plaintext
<2 x i64>
```

--------------------------------

### Conflict Declaration Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/Modules.md

Example of a module declaring a conflict with module B, with a custom message.

```default
module Conflicts {
  explicit module A {
    header "conflict_a.h"
    conflict B, "we just don't like B"
  }

  module B {
    header "conflict_b.h"
  }
}
```

--------------------------------

### Config Macros Declaration Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/Modules.md

Example of declaring NDEBUG as an exhaustive configuration macro for a module.

```default
module MyLogger {
  umbrella header "MyLogger.h"
  config_macros [exhaustive] NDEBUG
}
```

--------------------------------

### LLVMBuild File Format Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LLVMBuild.rst

This example demonstrates the basic syntax of an LLVMBuild file, including comments, sections, and properties with string, list, and boolean values. Property values cannot contain spaces.

```ini
; Comments start with a semi-colon.

; Sections are declared using square brackets.
[component_0]

; Properties are declared using '=' and are contained in the previous section.
; 
; We support simple string and boolean scalar values and list values, where
; items are separated by spaces. There is no support for quoting, and so
; property values may not contain spaces.
property_name = property_value
list_property_name = value_1 value_2 ... value_n
boolean_property_name = 1 (or 0)
```

--------------------------------

### Define GCC Installation Prefix

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/CMakeLists.txt

Sets the GCC_INSTALL_PREFIX cache variable to specify the directory where GCC is installed.

```cmake
set(GCC_INSTALL_PREFIX "" CACHE PATH "Directory where gcc is installed." )
```

--------------------------------

### Example Statistics Output

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/ProgrammersManual.rst

Sample output from the -stats option when running opt on a SPEC benchmark.

```none
   7646 bitcodewriter   - Number of normal instructions
    725 bitcodewriter   - Number of oversized instructions
 129996 bitcodewriter   - Number of bitcode bytes written
   2817 raise           - Number of insts DCEd or constprop'd
```

--------------------------------

### SparcTargetAsmInfo Constructor Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/WritingAnLLVMBackend.rst

Example of a SparcTargetAsmInfo constructor, setting target-specific directives for data representation and comments.

```c++
SparcTargetAsmInfo::SparcTargetAsmInfo(const SparcTargetMachine &TM) {
  Data16bitsDirective = "\t.half\t";
  Data32bitsDirective = "\t.word\t";
  Data64bitsDirective = 0;  // .xword is only supported by V9.
  ZeroDirective = "\t.skip\t";
  CommentString = "!";
  ConstantPoolSection = "\t.section \\".rodata\\",#alloc\n";
}
```

--------------------------------

### Install LLVM CMake Configuration Files

Source: https://github.com/microsoft/directxshadercompiler/blob/main/cmake/modules/CMakeLists.txt

Installs LLVM's CMake configuration files, including exports, configuration scripts, and other CMake modules, to the specified installation directory. This enables other projects to find and use LLVM via CMake.

```cmake
if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
  install(EXPORT LLVMExports DESTINATION ${LLVM_INSTALL_PACKAGE_DIR})

  install(FILES
    ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/LLVMConfig.cmake
    ${llvm_cmake_builddir}/LLVMConfigVersion.cmake
    LLVM-Config.cmake
    DESTINATION ${LLVM_INSTALL_PACKAGE_DIR})

  install(DIRECTORY .
    DESTINATION ${LLVM_INSTALL_PACKAGE_DIR}
    FILES_MATCHING PATTERN *.cmake
    PATTERN .svn EXCLUDE
    PATTERN LLVMConfig.cmake EXCLUDE
    PATTERN LLVMConfigVersion.cmake EXCLUDE
    PATTERN LLVM-Config.cmake EXCLUDE
    PATTERN GetHostTriple.cmake EXCLUDE
    PATTERN VersionFromVCS.cmake EXCLUDE
    PATTERN CheckAtomic.cmake EXCLUDE)
endif()
```

--------------------------------

### Install LTO Header File

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/lto/CMakeLists.txt

Installs the LTO C API header file to the appropriate include directory.

```cmake
install(FILES ${LLVM_MAIN_INCLUDE_DIR}/llvm-c/lto.h
  DESTINATION include/llvm-c)
```

--------------------------------

### Install HLSLHost Executable

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/unittests/HLSLHost/CMakeLists.txt

Specifies the installation rules for the HLSLHost target, placing the runtime binary in the 'bin' directory.

```cmake
install(TARGETS HLSLHost
  RUNTIME DESTINATION bin)

```

--------------------------------

### DXIL Entry Points Metadata Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/DXIL.rst

Specifies a list of entry point records for a DXIL module. Each record includes the function symbol, unmangled name, signatures, resources, and shader capabilities.

```llvm
define void @"\01?myfunc1@@YAXXZ"() #0 { ... }
define float @"\01?myfunc2@@YAMXZ"() #0 { ... }

!dx.entryPoints = !{ !1, !2 }

!1 = !{ void ()* @"\01?myfunc1@@YAXXZ", !"myfunc1", !3, null, null }
!2 = !{ float ()* @"\01?myfunc2@@YAMXZ", !"myfunc2", !5, !6, !7 }
```

--------------------------------

### Register Metadata Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of metadata used to identify a register, specifically the stack pointer ('sp').

```LLVM IR
!0 = !{"sp\00"}
```

--------------------------------

### Example C Standard Library Module Map

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/Modules.md

This example demonstrates how to structure a module map file for the C standard library, defining submodules for different functionalities and exporting their contents.

```default
module std [system] [extern_c] {
  module assert {
    textual header "assert.h"
    header "bits/assert-decls.h"
    export *
  }

  module complex {
    header "complex.h"
    export *
  }

  module ctype {
    header "ctype.h"
    export *
  }

  module errno {
    header "errno.h"
    header "sys/errno.h"
    export *
  }

  module fenv {
    header "fenv.h"
    export *
  }

  // ...more headers follow...
}
```

--------------------------------

### Pointer in Specific Address Space Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of a pointer to a 32-bit integer residing in address space #5.

```plaintext
i32 addrspace(5)*
```

--------------------------------

### Pointer to Function Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/LangRef.rst

Example of a pointer to a function that accepts a pointer to a 32-bit integer and returns a 32-bit integer.

```plaintext
i32 (i32*) *
```

--------------------------------

### Compile and Run a Clang Plugin

Source: https://github.com/microsoft/directxshadercompiler/blob/main/tools/clang/docs/ClangPlugins.md

Build the plugin dynamic library and then use `clang++` with `-Xclang -load`, `-Xclang -plugin`, and `-Xclang -plugin-arg-` options to execute the plugin.

```shell
$ export BD=/path/to/build/directory
$ (cd $BD && make PrintFunctionNames )
$ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
          -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
          -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
          tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
          -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
          -plugin -Xclang print-fns
```

--------------------------------

### HLSL Miss Shader Example

Source: https://github.com/microsoft/directxshadercompiler/blob/main/docs/SPIR-V.rst

Example of a miss shader entry point in HLSL. Invoked when no intersection is found.

```hlsl
struct Payload {
    float4 color;
};
[shader("miss")]
void main(inout Payload a) {
    a.color = float4(0.0f,1.0f,0.0f,0.0f);
}
```