README: update & move docs to machengine.org/pkg/mach-dxcompiler

Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
hexops · Feb 10, 2024 · 4ccd240 · 4ccd240
1 parent bd0cfbe
commit 4ccd240
Showing 1 changed file with 14 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,8 @@
-# mach-dxcompiler: DXC built using Zig
+# mach-dxcompiler
 
-This project builds/cross-compiles static binaries of Microsoft/DirectXShaderCompiler (`dxcompiler` / DXC, the official HLSL compiler for DirectX) for many OS/Arch.
+The DirectX shader compiler, built better.
 
+See ['Building the DirectX shader compiler better than Microsoft?'](https://devlog.hexops.com/2024/building-the-directx-shader-compiler-better-than-microsoft/) for details/background information.
 ## Experimental
 
 This is an **experimental** project according to [our stability guarantees](https://machengine.org/about/stability):
@@ -10,62 +11,23 @@ This is an **experimental** project according to [our stability guarantees](http
 
 **Tracking issue:** https://github.com/hexops/mach/issues/1094
 
-## Why?
+## Features
 
-The HLSL compiler shipped with Windows by default is called FXC, it does not support SM6.0 (DirectX 12+ features), is slow, has very poor codegen, and is officially deprected by Microsoft.
+* Statically linked `dxcompiler` library and `dxc` executables.
+* Zero dependency on proprietary `dxil.dll` code-signing blob (see: [Mach Siegbert Vogt DXCSA](https://github.com/hexops/DirectXShaderCompiler/blob/4190bb0c90d374c6b4d0b0f2c7b45b604eda24b6/tools/clang/tools/dxcompiler/MachSiegbertVogtDXCSA.cpp#L178))
+* Built using `build.zig` instead of 10k+ LOC CMake build system.
+* [Prebuilt binaries](https://github.com/hexops/mach-dxcompiler/releases) provided for many OS/arch.
+* Binaries for macOS and aarch64 Linux (first ever in history), among others.
+* [Simple C API](https://github.com/hexops/mach-dxcompiler/blob/main/src/mach_dxc.h) bundled into library as an alternative to the traditional COM API.
 
-[Microsoft/DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler) (DXC) is a fork of LLVM/Clang, and the successor to FXC with new Microsoft eccentricities such as using their own C++ testing framework (TAEF), Tracing library (ETW), and various dependencies on the Windows SDK and MSVC compiler. The fork is based on LLVM/Clang 3.7, which is over 7 years old and Microsoft is not able to update it because DirectX drivers directly expect DXIL, which is just _specifically_ LLVM v3.7's IR format. They are now bound to this old/outdated IR format, and are [making an effort to add DXIL/LLVM IR v3.7 as a backend to modern Clang versions](https://discourse.llvm.org/t/rfc-adding-hlsl-and-directx-support-to-clang-llvm/60783) upstream so that modern LLVM/Clang can be used without requiring all GPU drivers having to support a newer LLVM IR version.
+## Documentation
 
-The [Microsoft/DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler) fork may be compiled on Windows using MSVC, and on macOS/Linux using clang. However, the codebase is not setup to support [static library compilation](https://github.com/microsoft/DirectXShaderCompiler/issues/4766) and building on Windows is rather involved: it requires using a special HLSL Console, `hctbuild` wrapper, Visual Studio 2019, has dependencies on the Windows SDK, Windows Driver development kits, MSVC, etc.
+[machengine.org/pkg/mach-dxcompiler](https://machengine.org/pkg/mach-dxcompiler)
 
-`zig cc` and `zig c++` are clang-compatible C/C++ compilers, but use MinGW windows headers which are not 100% compatible with Microsoft's own [proprietary](https://github.com/microsoft/win32metadata/issues/766#issuecomment-1103518587) Windows SDK headers. We would like to use these MinGW headers and the `-gnu` clang ABI target so that game binaries can be cross-compiled from Linux/macOS -> Windows effortlessly.
+## Join the community
 
-## How?
-
-We maintain a fork of [DirectXCompiler](https://github.com/hexops/DirectXShaderCompiler) with various modifications to CMake build configurations and headers to support building only the `dxcompiler` library with `zig cc` and the MinGW headers on Windows.
-
-Subsequently, _this project_ provides CMake toolchains which use `zig cc`, and provides a `zig build` script to invoke `cmake` with these toolchains and the right configuration options for the given target.
-
-This repository _also_ provides lightweight Zig bindings to use DXC as a Zig API.
-
-## Usage
-
-By default, `zig build` will build the Zig bindings to DXC and will link against prebuilt binaries of DXC fetched from our CI build system. This is so that Zig developers do not need to wait the ~5 minutes or so that compiling DXC/LLVM takes, as it is a large C++ codebase.
-
-To build a static `dxcompiler` and headers from source, use:
-
-```
-zig build install -Dfrom-source=true
-```
-
-You may wish to use the following options when building:
-
-| Option                         | Description                                                                                     |
-| ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `-from-source=true`            | Build from source                                                                               |
-| `-Dcpu=x86_64_v2`              | e.g. do not emit AVX2 instructions, see [this issue](https://github.com/hexops/mach/issues/989) |
-| `-Doptimize=ReleaseFast`       | Release mode / perform release optimizations                                                    |
-| `-Dtarget=x86_64-linux-gnu`    | Cross-compile for 64-bit Linux GNU libc                                                         |
-| `-Dtarget=x86_64-linux-musl`   | Cross-compile for 64-bit Linux musl libc                                                        |
-| `-Dtarget=aarch64-linux-gnu`   | Cross-compile for ARM Linux GNU libc                                                            |
-| `-Dtarget=aarch64-linux-musl`  | Cross-compile for ARM Linux musl libc                                                           |
-| `-Dtarget=x86_64-windows-gnu`  | Cross-compile for Windows GNU/MinGW ABI                                                         |
-| `-Dtarget=x86_64-windows-msvc` | Cross-compile for Windows MSVC ABI                                                              |
-| `-Dtarget=aarch64-macos`       | Cross-compile for macOS Apple Silicon                                                           |
-| `-Dtarget=x86_64-macos`        | Cross-compile for macOS Intel                                                                   |
-
-**Note:**
-
-* Building from source requires `cmake` and `ninja`.
-* Linux->Windows cross-compilation _from source_ is only supported with a case-insensitive filesystem.
-  * MacOS and Windows both use case-insensitive filesystems, but most Linux distributions do not by default.
-  * Microsoft uses mixed case `#include`s throughout their headers and relies on this behavior.
-* `-Dtarget=x86_64-windows-msvc` requires the Windows SDK and may only be used on a Windows host machine.
+Join the [Mach community on Discord](https://discord.gg/XNG3NZgCqp) to discuss this project, ask questions, get help, etc.
 
 ## Issues
 
 Issues are tracked in the [main Mach repository](https://github.com/hexops/mach/issues?q=is%3Aissue+is%3Aopen+label%3Adxcompiler).
-
-## Community
-
-Join the Mach engine community [on Discord](https://discord.gg/XNG3NZgCqp) to discuss this project, ask questions, get help, etc.