review and revise building instructions (#5302)

Closes #3905 Would be good to tackle this as a follow on #5247 Co-authored-by: Yong He <yonghe@outlook.com>
shader-slang · Oct 15, 2024 · 3e170c7 · 3e170c7
1 parent 66b1031
commit 3e170c7
Showing 1 changed file with 109 additions and 46 deletions.
diff --git a/docs/building.md b/docs/building.md
@@ -9,7 +9,7 @@ version of Slang.
 
 Please install:
 
-- CMake (3.25 preferred, but 3.22 works[^cmake-version])
+- CMake (3.25 preferred, but 3.22 works[^1])
 - A C++ compiler with support for C++17. GCC, Clang and MSVC are supported
 - A CMake compatible backend, for example Visual Studio or Ninja
 
@@ -21,6 +21,9 @@ Optional dependencies include
 - Aftermath
 - X11
 
+Other dependencies are sourced from submodules in the [./external](./external)
+directory.
+
 ## Get the Source Code
 
 Clone [this](https://github.com/shader-slang/slang) repository. Make sure to
@@ -32,7 +35,8 @@ git clone https://github.com/shader-slang/slang --recursive
 
 ## Configure and build
 
-> This section assumes cmake 3.25 or greater, if you're on a lower version please see [building with an older cmake](#older-cmake)
+> This section assumes cmake 3.25 or greater, if you're on a lower version
+> please see [building with an older cmake](#building-with-an-older-cmake)
 
 For a Ninja based build system (all platforms) run:
 ```bash
@@ -47,23 +51,44 @@ start devenv ./build/slang.sln # to optionally open the project in Visual Studio
 cmake --build --preset release # to build from the CLI
 ```
 
-The `vs2022-dev` preset turns on features that makes debugging easy.
+There also exists a `vs2022-dev` preset which turns on features to aid
+debugging.
 
 ### WebAssembly build
 
-In order to build WebAssembly build of Slang, Slang needs to be compiled with [Emscripten SDK](https://github.com/emscripten-core/emsdk).
-You can find more information about [Emscripten](https://emscripten.org/).
+In order to build WebAssembly build of Slang, Slang needs to be compiled with
+[Emscripten SDK](https://github.com/emscripten-core/emsdk). You can find more
+information about [Emscripten](https://emscripten.org/).
 
 You need to clone the EMSDK repo. And you need to install and activate the latest.
+
+
 ```bash
 git clone https://github.com/emscripten-core/emsdk.git
 cd emsdk
-./emsdk install latest  # For Windows, emsdk.bat install latest
-./emsdk activate latest # For Windows, emsdk.bat activate latest
 ```
 
-After EMSDK is activated, Slang needs to be built in three steps: build "generators", configure the build with "emcmake" and build.
-For more information about "generators", please refer to the later part of the documentation about [cross-compiling](docs/building.md#cross-compiling).
+For non-Windows platforms
+```bash
+./emsdk install latest
+./emsdk activate latest
+```
+
+For Windows
+```cmd
+emsdk.bat install latest
+emsdk.bat activate latest
+```
+
+After EMSDK is activated, Slang needs to be built in a cross compiling setup: 
+
+- build the `generators` target for the build platform
+- configure the build with `emcmake` for the host platform
+- build for the host platform.
+
+> Note: For more details on cross compiling please refer to the 
+> [cross-compiling](docs/building.md#cross-compiling) section.
+
 ```bash
 # Build generators.
 cmake --workflow --preset generators --fresh
@@ -81,7 +106,8 @@ emcmake cmake -DSLANG_GENERATORS_PATH=generators/bin --preset emscripten -G "Nin
 cmake --build --preset emscripten --target slang-wasm
 ```
 
-**Note:** If the last build step fails, try running the command that `emcmake` outputs, directly.
+> Note: If the last build step fails, try running the command that `emcmake`
+> outputs, directly.
 
 ## Testing
 
@@ -95,45 +121,58 @@ See the [documentation on testing](../tools/slang-test/README.md) for more infor
 
 ### CMake options
 
-| Option                            | Default          | Description                                                        |
-|-----------------------------------|------------------|--------------------------------------------------------------------|
-| `SLANG_VERSION`                   | Latest `v*` tag  | The project version, detected using git if available               |
-| `SLANG_EMBED_STDLIB`              | `FALSE`          | Build slang with an embedded version of the stdlib                 |
-| `SLANG_EMBED_STDLIB_SOURCE`       | `TRUE`           | Embed stdlib source in the binary                                  |
-| `SLANG_ENABLE_ASAN`               | `FALSE`          | Enable ASAN (address sanitizer)                                    |
-| `SLANG_ENABLE_FULL_IR_VALIDATION` | `FALSE`          | Enable full IR validation (SLOW!)                                  |
-| `SLANG_ENABLE_IR_BREAK_ALLOC`     | `FALSE`          | Enable IR BreakAlloc functionality for debugging.                  |
-| `SLANG_ENABLE_GFX`                | `TRUE`           | Enable gfx targets                                                 |
-| `SLANG_ENABLE_SLANGD`             | `TRUE`           | Enable language server target                                      |
-| `SLANG_ENABLE_SLANGC`             | `TRUE`           | Enable standalone compiler target                                  |
-| `SLANG_ENABLE_SLANGRT`            | `TRUE`           | Enable runtime target                                              |
-| `SLANG_ENABLE_SLANG_GLSLANG`      | `TRUE`           | Enable glslang dependency and slang-glslang wrapper target         |
+| Option                            | Default          | Description                                                                                  |
+|-----------------------------------|------------------|----------------------------------------------------------------------------------------------|
+| `SLANG_VERSION`                   | Latest `v*` tag  | The project version, detected using git if available                                         |
+| `SLANG_EMBED_STDLIB`              | `FALSE`          | Build slang with an embedded version of the stdlib                                           |
+| `SLANG_EMBED_STDLIB_SOURCE`       | `TRUE`           | Embed stdlib source in the binary                                                            |
+| `SLANG_ENABLE_ASAN`               | `FALSE`          | Enable ASAN (address sanitizer)                                                              |
+| `SLANG_ENABLE_FULL_IR_VALIDATION` | `FALSE`          | Enable full IR validation (SLOW!)                                                            |
+| `SLANG_ENABLE_IR_BREAK_ALLOC`     | `FALSE`          | Enable IR BreakAlloc functionality for debugging.                                            |
+| `SLANG_ENABLE_GFX`                | `TRUE`           | Enable gfx targets                                                                           |
+| `SLANG_ENABLE_SLANGD`             | `TRUE`           | Enable language server target                                                                |
+| `SLANG_ENABLE_SLANGC`             | `TRUE`           | Enable standalone compiler target                                                            |
+| `SLANG_ENABLE_SLANGRT`            | `TRUE`           | Enable runtime target                                                                        |
+| `SLANG_ENABLE_SLANG_GLSLANG`      | `TRUE`           | Enable glslang dependency and slang-glslang wrapper target                                   |
 | `SLANG_ENABLE_TESTS`              | `TRUE`           | Enable test targets, requires SLANG_ENABLE_GFX, SLANG_ENABLE_SLANGD and SLANG_ENABLE_SLANGRT |
-| `SLANG_ENABLE_EXAMPLES`           | `TRUE`           | Enable example targets, requires SLANG_ENABLE_GFX                  |
-| `SLANG_LIB_TYPE`                  | `SHARED`         | How to build the slang library                                     |
-| `SLANG_SLANG_LLVM_FLAVOR`         | `FETCH_BINARY`   | How to set up llvm support                                         |
-| `SLANG_SLANG_LLVM_BINARY_URL`     | System dependent | URL specifying the location of the slang-llvm prebuilt library     |
-| `SLANG_GENERATORS_PATH`           | ``               | Path to an installed `all-generators` target for cross compilation |
+| `SLANG_ENABLE_EXAMPLES`           | `TRUE`           | Enable example targets, requires SLANG_ENABLE_GFX                                            |
+| `SLANG_LIB_TYPE`                  | `SHARED`         | How to build the slang library                                                               |
+| `SLANG_SLANG_LLVM_FLAVOR`         | `FETCH_BINARY`   | How to set up llvm support                                                                   |
+| `SLANG_SLANG_LLVM_BINARY_URL`     | System dependent | URL specifying the location of the slang-llvm prebuilt library                               |
+| `SLANG_GENERATORS_PATH`           | ``               | Path to an installed `all-generators` target for cross compilation                           |
 
 The following options relate to optional dependencies for additional backends
 and running additional tests. Left unchanged they are auto detected, however
 they can be set to `OFF` to prevent their usage, or set to `ON` to make it an
 error if they can't be found.
 
-| Option                   | CMake hints                    | Notes                                                               |
-|--------------------------|--------------------------------|---------------------------------------------------------------------|
-| `SLANG_ENABLE_CUDA`      | `CUDAToolkit_ROOT` `CUDA_PATH` |                                                                     |
-| `SLANG_ENABLE_OPTIX`     | `Optix_ROOT_DIR`               | Requires CUDA                                                       |
-| `SLANG_ENABLE_NVAPI`     | `NVAPI_ROOT_DIR`               | Only available for builds targeting Windows                         |
-| `SLANG_ENABLE_AFTERMATH` | `Aftermath_ROOT_DIR`           | Enable Aftermath in GFX, and add aftermath crash example to project |
-| `SLANG_ENABLE_XLIB`      |                                |                                                                     |
+| Option                   | CMake hints                    | Notes                                                                                        |
+|--------------------------|--------------------------------|----------------------------------------------------------------------------------------------|
+| `SLANG_ENABLE_CUDA`      | `CUDAToolkit_ROOT` `CUDA_PATH` | Enable running tests with the CUDA backend, doesn't affect the targets Slang itself supports |
+| `SLANG_ENABLE_OPTIX`     | `Optix_ROOT_DIR`               | Requires CUDA                                                                                |
+| `SLANG_ENABLE_NVAPI`     | `NVAPI_ROOT_DIR`               | Only available for builds targeting Windows                                                  |
+| `SLANG_ENABLE_AFTERMATH` | `Aftermath_ROOT_DIR`           | Enable Aftermath in GFX, and add aftermath crash example to project                          |
+| `SLANG_ENABLE_XLIB`      |                                |                                                                                              |
+
+### Advanced options
+
+| Option                             | Default | Description                                                                                                                    |
+|------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------|
+| `SLANG_ENABLE_DX_ON_VK`            | `FALSE` | Enable running the DX11 and DX12 tests on non-warning Windows platforms via vkd3d-proton, requires system-provided d3d headers |
+| `SLANG_ENABLE_SLANG_RHI`           | `TRUE`  | Enable building and using [slang-rhi](https://github.com/shader-slang/slang-rhi) for tests                                     |
+| `SLANG_USE_SYSTEM_MINIZ`           | `FALSE` | Build using system Miniz library instead of the bundled version in [./external](./external)                                    |
+| `SLANG_USE_SYSTEM_LZ4`             | `FALSE` | Build using system LZ4 library instead of the bundled version in [./external](./external)                                      |
+| `SLANG_USE_SYSTEM_VULKAN_HEADERS`  | `FALSE` | Build using system Vulkan headers instead of the bundled version in [./external](./external)                                   |
+| `SLANG_USE_SYSTEM_SPIRV_HEADERS`   | `FALSE` | Build using system SPIR-V headers instead of the bundled version in [./external](./external)                                   |
+| `SLANG_USE_SYSTEM_UNORDERED_DENSE` | `FALSE` | Build using system unordered dense instead of the bundled version in [./external](./external)                                  |
+| `SLANG_SPIRV_HEADERS_INCLUDE_DIR`  | ``      | Use this specific path to SPIR-V headers instead of the bundled version in [./external](./external)                            |
 
 ### LLVM Support
 
 There are several options for getting llvm-support:
 
-- Use a prebuilt binary slang-llvm library: `-DSLANG_SLANG_LLVM_FLAVOR=FETCH_BINARY`,
-  this is the default
+- Use a prebuilt binary slang-llvm library:
+  `-DSLANG_SLANG_LLVM_FLAVOR=FETCH_BINARY`, this is the default
     - You can set `SLANG_SLANG_LLVM_BINARY_URL` to point to a local
       `libslang-llvm.so/slang-llvm.dll` or set it to a URL of an zip/archive
       containing such a file
@@ -177,17 +216,42 @@ generators for the build platform. Build them with the `generators` preset, and
 pass the install path to the cross building CMake invocation using
 `SLANG_GENERATORS_PATH`
 
+Non-Windows platforms:
+
+```bash
+# build the generators
+cmake --workflow --preset generators --fresh
+mkdir build-platform-generators
+cmake --install build --config Release --prefix build-platform-generators --component generators
+# reconfigure, pointing to these generators
+# Here is also where you should set up any cross compiling environment
+cmake \
+  --preset default \
+  --fresh \
+  -DSLANG_GENERATORS_PATH=build-platform-generators/bin \
+  -Dwhatever-other-necessary-options-for-your-cross-build \
+  # for example \
+  -DCMAKE_C_COMPILER=my-arch-gcc \
+  -DCMAKE_CXX_COMPILER=my-arch-g++
+# perform the final build
+cmake --workflow --preset release
+```
+
+Windows
+
 ```bash
 # build the generators
 cmake --workflow --preset generators --fresh
-mkdir my-build-platform-generators
-cmake --install build --config Release --prefix my-build-platform-generators --component generators
+mkdir build-platform-generators
+cmake --install build --config Release --prefix build-platform-generators --component generators
 # reconfigure, pointing to these generators
 # Here is also where you should set up any cross compiling environment
+# For example
+./vcvarsamd64_arm64.bat
 cmake \
   --preset default \
   --fresh \
-  -DSLANG_GENERATORS_PATH=my-build-platform-generators/bin \
+  -DSLANG_GENERATORS_PATH=build-platform-generators/bin \
   -Dwhatever-other-necessary-options-for-your-cross-build
 # perform the final build
 cmake --workflow --preset release
@@ -220,7 +284,7 @@ cmake --preset vs2022 --fresh -A arm64 -DSLANG_GENERATORS_PATH=generators/bin
 cmake --build --preset release
 ```
 
-## Building with an older CMake {#older-cmake}
+## Building with an older CMake
 
 Because older CMake versions don't support all the features we want to use in
 CMakePresets, you'll have to do without the presets. Something like the following
@@ -232,8 +296,7 @@ cmake --build build -j
 
 ## Notes
 
-[^cmake-version] below 3.25, CMake lacks the ability to mark directories as being system
-directories
-(https://cmake.org/cmake/help/latest/prop_tgt/SYSTEM.html#prop_tgt:SYSTEM),
-this leads to an inability to suppress warnings originating in the dependencies
-in `./external`, so be prepared for some additional warnings.
+[^1] below 3.25, CMake lacks the ability to mark directories as being
+system directories (https://cmake.org/cmake/help/latest/prop_tgt/SYSTEM.html#prop_tgt:SYSTEM),
+this leads to an inability to suppress warnings originating in the
+dependencies in `./external`, so be prepared for some additional warnings.