Skip to content

Latest commit

 

History

History
205 lines (153 loc) · 7.83 KB

BuildingAndTestingDXC.rst

File metadata and controls

205 lines (153 loc) · 7.83 KB
Raw

Building and Testing DirectXShaderCompiler

Warning

This document describes a new and slightly experimental build process building DXC and using LLVM's LIT tool to run DXC's tests. This workflow is complete on Linux and Unix platforms, but is incomplete but usable on Windows. Instructions for building on Windows are available in the repository readme.

Introduction

DXC's build is configured using CMake and should be buildable with any preferred generator. In subsequent sections we will describe workflows using Ninja and Visual Studio. The Ninja workflow should also apply to makefile generators with minimal adaption.

Prerequisites

Building on windows additionally requires:

Note: DXC uses submodules for some external dependencies. You must initialize the submodules in order to build DXC:

Basic CMake Usage

When building DXC there are a bunch of CMake options which must be set. To simplify configuration those options are collected into a CMake cache script which can be passed into the CMake tool using the -C flag. Cache scripts run before any other CMake script evaluation and can be used to initialize variables for the configuration process.

All of the most basic CMake configurations for DXC follow a similar format to:

cmake <Repository Root> \
  -C <Repository Root>/cmake/caches/PredefinedParams.cmake \
  -DCMAKE_BUILD_TYPE=<Build Type> \
  -G <Generator>

Useful CMake Flags

By default CMake will place the generated build output files in the directory you run CMake in. Our build system disallows running CMake in the root of the repository so you either need to create an alternate directory to run CMake in, or you can use the CMake -B <path> flag to direct CMake to place the generated files in a different location.

Generating a Visual Studio Solution

Open a Visual Stuido command prompt and run:

cmake <Repository Root> \
  -B <Path to Output> \
  -C <Repository Root>/cmake/caches/PredefinedParams.cmake \
  -DCMAKE_BUILD_TYPE=<Build Type> \
  -G "Visual Studio 17 2022"

Open the resulting LLVM.sln placed under the <Path to Output>. DXC should build successfully with either the Visual Studio 17 2022 or Visual Studio 16 2019 generators.

Using Visual Studio's CMake Integration

Open Visual Studio and select "Open a local folder". Open the folder DXC is cloned into. If Visual Studio does not start automatically configuring the build you may need to go to the "Project" menu and select "CMake Workspace Settings" and add "enableCMake"; true to the JSON configuration file.

After CMake configuration completes you should be able to toggle the "Solution Explorer" into "CMake Targets View" to see the available build targets.

Generating Ninja or Makefiles

In your preferred terminal run:

cmake <Repository Root> \
  -B <Path to Output> \
  -C <Repository Root>/cmake/caches/PredefinedParams.cmake \
  -DCMAKE_BUILD_TYPE=<Build Type> \
  -G Ninja

You may substitute Ninja for Unix Makefiles to generate a makefile build. After generation completes you can run ninja or make as appropriate.

Building and Running Tests

With the LIT-based testing solution, builds and tests are all run through the generated build system. Regardless of which tool you use to build DXC you should have the following targets available:

llvm-test-depends Builds all the binaries used by the tests. clang-test-depends Builds all the binaries used by the clang tests. test-depends Builds all the binaries used by all the tests. check-llvm Runs the LLVM tests after rebuilding any required out-of-date targets. check-clang Runs the Clang tests after rebuilding any required out-of-date targets. check-all Runs all available tests after rebuilding any out-of-date targets.

Useful CMake Options

By convention CMake options are all capital, underscore separated words, and the first word signifies what the option applies to. In the DXC codebase there are four commonly used option prefixes:

  1. CMAKE - For options defined by CMake itself which apply across the entire configuration.
  2. LLVM - For options defined by LLVM which DXC has inherited. These apply across the entire DXC codebase.
  3. CLANG - For options defined in the clang sub-project which DXC has inherited. These options apply across just the tools/clang subdirectory.
  4. DXC - For DXC-specific options, which may apply across the entire codebase.
CMAKE_BUILD_TYPE:STRING
Sets the build type for single-configuration generators (i.e. Ninja and makefiles) Possible values are Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio or Xcode the user sets the build type with the IDE settings.
LLVM_USE_LINKER:STRING
When building with Clang or GCC this option allows overriding the default linker used by setting the -fuse-ld= flag. This may be important for Linux users on systems where the system linker is ld.bfd as linking DXC with debug information can be very memory intensive.
LLVM_PARALLEL_COMPILE_JOBS:STRING
When building with Ninja, this option can be used to limit the number of concurrent compilation jobs.
LLVM_PARALLEL_LINK_JOBS:STRING
When building with Ninja, this option can be used to limit number of concurrent link jobs.
DXC_COVERAGE:BOOL
This option must be passed before the -C flag to set the PredefinedParams cache script because it is handled by the cache script. This option enables building DXC with code coverage instrumentation and build targets to generate code coverage reports. With this setting enabled the generate-coverage-report target is added to the build which produces a static HTML page with code coverage analysis results.

Legacy Windows Build Tooling

After cloning the project, you can set up a build environment shortcut by double-clicking the utilshcthctshortcut.js file. This will create a shortcut on your desktop with a default configuration. If your system doesn't have the requisite association for .js files, this may not work. If so, open a cmd window and invoke: wscript.exe utilshcthctshortcut.js.

Tests are built using the TAEF framework which is included in the Windows Driver Kit.

To build, run this command on the HLSL Console.

hctbuild

You can also run tests with this command.

hcttest

Some tests will run shaders and verify their behavior. These tests also involve a driver that can execute these shaders. See the next section on how this should be currently set up.

To see a list of additional commands available, run hcthelp