206 строки
7.8 KiB
ReStructuredText
206 строки
7.8 KiB
ReStructuredText
==========================================
|
|
Building and Testing DirectXShaderCompiler
|
|
==========================================
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 3
|
|
|
|
.. 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 <https://github.com/microsoft/DirectXShaderCompiler/blob/main/README.md>`_.
|
|
|
|
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
|
|
-------------
|
|
|
|
* [Git](http://git-scm.com/downloads).
|
|
* [Python](https://www.python.org/downloads/) - version 3.x is required
|
|
* [CMake](https://cmake.org/download/) - version >= 3.17.2
|
|
* The bundled version with Visual Studio works for Windows.
|
|
* The C++ 14 compiler and runtime of your choosing.
|
|
* DXC is known to compile with recent versions of GCC, Clang and MSVC.
|
|
|
|
Building on windows additionally requires:
|
|
|
|
* [Visual Studio 2019 or later](https://www.visualstudio.com/downloads) - select the following workloads:
|
|
* Universal Windows Platform Development
|
|
* Desktop Development with C++
|
|
* [Windows SDK](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk) - version 10.0.18362.0 or newer
|
|
* [Windows Driver Kit](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) - same version as the SDK
|
|
|
|
Note: DXC uses submodules for some external dependencies. You must initialize
|
|
the submodules in order to build DXC:
|
|
|
|
.. code-block:: sh
|
|
git submodule update --init --recursive
|
|
|
|
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:
|
|
|
|
.. code-block:: sh
|
|
|
|
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:
|
|
|
|
.. code-block:: sh
|
|
|
|
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:
|
|
|
|
.. code-block:: sh
|
|
|
|
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:
|
|
|
|
#. CMAKE - For options defined by CMake itself which apply across the entire
|
|
configuration.
|
|
#. LLVM - For options defined by LLVM which DXC has inherited. These apply
|
|
across the entire DXC codebase.
|
|
#. CLANG - For options defined in the clang sub-project which DXC has inherited.
|
|
These options apply across just the tools/clang subdirectory.
|
|
#. 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 `utils\hct\hctshortcut.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 utils\hct\hctshortcut.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.
|
|
|
|
.. code-block:: sh
|
|
|
|
hctbuild
|
|
|
|
You can also run tests with this command.
|
|
|
|
.. code-block:: sh
|
|
|
|
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`
|