5e8ab95a74
Users in the Chinese mainland find download speeds are too slow and need an option to use GitHub download mirroring sites like fastgit.org, this makes it possible to configure that using an environment variable. See the documentation for more details. Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
58 lines
3.3 KiB
Markdown
58 lines
3.3 KiB
Markdown
# Known issues
|
|
|
|
If you're trying the commands [on the homepage](https://hexops.com/mach/) and running into issues, it may be one of these known issues.
|
|
|
|
## Windows: File not found
|
|
|
|
If you encounter an error like this:
|
|
|
|
|
|
|
|
Windows does not have symlinks enabled, or Git is not configured to use them. This is very annoying and [has been reported to Microsoft](https://twitter.com/slimsag/status/1508114938933362688).
|
|
|
|
**Two solutions:**
|
|
|
|
1. (recommended) Build a native Windows binary by cross-compiling from WSL -> Windows:
|
|
* `cd mach/gpu`
|
|
* `zig build -Dtarget=x86_64-windows`
|
|
* Run the exe in `zig-out/bin/` outside of WSL.
|
|
2. Enable symlinks in Windows:
|
|
* [Turn on Development Mode](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development)
|
|
* [Ensure symlinks are installed in Git](https://stackoverflow.com/a/59761201) `git config --global core.symlinks true`
|
|
* Re-clone the repository and try again.
|
|
|
|
## Windows: "SSL certificate problem: unable to get local issuer certificate"
|
|
|
|
This is a curl SSL CA issue, you may want to Google for proper solutions on your system. That said, you can `set CURL_INSECURE=true` and retry to disable SSL verification if you want to workaround the issue.
|
|
|
|
## Linux: `Error: Couldn't load Vulkan. Searched /tmp/mach/gpu/zig-out/bin/libvulkan.so.1`
|
|
|
|
We're aware of a bug failing to find `libvulkan.so` on some Linux distros such as [Guix](https://guix.gnu.org/).
|
|
|
|
```
|
|
Error: Couldn't load Vulkan. Searched /tmp/mach/gpu/zig-out/bin/libvulkan.so.1, /tmp/mach/gpu/zig-out/bin/libvulkan.so.1, libvulkan.so.1.
|
|
at operator() (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:198)
|
|
at Initialize (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:203)
|
|
at Create (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:165)
|
|
at operator() (/home/runner/work/mach-gpu-dawn/mach-gpu-dawn/libs/dawn/src/dawn/native/vulkan/BackendVk.cpp:420)
|
|
|
|
found Null backend on CPU adapter: Null backend,
|
|
```
|
|
|
|
This is [a bug in Dawn](https://github.com/NixOS/nixpkgs/issues/150398), you can workaround it for now by specifying the path to `libvulkan.so` on your system `LD_PRELOAD` like e.g.:
|
|
|
|
```
|
|
LD_PRELOAD=/run/current-system/profile/lib/libvulkan.so zig-out/bin/gpu-hello-triangle
|
|
```
|
|
|
|
## Choosing a different GitHub download mirror (Chinese users)
|
|
|
|
**Background**: `zig build` on the first time around will download a 20-30MB file of Dawn (Google's WebGPU implementation) from https://github.com/hexops/mach-gpu-dawn/releases - the build system uses `curl` to do this automatically. You can of course build Dawn from source using the `-Ddawn-from-source=true` flag, but this will require a clone of the Dawn sources which are a larger download and takes a few minutes to build as it is a large C++ codebase.
|
|
|
|
Users in Chinese mainland may find that download speeds to github.com are too slow (hours to download a 30 MB file), and apparently it is common to use GitHub mirror sites like https://fastgit.org to download files from GitHub.
|
|
|
|
You can have Mach use such websites by setting an environment variable e.g.:
|
|
|
|
```sh
|
|
MACH_GITHUB_BASE_URL=https://download.fastgit.org
|
|
```
|