Thank you for considering contributing to the Shader-Slang project! We welcome your help to improve and enhance our project. Please take a moment to read through this guide to understand how you can contribute.
This document is designed to guide you in contributing to the project. It is intended to be easy to follow without sending readers to other pages and links. You can simply copy and paste the command lines described in this document.
- Contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant the rights to use your contribution.
- When you submit a pull request, a CLA bot will determine whether you need to sign a CLA. Simply follow the instructions provided.
- Please read and follow the contributor Code of Conduct.
- Bug reports and feature requests should be submitted via the GitHub issue tracker.
- Changes should ideally come in as small pull requests on top of master, coming from your own personal fork of the project.
- Large features that will involve multiple contributors or a long development time should be discussed in issues and broken down into smaller pieces that can be implemented and checked in stages.
Navigate to the Shader-Slang repository. Click on the "Fork" button in the top right corner to create a copy of the repository in your GitHub account. This document will assume that the name of your forked repository is "slang". Make sure your "Actions" are enabled. Visit your forked repository, click on the "Actions" tab, and enable the actions.
-
Clone your fork locally, replacing "USER-NAME" in the command below with your actual username.
$ git clone --recursive --tags https://github.com/USER-NAME/slang.git $ cd slang -
Fetch tags by adding the original repository as an upstream. It is important to have tags in your forked repository because our workflow/action uses the information for the build process. But the tags are not fetched by default when you fork a repository in GitHub. You need to add the original repository as an upstream and fetch tags manually.
$ git remote add upstream https://github.com/shader-slang/slang.git $ git fetch --tags upstreamYou can check whether the tags are fetched properly with the following command.
$ git tag -l -
Push tags to your forked repository. The tags are fetched to your local machine but haven't been pushed to the forked repository yet. You need to push tags to your forked repository with the following command.
$ git push --tags origin
Create a new branch for your contribution:
$ git checkout -b feature/your-feature-name
Please follow the instructions on how to Build Slang from Source.
For a quick reference, follow the instructions below.
Download and install CMake from CMake.org/download.
Run CMake with the following command to generate a Visual Studio 2022 Solution:
C:\git\slang> cmake.exe --preset vs2022 # For Visual Studio 2022
C:\git\slang> cmake.exe --preset vs2019 # For Visual Studio 2019
Open build/slang.sln with Visual Studio IDE and build it for "x64".
Or you can build with the following command:
C:\git\slang> cmake.exe --build --preset release
Install CMake and Ninja.
$ sudo apt-get install cmake ninja-build
Warning: Currently the required CMake version is 3.25 or above.
Run CMake with the following command to generate Makefile:
$ cmake --preset default
Build with the following command:
$ cmake --build --preset release
Install Xcode from the App Store.
Install CMake and Ninja; we recommend using Homebrew for installing them.
$ brew install ninja
$ brew install cmake
Run CMake with the following command to generate Makefile:
$ cmake --preset default
Build with the following command:
$ cmake --build --preset release
slang-llvm is required to run slang-test properly.
Follow the instructions below if you wish to build slang-llvm locally.
$ external/build-llvm.sh --source-dir build/slang-llvm_src --install-prefix build/slang-llvm_install
You need to use the following command to regenerate the Makefile:
$ cmake --preset default --fresh -DSLANG_SLANG_LLVM_FLAVOR=USE_SYSTEM_LLVM -DLLVM_DIR=build/slang-llvm_install/lib/cmake/llvm -DClang_DIR=build/slang-llvm_install/lib/cmake/clang
Build with the following command:
$ cmake --build --preset release
When you execute cmake --preset, CMake uses the GitHub REST API, and there is a daily/hourly API limit for each IP address. If you are using an IP address shared by many people, you may hit this limit occasionally. Refer to Rate limits for the REST API for more information.
When this happens, you will see a warning message from CMake as follows:
CMake Warning at cmake/GitHubRelease.cmake:53 (message):
If API rate limit is exceeded, Github allows a higher limit when you use
token. Try a cmake option -DSLANG_GITHUB_TOKEN=your_token_here
Call Stack (most recent call first):
cmake/GitHubRelease.cmake:114 (check_release_and_get_latest)
CMakeLists.txt:141 (get_best_slang_binary_release_url)
The limit is higher when you use your personal account with a "Passkey".
To generate a "Passkey" on GitHub:
- Go to GitHub "Settings" for your account.
- Go to "Password and Authentication".
- Click "Add a passkey" button.
- GitHub will generate a "Passkey".
Use the generated "Passkey" with a cmake option "-DSLANG_GITHUB_TOKEN=your-pass-key-here".
Make your changes and ensure to follow our Design Decisions.
Test your changes thoroughly to ensure they do not introduce new issues. This is done by building and running slang-test from the repository root directory. For more details about slang-test, please refer to the Documentation on testing.
Note:
slang-testis meant to be launched from the root of the repository. It uses a hard-coded directory name "tests/" that is expected to exist in the current working directory.
Note: One of the options for
slang-test.exeis-api, and it takes an additional keyword to specify which API to test. When the option is-api all-cpu, as an example, it means it tests all APIs except CPU. The minus sign (-) afterallmeans "exclude," and you can "include" with a plus sign (+) like-api gl+dx11.
If you are familiar with Workflows/Actions in GitHub, you can check Our Workflows. The "Test Slang" section in ci.yml is where slang-test runs.
For a quick reference, follow the instructions below.
- Download and install VulkanSDK from the LunarG SDK page.
- Set an environment variable to enable SPIR-V validation in the Slang compiler:
C:\git\slang> set SLANG_RUN_SPIRV_VALIDATION=1 - Run
slang-testwith multiple threads. This may take 10 minutes or less depending on the performance of your computer.C:\git\slang> build\Release\bin\slang-test.exe -use-test-server -server-count 8Note: If you increase
-server-countto more than 16, you may find some of the tests randomly fail. This is a known issue on the graphics driver side. - Check whether the tests finished as expected.
- Install VulkanSDK by following the Instructions from LunarG.
$ sudo apt update $ sudo apt install vulkan-sdk - Run
slang-testwith multiple threads. This may take 10 minutes or less depending on the performance of your computer.$ ./build/Release/bin/slang-test -use-test-server -server-count 8 - Check whether the tests finished as expected.
Commit your changes to the branch with a descriptive commit message:
$ git commit
It is important to have a descriptive commit message. Unlike comments inside the source code, the commit messages don't spoil over time because they are tied to specific changes and can be reviewed by many people many years later.
Here is a good example of a commit message:
Add user authentication feature
Fixes #1234
This commit introduces a new user authentication feature. It includes changes to the login page, user database, and session management to provide secure user authentication.
Push your branch to your forked repository with the following command:
$ git push origin feature/your-feature-name
After the changes are pushed to your forked repository, the change needs to be merged to the final destination shader-slang/slang.
In order to proceed, you will need to create a "Pull Request," or "PR" for short.
When you push to your forked repository, git-push usually prints a URL that allows you to create a PR.
If you missed a chance to use the URL, you can still create a PR from the GitHub webpage.
Go to your forked repository and change the branch name to the one you used for git-push.
It will show a message like "This branch is 1 commit ahead of shader-slang/slang:master."
You can create a PR by clicking on the message.
Once a PR is created against shader-slang/slang:master, the PR will be merged when the following conditions are met:
- The PR is reviewed and got approval.
- All of the workflows pass.
When the conditions above are all met, you will have a chance to rewrite the commit message. Since the Slang repo uses the "squash" strategy for merging, multiple commits in your PR will become one commit. By default, GitHub will concatenate all of the commit messages sequentially, but often it is not readable. Please rewrite the final commit message in a way that people can easily understand what the purpose of the commit is.
There are two cases where the workflow may fail for reasons that are not directly related to the change:
- "Breaking change" labeling is missing.
- Source code "Format" needs to be changed.
After your pull request is created, you will receive code reviews from the community within 24 hours.
The PR requires approval from people who have permissions. They will review the changes before approving the pull. During this step, you will get feedback from other people, and they may request you to make some changes.
Follow-up changes that address review comments should be pushed to your pull request branch as additional commits. Any additional commits made to the same branch in your forked repository will show up on the PR as incremental changes.
When your branch is out of sync with top-of-tree, submit a merge commit to keep them in sync. Do not rebase and force push after the PR is created to keep the change history during the review process.
Use these commands to sync your branch:
$ git fetch upstream master
$ git merge upstream/master # resolve any conflicts here
$ git submodule update --recursive
The Slang repository uses the squash strategy for merging pull requests, which means all your commits will be squashed into one commit by GitHub upon merge.
All pull requests must be labeled as either pr: non-breaking or pr: breaking change before it can be merged to the main branch. If you are already a committer, you are expected to label your PR when you create it. If you are not yet a committer, a reviewer will do this for you.
A PR is considered to introduce a breaking change if an existing application that uses Slang may no longer compile or behave the same way with the change. Typical examples of breaking changes include:
- Changes to
slang.hthat modify the Slang API in a way that breaks binary compatibility. - Changes to the language syntax or semantics that may cause existing Slang code to not compile or produce different run-time results. For example, changing the overload resolution rules.
- Removing or renaming an existing intrinsic from the core module.
When the PR contains source code changes, one of the workflows will check the formatting of the code.
Code formatting can be automatically fixed on your branch by commenting /format; a bot will proceed to open a PR targeting your branch. You can merge the generated PR into your branch, and the problem will be resolved.
When the PR contains document changes for the Slang User's Guide, you need to update the table of contents by running a PowerShell script as follows:
# Open PowerShell on Windows
cd docs
.\build_toc.ps1
# Add to git commit
git add gfx-user-guide/toc.html
git add user-guide/toc.html
Similar to the /format bot-command described in the previous section, you can also use /regenerate-toc instead.
When the PR is limited to document changes, the build workflows may not start properly. This is because the building process is unnecessary when the PR is limited to document changes. This may lead to a case where some of the required build workflows are stuck waiting to start. When this happens, the committers will manually merge the PR as a workaround, and it will not give you a chance to rewrite the commit message.
Follow our Coding Conventions to maintain consistency throughout the project.
Here are a few highlights:
- Indent by four spaces. Don't use tabs except in files that require them (e.g., Makefiles).
- Don't use the STL containers, iostreams, or the built-in C++ RTTI system.
- Don't use the C++ variants of C headers (e.g., use
<stdio.h>instead of<cstdio>). - Don't use exceptions for non-fatal errors (and even then support a build flag to opt out of exceptions).
- Types should use UpperCamelCase, values should use lowerCamelCase, and macros should use
SCREAMING_SNAKE_CASEwith a prefixSLANG_. - Global variables should have a
gprefix, non-const static class members can have ansprefix, constant data (in the sense of static const) should have akprefix, and anm_prefix on member variables and a_prefix on member functions are allowed. - Prefixes based on types (e.g.,
pfor pointers) should never be used. - In function parameter lists, an
in,out, orioprefix can be added to a parameter name to indicate whether a pointer/reference/buffer is intended to be used for input, output, or both input and output. - Trailing commas should always be used for array initializer lists.
- Try to write comments that explain the "why" of your code more than the "what."
We track all our work with GitHub issues. Check the Issues for open issues. If you find a bug or want to suggest an enhancement, please open a new issue.
If you're new to the project or looking for a good starting point, consider exploring issues labeled as Good first bug. These are beginner-friendly bugs that provide a great entry point for new contributors.
Join our Discussions.
By contributing to Shader-Slang, you agree that your contributions will be licensed under the MIT License. The full text of the License can be found in the LICENSE file in the root of the repository.