diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/update_spirv.md | 168 |
1 files changed, 143 insertions, 25 deletions
diff --git a/docs/update_spirv.md b/docs/update_spirv.md index 8463da343..6994b3fa4 100644 --- a/docs/update_spirv.md +++ b/docs/update_spirv.md @@ -7,55 +7,99 @@ There are three directories under `external` that are related to SPIR-V: In order to use the latest or custom SPIR-V, they need to be updated. -## Update URLs to the repo -Open `.gitmodules` and update the following sections to have a desired `url` set. +## Fork `shader-slang/SPIRV-Tools` repo and update it + +Currently Slang uses [shader-slang/SPIRV-Tools](https://github.com/shader-slang/SPIRV-Tools) forked from [KhronosGroup/SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools). +In order for Slang to use the latest changes from `KhronosGroup/SPIRV-Tools`, `shader-slang/SPIRV-Tools` needs to be updated. + +1. Fork `shader-slang/SPIRV-Tools` to your personal github organization like `your-name/SPIRV-Tools`. +1. Clone it on your local machine. + ``` + git clone https://github.com/your-name/SPIRV-Tools.git # replace `your-name` to the actual URL + ``` +1. Fetch from `KhronosGroup/SPIRV-Tools`. + ``` + git remote add khronos https://github.com/KhronosGroup/SPIRV-Tools.git + git fetch khronos + ``` +1. Create a branch for a Pull Request. + ``` + git checkout -b merge/update + ``` +1. Rebase to khronos/main + ``` + git rebase khronos/main # use ToT + ``` +1. Push to Github. + ``` + git push origin merge/update + ``` + +The steps above will create a branch called `merge/update`. You can use a different name but this document will use the name. + + +## Test the branch before creating a Pull Request + +Before creating a Pull Request, it will be a good idea to test if it works. +But if you are confident, you may skip the testing step. + + +### Modify `.gitmodules` and use the `merge/update` branch + +On a Slang repo side, you need to create a branch for the following changes. +``` +git clone https://github.com/your-name/slang.git # replace `your-name` to the actual URL +cd slang +git checkout -b update_spirv +``` + +Open `.gitmodules` and modify the setting to the following, ``` [submodule "external/spirv-tools"] path = external/spirv-tools - url = https://github.com/shader-slang/SPIRV-Tools.git + url = https://github.com/your-name/SPIRV-Tools.git [submodule "external/spirv-headers"] path = external/spirv-headers url = https://github.com/KhronosGroup/SPIRV-Headers.git ``` +Note that you need to replace `your-name` with the actual URL from the previous step. -Run the following command to apply the change. +Apply the URL changes with the following commands, ``` git submodule sync git submodule update --init --recursive -``` -If you need to use a specific branch from the repos, you need to manually checkout the branch. -``` -cd external/spirv-tools -git checkout branch_name_to_use +cd spirv-headers +git fetch +git checkout origin/main # use ToT cd .. -git add spirv-tools -cd external/spirv-headers -git checkout branch_name_to_use -cd .. -git add spirv-headers +cd external +cd spirv-tools +git fetch +git checkout merge/update # use merger/update branch ``` -## Build spirv-tools + +### Build spirv-tools A directory, `external/spirv-tools/generated`, holds a set of files generated from spirv-tools directory. You need to build spirv-tools in order to generate them. ``` -cd external/spirv-tools -python3.exe utils/git-sync-deps # this step may require you to register your ssh public key to gitlab.khronos.org -mkdir build -cd build -cmake.exe .. -cmake.exe --build . --config Release +cd external +cd spirv-tools +python3.exe utils\git-sync-deps # this step may require you to register your ssh public key to gitlab.khronos.org +cmake.exe . -B build +cmake.exe --build build --config Release ``` -## Copy the generated files from spirv-tools -Copy some of generated files from `external/spirv-tools/build/` to `external/spirv-tools-generated`. -The following files are ones you need to copy at the momment, but the list will change in the future. +### Copy the generated files from `spirv-tools` to `spirv-tools-generated` + +Copy some of generated files from `external/spirv-tools/build/` to `external/spirv-tools-generated/`. +The following files are ones you need to copy at the momment, but the list may change in the future. ``` DebugInfo.h NonSemanticShaderDebugInfo100.h @@ -73,10 +117,84 @@ nonsemantic.vkspreflection.insts.inc opencl.debuginfo.100.insts.inc opencl.std.insts.inc operand.kinds-unified1.inc -options-pinned.h spv-amd-gcn-shader.insts.inc spv-amd-shader-ballot.insts.inc spv-amd-shader-explicit-vertex-parameter.insts.inc spv-amd-shader-trinary-minmax.insts.inc ``` + +### Build Slang and run slang-test + +There are many ways to build Slang executables. Refer to the [document](https://github.com/shader-slang/slang/blob/master/docs/building.md) for more detail. +For a quick reference, you can build with the following commands, +``` +cmake.exe --preset vs2019 +cmake.exe --build --preset release +``` + +After building Slang executables, run `slang-test` to see all tests are passing. +``` +set SLANG_RUN_SPIRV_VALIDATION=1 +build\Release\bin\slang-test.exe -use-test-server -server-count 8 +``` + +It is often the case that some of tests fail at this step, because of the changes on SPIRV-Header side. +You need to properly resolve them before proceed. + + +## Create A Pull Request on `shader-slang/SPIRV-Tools` + +After testing is done, you should create a Pull Request on `shader-slang/SPIRV-Tools` repo. + +1. The git-push command will show you a URL for creating a Pull Request like following, + > https://github.com/your-name/SPIRV-Tools/pull/new/merge/update # replace `your-name` to the actual URL + + Create a Pull Request. +1. Wait for all workflows to pass. +1. Merge the PR and take a note of the commit ID for the next step. + +Note that this process will update `shader-slang/SPIRV-Tools` repo, but your merge is not used by `slang` repo yet. + + +## Create a Pull Request on `shader-slang/slang` + +After the PR is merged to `shader-slang/SPIRV-Tools`, `slang` needs to start using it. + +On the clone of Slang repo, revert the changes in `.gitmodules` if modified. +``` +# revert the change in .gitmodules +git checkout .gitmodules +git submodule sync +git submodule update --init --recursive +``` + +You need to stage and commit the latest commit IDs of spirv-tools and spirv-headers. +``` +cd external + +# Add changes in spirv-tools-generated +git add spirv-tools-generated + +# Add commit ID of spirv-headers +cd spirv-headers +git fetch +git checkout origin/main # Use ToT +cd .. +git add spirv-headers + +# Add commit ID of spirv-tools +cd spirv-tools +git fetch +git checkout merge/update # Use merge/update branch +cd .. +git add spirv-tools + +# Add more if there are other changes to resolve the test failures. + +git commit +git push origin update_spirv +``` +Once all changes are pushed to GitHub, you can create a Pull Request on `shader-slang/slang`. + + |