| ========================================== |
| 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. |
| |
| 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:: 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:: 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:: 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. |