Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

update windows build instruction

CJ Pais158168983cfc
diff --git a/BUILD.md b/BUILD.md
index 21095854..dd8bb539 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -34,16 +34,31 @@ ORT_LIB_LOCATION=$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK=1 bun
#### Windows
-- Microsoft C++ Build Tools
-- Visual Studio 2019/2022 with C++ development tools
-- Or Visual Studio Build Tools 2019/2022
+- Microsoft C++ Build Tools: Visual Studio 2019/2022 with C++ development
+ tools, or Visual Studio Build Tools 2019/2022
+- [CMake](https://cmake.org/download/) (must be on `PATH`):
+
+ ```powershell
+ winget install Kitware.CMake
+ ```
+
+- [Vulkan SDK](https://vulkan.lunarg.com/sdk/home) from LunarG — required to
+ build the Vulkan GPU backend (`vulkan-shaders-gen` needs the SDK's headers
+ and `glslc`):
+
+ ```powershell
+ winget install KhronosGroup.VulkanSDK
+ ```
+
+ Open a new terminal afterward so `VULKAN_SDK` is set.
> [!IMPORTANT]
-> Windows' 260-character path limit can break the native build (the Vulkan
-> shader generator nests very deep). If `bun run tauri build` fails with
-> `MSB3491` / "path exceeds the OS max path limit", see
-> [Windows build fails with `MSB3491`](#windows-build-fails-with-msb3491--path-exceeds-260-characters)
-> in Troubleshooting.
+> Windows' 260-character path limit **will** break the native Vulkan build in
+> most checkouts (the shader generator nests very deep). Before your first
+> build, do BOTH steps in
+> [Windows build fails with path-limit errors](#windows-build-fails-with-path-limit-errors-msb3491--ftk1011--msb6003)
+> in Troubleshooting — enable long paths **and** set a short
+> `CARGO_TARGET_DIR`. Neither alone is sufficient.
#### Linux
@@ -156,43 +171,85 @@ bun run tauri build -- --bundles deb
Then install using the deb extraction method above.
-### Windows build fails with `MSB3491` / path exceeds 260 characters
+### Windows build fails with path-limit errors (`MSB3491` / `FTK1011` / `MSB6003`)
-On Windows the native build can fail partway through with an error like:
+On Windows the native build can fail partway through `transcribe-cpp-sys` with
+any of these (all the same root cause):
```
error MSB3491: Could not write lines to file "...VCTargetsPath.tlog\VCTargetsPath.lastbuildstate".
Path: ... exceeds the OS max path limit. The fully qualified file name must be less than 260 characters.
```
+```
+FileTracker : error FTK1011: could not create the new file tracking log file:
+...\vulkan-shaders-gen-build\...\cmTC_xxxxx.tlog\link.write.1.tlog.
+The system cannot find the path specified.
+```
+
+```
+error MSB6003: The specified task executable "CL.exe" could not be run.
+System.IO.DirectoryNotFoundException: Could not find a part of the path ...
+```
+
This is **not** a code or toolchain problem — it's Windows' legacy 260-character
path limit (`MAX_PATH`). The Vulkan shader generator builds as a nested CMake
sub-project (`...\vulkan-shaders-gen-prefix\src\vulkan-shaders-gen-build\...`),
which alone adds ~140 characters on top of Cargo's already-deep
`target\release\build\<crate>-<hash>\out\build\...` directory. If your checkout
-isn't very shallow, MSBuild's `.tlog` write overflows the limit. (CI doesn't hit
-this because it builds from a short root such as `D:\a\Handy`.)
+isn't very shallow, the build overflows the limit. (CI doesn't hit this because
+it builds from a short root such as `D:\a\Handy`.)
+
+**You need BOTH of the following fixes.** Different parts of the toolchain hit
+the limit in different ways: MSBuild's native `FileTracker` (`tracker.exe`)
+ignores the long-paths flag entirely, so a short target dir is required for it —
+while other .NET-side path operations overflow even from a short root unless
+long paths are enabled. Each fix alone still fails.
+
+**1. Enable Windows long paths** (one-time, machine-wide; needs an
+Administrator PowerShell):
-Either fix works; the first is the most reliable:
+```powershell
+Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name LongPathsEnabled -Value 1 -Type DWord
+git config --global core.longpaths true
+```
-**1. Build with a shorter target directory** (no admin, fixes it immediately):
+**2. Build with a short target directory:**
```powershell
+# Per-shell:
$env:CARGO_TARGET_DIR = "C:\h"
-bun run tauri build
+
+# Or persist it for all future terminals (note: redirects ALL your
+# Rust projects' build output, not just Handy):
+[Environment]::SetEnvironmentVariable('CARGO_TARGET_DIR', 'C:\h', 'User')
```
-Artifacts then land in `C:\h\release\...` instead of the repo's `src-tauri\target\`.
-Alternatively, clone the repo to a short root (e.g. `C:\Handy`).
+Artifacts then land in `C:\h\release\...` instead of the repo's
+`src-tauri\target\`.
-**2. Enable Windows long paths** (one-time, machine-wide; needs an Administrator
-PowerShell, and modern Visual Studio 2022). This removes the limit for every
-build, not just Handy:
+Open a **new terminal** afterward — both the registry flag and the persisted
+environment variable are only picked up by freshly started processes. Then
+`bun run tauri dev` and `bun run tauri build` work normally.
+
+### Windows `tauri build` fails at bundling with `program not found`
+
+If the build compiles all the way to `Built application at: ...\handy.exe` and
+then fails with:
-```powershell
-Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' LongPathsEnabled 1
-git config --global core.longpaths true
```
+Signing C:\...\handy.exe with a custom signing command
+failed to bundle project `program not found`
+```
+
+that's the code-signing step: `tauri.conf.json` configures a custom
+`signCommand` (`trusted-signing-cli`, Azure Trusted Signing) that only exists
+in the release CI environment. Local development doesn't need it:
-Restart your shell (or reboot) afterward so the change takes effect. If a build
-still trips on the limit, fall back to option 1.
+```powershell
+# Development (no bundling/signing at all):
+bun run tauri dev
+
+# Or compile a release binary without the installer/signing step:
+bun run tauri build --no-bundle
+```