|
| 1 | +# Windows One-Click Installer (WSL2 + conda-forge) |
| 2 | + |
| 3 | +A lightweight installer that brings ABACUS to Windows via WSL2 and |
| 4 | +conda-forge. No C++ toolchain, no MPI build, no manual dependency juggling — |
| 5 | +run `install-abacus.bat` once and type `abacus` from any Windows terminal. |
| 6 | + |
| 7 | +The scripts live in the repository under `tools/windows/`. This page is the |
| 8 | +user-facing documentation for the same scripts. |
| 9 | + |
| 10 | +## How it works |
| 11 | + |
| 12 | +ABACUS depends on a heavy Linux-native scientific stack (OpenMPI, ScaLAPACK, |
| 13 | +ELPA, FFTW, libxc, OpenBLAS, …) that is painful to build natively on Windows. |
| 14 | +Instead of porting, this installer provisions a standard Linux environment |
| 15 | +inside WSL2 and exposes it through thin Windows launchers. |
| 16 | + |
| 17 | +The pipeline, end to end: |
| 18 | + |
| 19 | +1. **`install-abacus.bat`** (runs on Windows, requires admin) |
| 20 | + - Checks the Windows build (≥ 19041) and whether WSL is installed; if not, |
| 21 | + runs `wsl --install --no-launch` and asks the user to reboot once. |
| 22 | + - Optionally enables TUNA (Tsinghua) mirrors for users in Mainland China. |
| 23 | + - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL |
| 24 | + registry key `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This |
| 25 | + is immune to UTF-16 parsing pitfalls and to Store appx leftovers that |
| 26 | + can make `wsl -d <name> -- true` falsely report success. |
| 27 | + - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is |
| 28 | + missing, then verifies the registry entry appeared. |
| 29 | + - Invokes `provision.sh` inside the distribution, stripping any `\r` |
| 30 | + bytes on the fly (`sed 's/\r$//' script | bash`) so Windows line |
| 31 | + endings don't break shell parsing. |
| 32 | + - Writes two small launcher `.cmd` files and adds them to the user PATH |
| 33 | + via PowerShell (avoiding `setx`'s 1024-character truncation). |
| 34 | + |
| 35 | +2. **`provision.sh`** (runs as root inside the WSL distribution) |
| 36 | + - Optionally rewrites `/etc/apt/sources.list` to TUNA. |
| 37 | + - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, |
| 38 | + bzip2). |
| 39 | + - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases |
| 40 | + mirror) and installs it to `/opt/abacus-miniforge`. |
| 41 | + - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA |
| 42 | + conda-forge channel) — a single package pulls in the entire scientific |
| 43 | + runtime. conda-forge ships `abacus` for `linux-64` and `linux-aarch64`, |
| 44 | + which is exactly what WSL2 provides. |
| 45 | + - Writes two system-wide launchers, `/usr/local/bin/abacus` and |
| 46 | + `/usr/local/bin/abacus-mpi`, that activate the env and exec the real |
| 47 | + binary. Both set `OMP_NUM_THREADS=1` by default to avoid thread |
| 48 | + oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE |
| 49 | + "allow run as root" environment variables and passes |
| 50 | + `--allow-run-as-root` to `mpirun`, so the default WSL root user can |
| 51 | + launch parallel jobs without creating a non-root user. |
| 52 | + |
| 53 | +3. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) |
| 54 | + - Added to `%LOCALAPPDATA%\ABACUS\bin` and the user PATH. |
| 55 | + - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` |
| 56 | + so thread-count overrides set on the Windows side are visible inside WSL. |
| 57 | + - Body is just: |
| 58 | + ``` |
| 59 | + wsl -d Ubuntu-22.04 --cd "%CD%" -- abacus %* |
| 60 | + ``` |
| 61 | + `--cd "%CD%"` maps the current Windows directory (`C:\…\case`) to its |
| 62 | + WSL path (`/mnt/c/…/case`), so users can `cd` into a case directory in |
| 63 | + `cmd`/PowerShell/Terminal and just type `abacus`. |
| 64 | +
|
| 65 | +4. **`uninstall-abacus.bat`** |
| 66 | + - Reads `install-state.txt` (written by the installer) to learn whether |
| 67 | + the Ubuntu-22.04 distribution was pre-existing or added by us. |
| 68 | + - If it was added by us, prompts whether to `wsl --unregister` the entire |
| 69 | + distribution, or to only wipe `/opt/abacus-miniforge` and the launchers. |
| 70 | + - If it was pre-existing, only the ABACUS files inside are removed. |
| 71 | + - Cleans Windows-side launchers and removes the bin directory from the |
| 72 | + user PATH. |
| 73 | + - Does **not** touch WSL itself (runtime, Windows optional features, or |
| 74 | + other distributions). See *Uninstallation* below for how to fully |
| 75 | + remove WSL if you want to. |
| 76 | +
|
| 77 | +## Requirements |
| 78 | +
|
| 79 | +- Windows 10 build 19041 (2004) or newer, or any Windows 11. |
| 80 | +- Administrator privileges for the first run (to enable WSL features). |
| 81 | +- Virtualization enabled in BIOS/UEFI. |
| 82 | +- ~2 GB free disk space (Ubuntu + conda env). |
| 83 | +- Network access to GitHub and conda-forge, or to TUNA if you choose the |
| 84 | + China mirror option. |
| 85 | +
|
| 86 | +## Installation |
| 87 | +
|
| 88 | +1. Clone or download this repository. |
| 89 | +2. In `tools/windows/`, right-click `install-abacus.bat` → **Run as administrator**. |
| 90 | +3. Answer the China-mirror prompt (`y` recommended inside Mainland China). |
| 91 | +4. If this is the first time WSL is installed on the machine, the script |
| 92 | + will ask you to reboot and run it again. |
| 93 | +5. Wait for `[*] Provisioning ABACUS …` to finish (5–15 minutes on first |
| 94 | + run; most of it is the conda-forge download). |
| 95 | +6. When you see `Installation complete!`, **open a new terminal window** |
| 96 | + (so the updated PATH takes effect) and verify: |
| 97 | + ``` |
| 98 | + abacus --version |
| 99 | + ``` |
| 100 | +
|
| 101 | +## Usage |
| 102 | +
|
| 103 | +Serial run in any case directory: |
| 104 | +
|
| 105 | +``` |
| 106 | +cd path\to\my_case |
| 107 | +abacus |
| 108 | +``` |
| 109 | +
|
| 110 | +Parallel run with 4 MPI ranks: |
| 111 | +
|
| 112 | +``` |
| 113 | +abacus-mpi -n 4 |
| 114 | +``` |
| 115 | +
|
| 116 | +Hybrid MPI + OpenMP (e.g. 4 MPI ranks × 2 threads each): |
| 117 | +
|
| 118 | +``` |
| 119 | +set OMP_NUM_THREADS=2 |
| 120 | +abacus-mpi -n 4 |
| 121 | +``` |
| 122 | +
|
| 123 | +Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in |
| 124 | +your Windows shell and the launcher will forward the value into WSL through |
| 125 | +`WSLENV`. Unset, it defaults to 1 — a safe choice when running pure MPI. |
| 126 | +
|
| 127 | +Interactive Linux shell (for advanced debugging, manually running |
| 128 | +`mpirun`, inspecting logs, etc.): |
| 129 | +
|
| 130 | +``` |
| 131 | +wsl -d Ubuntu-22.04 |
| 132 | +``` |
| 133 | +
|
| 134 | +Inside the shell you can `conda activate abacus_env` to get access to |
| 135 | +`mpirun`, `mpiexec`, and other tools from the conda environment. |
| 136 | +
|
| 137 | +## Uninstallation |
| 138 | +
|
| 139 | +### Standard: remove ABACUS only |
| 140 | +
|
| 141 | +Run `uninstall-abacus.bat`. This handles the common case: |
| 142 | +
|
| 143 | +- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers |
| 144 | + inside WSL. |
| 145 | +- If the installer added the `Ubuntu-22.04` distribution, asks whether you |
| 146 | + also want to `wsl --unregister` it (pick `y` to reclaim the disk space, |
| 147 | + `n` to keep the Linux environment for other uses). |
| 148 | +- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from |
| 149 | + your user PATH. |
| 150 | +
|
| 151 | +This is enough for almost every user. WSL itself and any *other* WSL |
| 152 | +distributions you have stay untouched — important because WSL is commonly |
| 153 | +shared with Docker Desktop, VS Code Remote, and other toolchains. |
| 154 | +
|
| 155 | +### Nuclear: remove WSL itself |
| 156 | +
|
| 157 | +Only do this if you truly have no other use for WSL on this machine. |
| 158 | +Removing WSL will break Docker Desktop, VS Code Remote-WSL, any other |
| 159 | +Linux distros you have, and so on. Run the following in an elevated |
| 160 | +PowerShell: |
| 161 | +
|
| 162 | +```powershell |
| 163 | +# 1. Unregister every WSL distribution (this wipes all their files). |
| 164 | +wsl --list --quiet | ForEach-Object { wsl --unregister $_.Trim() } |
| 165 | +
|
| 166 | +# 2. Uninstall the WSL runtime itself (wsl.exe + the Linux kernel package). |
| 167 | +# This is Microsoft's official command; it does not disable the Windows |
| 168 | +# optional features and does not touch any distro appx packages. |
| 169 | +wsl --uninstall |
| 170 | +
|
| 171 | +# 3. Optionally remove leftover distribution appx packages from the Store |
| 172 | +# (e.g. "Ubuntu 22.04 LTS"). `wsl --unregister` deletes the data only; |
| 173 | +# the Store app that installs the distro is separate. |
| 174 | +Get-AppxPackage *Ubuntu* | Remove-AppxPackage |
| 175 | +
|
| 176 | +# 4. Optional: disable the Windows optional features (requires a reboot). |
| 177 | +# Skip this step if anything else on the machine still uses Hyper-V |
| 178 | +# virtualization (Docker Desktop, Windows Sandbox, Hyper-V VMs, ...). |
| 179 | +dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart |
| 180 | +dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart |
| 181 | +
|
| 182 | +# 5. Remove user config if present. |
| 183 | +Remove-Item "$env:UserProfile\.wslconfig" -ErrorAction SilentlyContinue |
| 184 | +
|
| 185 | +# 6. Reboot to finalize. |
| 186 | +Restart-Computer |
| 187 | +``` |
| 188 | + |
| 189 | +After the reboot `wsl.exe` no longer exists. If you also ran step 4, the |
| 190 | +Hyper-V virtualization layer used by WSL2 is disabled. |
| 191 | + |
| 192 | +> On older Windows builds where `wsl --uninstall` is not available (WSL |
| 193 | +> shipped via the in-box `wsl.exe` rather than the Store package), use |
| 194 | +> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a |
| 195 | +> fallback for step 2. |
| 196 | +
|
| 197 | +## Performance notes |
| 198 | + |
| 199 | +- Files under `/mnt/c/...` are served through the 9P protocol and are |
| 200 | + noticeably slower than native ext4. For heavy I/O (large SCF, MD |
| 201 | + trajectories), run the case from inside the WSL filesystem: |
| 202 | + ``` |
| 203 | + wsl -d Ubuntu-22.04 |
| 204 | + cp -r /mnt/c/path/to/case ~/case |
| 205 | + cd ~/case |
| 206 | + abacus |
| 207 | + ``` |
| 208 | +- The first `wsl` invocation after a boot triggers a 10–30 s VM cold start. |
| 209 | +- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network |
| 210 | + overhead between ranks — you get near-native parallel performance. |
| 211 | + |
| 212 | +## File layout |
| 213 | + |
| 214 | +``` |
| 215 | +tools/windows/ |
| 216 | +├── install-abacus.bat # Windows entry point (admin, interactive) |
| 217 | +├── uninstall-abacus.bat # Clean removal, optionally including the distro |
| 218 | +├── provision.sh # Linux-side installer (runs as root in WSL) |
| 219 | +├── .gitattributes # Pin *.sh to LF, *.bat/*.cmd to CRLF |
| 220 | +└── README.md # Mirror of this page, shipped with the scripts |
| 221 | +``` |
| 222 | + |
| 223 | +Artifacts created at install time: |
| 224 | + |
| 225 | +``` |
| 226 | +%LOCALAPPDATA%\ABACUS\ |
| 227 | +├── bin\ |
| 228 | +│ ├── abacus.cmd # Windows launcher (serial) |
| 229 | +│ └── abacus-mpi.cmd # Windows launcher (MPI) |
| 230 | +└── install-state.txt # Records whether we created the WSL distro |
| 231 | +
|
| 232 | +Inside WSL (Ubuntu-22.04): |
| 233 | +/opt/abacus-miniforge/ # Private Miniforge install |
| 234 | +/opt/abacus-miniforge/envs/abacus_env/ # conda env holding abacus |
| 235 | +/usr/local/bin/abacus, /usr/local/bin/abacus-mpi # Linux-side launchers |
| 236 | +``` |
| 237 | + |
| 238 | +## Design choices and trade-offs |
| 239 | + |
| 240 | +- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's |
| 241 | + MPI + ScaLAPACK + ELPA stack has no reliable native Windows build. Going |
| 242 | + through WSL2 lets us reuse the Linux binaries conda-forge already ships, |
| 243 | + turning a multi-week porting problem into a 200-line shell script. |
| 244 | +- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is |
| 245 | + built against glibc from 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks |
| 246 | + mismatches; pinning the version keeps the install reproducible. |
| 247 | +- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** |
| 248 | + Clean uninstall path, clear ownership, and doesn't interfere with a |
| 249 | + user's personal conda install if they later add one inside the same |
| 250 | + distribution. |
| 251 | +- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from |
| 252 | + ~10 min to ~1 min, but balloons the installer from a few KB of scripts |
| 253 | + to 300–500 MB, requires CI infrastructure, and needs code signing to |
| 254 | + avoid SmartScreen warnings. A scripted online installer is the |
| 255 | + lowest-maintenance starting point; the pre-built rootfs path remains |
| 256 | + open for a future v1. |
0 commit comments