Merge pull request #578 from loongmiaow-pixel/docs/windows-china-install-guide

docs(install): add Windows build guide, AV troubleshooting, and China mirror details
2026-05-04 10:02:53 -05:00
parent e92403de7a 65fb815cd2
commit 0b5da7a34b
1 changed files with 158 additions and 1 deletions
@@ -61,6 +61,15 @@ Useful environment variables:
 | `DEEPSEEK_TUI_DISABLE_INSTALL=1`    | Skip the `postinstall` download entirely (CI smoke, vendored binaries)                 |
 | `DEEPSEEK_TUI_OPTIONAL_INSTALL=1`   | Don't fail `npm install` on download/extract errors — useful in CI matrices            |

+> **Slow npm download from mainland China?** If `npm install` itself is slow
+> (not just the postinstall binary download), use an npm registry mirror:
+> ```bash
+> npm config set registry https://registry.npmmirror.com
+> npm install -g deepseek-tui
+> ```
+> See also [Section 3](#3-install-via-cargo-any-tier-1-rust-target) if you
+> prefer Cargo over npm.
+
 ---

 ## 3. Install via Cargo (any Tier-1 Rust target)
@@ -76,7 +85,35 @@ cargo install deepseek-tui     --locked   # provides `deepseek-tui`
 deepseek --version
 ```

-### China / mirror-friendly Cargo registry
+### China / mirror-friendly install
+
+When installing from mainland China, configure mirrors for both **rustup**
+(the Rust toolchain installer) and **Cargo** (the package registry) to avoid
+TLS timeouts and download failures.
+
+**Step 1: Install Rust via a rustup mirror**
+
+```bash
+# PowerShell
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+(New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe')
+
+# git-bash / msys2
+export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
+export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
+./rustup-init.exe -y --default-toolchain stable
+
+# Linux / macOS
+export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
+export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+```
+
+The `RUSTUP_DIST_SERVER` and `RUSTUP_UPDATE_ROOT` environment variables must
+be set **before** running rustup-init; the toolchain download otherwise hits
+the same TLS handshake problem as the installer.
+
+**Step 2: Configure Cargo registry mirror**

 ```toml
 # ~/.cargo/config.toml
@@ -193,6 +230,69 @@ cargo build --release --target aarch64-unknown-linux-gnu -p deepseek-tui
 The same recipe works for `aarch64-unknown-linux-musl` if your distro is
 musl-based.

+### Windows build from source
+
+Building on Windows requires the **MSVC C toolchain** from
+[Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
+(the free workload-selectable installer, not the full IDE).
+
+**Prerequisites (Windows)**
+
+1. Install Visual Studio 2022 Build Tools — select the **"Desktop development
+   with C++"** workload.
+2. Install [Rust](https://rustup.rs) 1.85+ (see the
+   [China mirror instructions](#china--mirror-friendly-install) above if
+   downloading from mainland China).
+3. Install [Git for Windows](https://git-scm.com/download/win) (provides `git`
+   and the `git-bash` terminal).
+
+**Recommended terminals**: Windows Terminal, `git-bash`, or PowerShell.
+`cmd.exe` works but has a small buffer and limited PATH behavior.
+
+**Setting up the MSVC environment**
+
+Visual Studio Build Tools install `cl.exe` to a versioned directory but do
+**not** add it to `PATH` globally. You must set the environment manually or
+use a Developer Command Prompt. The required variables are:
+
+```powershell
+# Adjust version numbers to match your installation
+$msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207"
+$sdk   = "C:\Program Files (x86)\Windows Kits\10"
+$sdkv  = "10.0.26100.0"
+
+$env:INCLUDE  = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared"
+$env:LIB      = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64"
+$env:LIBPATH  = "$msvc\lib\x64;$msvc\atlmfc\lib\x64"
+$env:CC       = "$msvc\bin\Hostx64\x64\cl.exe"
+$env:CXX      = "$msvc\bin\Hostx64\x64\cl.exe"
+$env:PATH     = "$msvc\bin\Hostx64\x64;$env:PATH"
+```
+
+Alternatively, open a **"Developer Command Prompt for VS 2022"** (available
+from the Start Menu after installing Build Tools), which runs `vcvars64.bat`
+to configure all of the above automatically. Then add `cargo` to `PATH` inside
+that session and run `cargo build` from the project root.
+
+**Cargo registry mirror** — on Windows the mirror config goes to
+`%USERPROFILE%\.cargo\config.toml`. See [Step 2 above](#china--mirror-friendly-install).
+
+**Build**
+
+```bash
+git clone https://github.com/Hmbown/DeepSeek-TUI.git
+cd DeepSeek-TUI
+set CARGO_HTTP_CHECK_REVOKE=false   # may be needed behind some Chinese ISPs
+cargo build --release
+```
+
+Both binaries appear in `target\release\deepseek.exe` and
+`target\release\deepseek-tui.exe`.
+
+> **Prefer `npm install -g` on Windows unless you need to modify source.**
+> The npm package pulls prebuilt binaries and avoids the C toolchain
+> dependency entirely — see [Section 2](#2-install-via-npm-recommended).
+
 ---

 ## 6. Troubleshooting
@@ -245,6 +345,63 @@ sudo apt-get install -y build-essential pkg-config libdbus-1-dev
 `npm i -g` installs into `$(npm prefix -g)/bin`; make sure that directory is on
 your shell's `PATH`. With nvm: `nvm use --lts && hash -r`.

+### Windows: `TLS handshake eof` or `CRYPT_E_REVOCATION_OFFLINE` from `rustup-init`
+
+The TLS handshake to `static.rust-lang.org` fails from behind the GFW or
+certain Chinese ISPs. Set the rustup mirror environment variables **before**
+running the installer:
+
+```bash
+# git-bash / msys2
+export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
+export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
+./rustup-init.exe -y --default-toolchain stable
+```
+
+If you see `CRYPT_E_REVOCATION_OFFLINE` from Cargo after Rust is installed,
+also set `CARGO_HTTP_CHECK_REVOKE=false` during `cargo build`.
+
+### Windows: MSVC compiler (`cl.exe`) not found during `cargo build`
+
+Visual Studio Build Tools do not add `cl.exe` to the global `PATH`. Either:
+
+1. Open **"Developer Command Prompt for VS 2022"** from the Start Menu, add
+   `%USERPROFILE%\.cargo\bin` to `PATH` in that window, and run `cargo build`
+   from there; or
+2. Set the MSVC environment variables manually — see the
+   [Windows build from source](#windows-build-from-source) section for the
+   PowerShell snippet.
+
+Verify the compiler is reachable: `cl.exe /?` should print help text.
+
+### Windows: `拒绝访问 (os error 5)` when Cargo executes build scripts
+
+Third-party antivirus software (Huorong, 360, Kaspersky, etc.) may block
+Cargo from executing freshly-compiled build-script binaries
+(e.g. `libsqlite3-sys`, `aws-lc-sys`, `instability`). The error is
+path-agnostic — moving `target-dir` does not help.
+
+**Symptoms**: `could not execute process ... build-script-build (never executed)`
+
+**Workarounds** (pick one):
+
+1. **Add the project's `target/` directory to your AV exclusions list.**
+2. **Close the antivirus software temporarily** during `cargo build`.
+3. **Use `npm install -g deepseek-tui` instead** — the npm package ships
+   prebuilt binaries and skips the Cargo build entirely
+   ([Section 2](#2-install-via-npm-recommended)).
+4. **Use `cargo install deepseek-tui-cli --locked`** from crates.io — this
+   changes the binary path, which some AV tools treat differently.
+
+To verify that the build-script binary itself is valid (not corrupted), locate
+it under `target/debug/build/<crate>/build-script-build` and run it manually:
+
+```bash
+target/debug/build/libsqlite3-sys-*/build-script-build
+# If this runs but panics with "NotPresent" (no C compiler), the binary is
+# fine — the AV is blocking Cargo's process-spawning path specifically.
+```
+
 ---

 ## 7. Verifying your install