diff --git a/docs/index.rst b/docs/index.rst index ae96c406632..a5209940347 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,6 +26,7 @@ the developments and applications of novel machine-learning-assisted DFT methods :caption: Quick Start quick_start/easy_install + quick_start/windows_installer quick_start/hands_on quick_start/input quick_start/output diff --git a/docs/quick_start/easy_install.md b/docs/quick_start/easy_install.md index aae9bca3088..90128a707b1 100644 --- a/docs/quick_start/easy_install.md +++ b/docs/quick_start/easy_install.md @@ -1,6 +1,6 @@ # Easy Installation -This guide helps you install ABACUS with basic features. **For DeePKS, DeePMD and Libxc support, or building with `make`, please refer to [the advanced installation guide](../advanced/install.md)** after going through this page. We recommend building ABACUS with `cmake` to avoid dependency issues. We recommend compiling ABACUS (and possibly its requirements) from the source code using the latest compiler for the best performace. You can use [toolchain](#install-by-toolchain) to install ABACUS and dependencies in a source-code compilation way with convience. You can also deploy ABACUS **without building** by [Docker](#container-deployment) or [conda](#install-by-conda). Please note that ABACUS only supports Linux; for Windows users, please consider using [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or docker. +This guide helps you install ABACUS with basic features. **For DeePKS, DeePMD and Libxc support, or building with `make`, please refer to [the advanced installation guide](../advanced/install.md)** after going through this page. We recommend building ABACUS with `cmake` to avoid dependency issues. We recommend compiling ABACUS (and possibly its requirements) from the source code using the latest compiler for the best performace. You can use [toolchain](#install-by-toolchain) to install ABACUS and dependencies in a source-code compilation way with convience. You can also deploy ABACUS **without building** by [Docker](#container-deployment) or [conda](#install-by-conda). Please note that ABACUS only supports Linux; for Windows users, please consider using [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or docker. For a scripted one-click setup that provisions WSL2 and installs ABACUS inside it automatically, see [Windows One-Click Installer](./windows_installer.md). ## Get ABACUS source code diff --git a/docs/quick_start/windows_installer.md b/docs/quick_start/windows_installer.md new file mode 100644 index 00000000000..7d4e3346760 --- /dev/null +++ b/docs/quick_start/windows_installer.md @@ -0,0 +1,256 @@ +# Windows One-Click Installer (WSL2 + conda-forge) + +A lightweight installer that brings ABACUS to Windows via WSL2 and +conda-forge. No C++ toolchain, no MPI build, no manual dependency juggling — +run `install-abacus.bat` once and type `abacus` from any Windows terminal. + +The scripts live in the repository under `tools/windows/`. This page is the +user-facing documentation for the same scripts. + +## How it works + +ABACUS depends on a heavy Linux-native scientific stack (OpenMPI, ScaLAPACK, +ELPA, FFTW, libxc, OpenBLAS, …) that is painful to build natively on Windows. +Instead of porting, this installer provisions a standard Linux environment +inside WSL2 and exposes it through thin Windows launchers. + +The pipeline, end to end: + +1. **`install-abacus.bat`** (runs on Windows, requires admin) + - Checks the Windows build (≥ 19041) and whether WSL is installed; if not, + runs `wsl --install --no-launch` and asks the user to reboot once. + - Optionally enables TUNA (Tsinghua) mirrors for users in Mainland China. + - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL + registry key `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This + is immune to UTF-16 parsing pitfalls and to Store appx leftovers that + can make `wsl -d -- true` falsely report success. + - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is + missing, then verifies the registry entry appeared. + - Invokes `provision.sh` inside the distribution, stripping any `\r` + bytes on the fly (`sed 's/\r$//' script | bash`) so Windows line + endings don't break shell parsing. + - Writes two small launcher `.cmd` files and adds them to the user PATH + via PowerShell (avoiding `setx`'s 1024-character truncation). + +2. **`provision.sh`** (runs as root inside the WSL distribution) + - Optionally rewrites `/etc/apt/sources.list` to TUNA. + - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, + bzip2). + - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases + mirror) and installs it to `/opt/abacus-miniforge`. + - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA + conda-forge channel) — a single package pulls in the entire scientific + runtime. conda-forge ships `abacus` for `linux-64` and `linux-aarch64`, + which is exactly what WSL2 provides. + - Writes two system-wide launchers, `/usr/local/bin/abacus` and + `/usr/local/bin/abacus-mpi`, that activate the env and exec the real + binary. Both set `OMP_NUM_THREADS=1` by default to avoid thread + oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE + "allow run as root" environment variables and passes + `--allow-run-as-root` to `mpirun`, so the default WSL root user can + launch parallel jobs without creating a non-root user. + +3. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) + - Added to `%LOCALAPPDATA%\ABACUS\bin` and the user PATH. + - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` + so thread-count overrides set on the Windows side are visible inside WSL. + - Body is just: + ``` + wsl -d Ubuntu-22.04 --cd "%CD%" -- abacus %* + ``` + `--cd "%CD%"` maps the current Windows directory (`C:\…\case`) to its + WSL path (`/mnt/c/…/case`), so users can `cd` into a case directory in + `cmd`/PowerShell/Terminal and just type `abacus`. + +4. **`uninstall-abacus.bat`** + - Reads `install-state.txt` (written by the installer) to learn whether + the Ubuntu-22.04 distribution was pre-existing or added by us. + - If it was added by us, prompts whether to `wsl --unregister` the entire + distribution, or to only wipe `/opt/abacus-miniforge` and the launchers. + - If it was pre-existing, only the ABACUS files inside are removed. + - Cleans Windows-side launchers and removes the bin directory from the + user PATH. + - Does **not** touch WSL itself (runtime, Windows optional features, or + other distributions). See *Uninstallation* below for how to fully + remove WSL if you want to. + +## Requirements + +- Windows 10 build 19041 (2004) or newer, or any Windows 11. +- Administrator privileges for the first run (to enable WSL features). +- Virtualization enabled in BIOS/UEFI. +- ~2 GB free disk space (Ubuntu + conda env). +- Network access to GitHub and conda-forge, or to TUNA if you choose the + China mirror option. + +## Installation + +1. Clone or download this repository. +2. In `tools/windows/`, right-click `install-abacus.bat` → **Run as administrator**. +3. Answer the China-mirror prompt (`y` recommended inside Mainland China). +4. If this is the first time WSL is installed on the machine, the script + will ask you to reboot and run it again. +5. Wait for `[*] Provisioning ABACUS …` to finish (5–15 minutes on first + run; most of it is the conda-forge download). +6. When you see `Installation complete!`, **open a new terminal window** + (so the updated PATH takes effect) and verify: + ``` + abacus --version + ``` + +## Usage + +Serial run in any case directory: + +``` +cd path\to\my_case +abacus +``` + +Parallel run with 4 MPI ranks: + +``` +abacus-mpi -n 4 +``` + +Hybrid MPI + OpenMP (e.g. 4 MPI ranks × 2 threads each): + +``` +set OMP_NUM_THREADS=2 +abacus-mpi -n 4 +``` + +Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in +your Windows shell and the launcher will forward the value into WSL through +`WSLENV`. Unset, it defaults to 1 — a safe choice when running pure MPI. + +Interactive Linux shell (for advanced debugging, manually running +`mpirun`, inspecting logs, etc.): + +``` +wsl -d Ubuntu-22.04 +``` + +Inside the shell you can `conda activate abacus_env` to get access to +`mpirun`, `mpiexec`, and other tools from the conda environment. + +## Uninstallation + +### Standard: remove ABACUS only + +Run `uninstall-abacus.bat`. This handles the common case: + +- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers + inside WSL. +- If the installer added the `Ubuntu-22.04` distribution, asks whether you + also want to `wsl --unregister` it (pick `y` to reclaim the disk space, + `n` to keep the Linux environment for other uses). +- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from + your user PATH. + +This is enough for almost every user. WSL itself and any *other* WSL +distributions you have stay untouched — important because WSL is commonly +shared with Docker Desktop, VS Code Remote, and other toolchains. + +### Nuclear: remove WSL itself + +Only do this if you truly have no other use for WSL on this machine. +Removing WSL will break Docker Desktop, VS Code Remote-WSL, any other +Linux distros you have, and so on. Run the following in an elevated +PowerShell: + +```powershell +# 1. Unregister every WSL distribution (this wipes all their files). +wsl --list --quiet | ForEach-Object { wsl --unregister $_.Trim() } + +# 2. Uninstall the WSL runtime itself (wsl.exe + the Linux kernel package). +# This is Microsoft's official command; it does not disable the Windows +# optional features and does not touch any distro appx packages. +wsl --uninstall + +# 3. Optionally remove leftover distribution appx packages from the Store +# (e.g. "Ubuntu 22.04 LTS"). `wsl --unregister` deletes the data only; +# the Store app that installs the distro is separate. +Get-AppxPackage *Ubuntu* | Remove-AppxPackage + +# 4. Optional: disable the Windows optional features (requires a reboot). +# Skip this step if anything else on the machine still uses Hyper-V +# virtualization (Docker Desktop, Windows Sandbox, Hyper-V VMs, ...). +dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart +dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart + +# 5. Remove user config if present. +Remove-Item "$env:UserProfile\.wslconfig" -ErrorAction SilentlyContinue + +# 6. Reboot to finalize. +Restart-Computer +``` + +After the reboot `wsl.exe` no longer exists. If you also ran step 4, the +Hyper-V virtualization layer used by WSL2 is disabled. + +> On older Windows builds where `wsl --uninstall` is not available (WSL +> shipped via the in-box `wsl.exe` rather than the Store package), use +> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a +> fallback for step 2. + +## Performance notes + +- Files under `/mnt/c/...` are served through the 9P protocol and are + noticeably slower than native ext4. For heavy I/O (large SCF, MD + trajectories), run the case from inside the WSL filesystem: + ``` + wsl -d Ubuntu-22.04 + cp -r /mnt/c/path/to/case ~/case + cd ~/case + abacus + ``` +- The first `wsl` invocation after a boot triggers a 10–30 s VM cold start. +- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network + overhead between ranks — you get near-native parallel performance. + +## File layout + +``` +tools/windows/ +├── install-abacus.bat # Windows entry point (admin, interactive) +├── uninstall-abacus.bat # Clean removal, optionally including the distro +├── provision.sh # Linux-side installer (runs as root in WSL) +├── .gitattributes # Pin *.sh to LF, *.bat/*.cmd to CRLF +└── README.md # Mirror of this page, shipped with the scripts +``` + +Artifacts created at install time: + +``` +%LOCALAPPDATA%\ABACUS\ +├── bin\ +│ ├── abacus.cmd # Windows launcher (serial) +│ └── abacus-mpi.cmd # Windows launcher (MPI) +└── install-state.txt # Records whether we created the WSL distro + +Inside WSL (Ubuntu-22.04): +/opt/abacus-miniforge/ # Private Miniforge install +/opt/abacus-miniforge/envs/abacus_env/ # conda env holding abacus +/usr/local/bin/abacus, /usr/local/bin/abacus-mpi # Linux-side launchers +``` + +## Design choices and trade-offs + +- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's + MPI + ScaLAPACK + ELPA stack has no reliable native Windows build. Going + through WSL2 lets us reuse the Linux binaries conda-forge already ships, + turning a multi-week porting problem into a 200-line shell script. +- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is + built against glibc from 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks + mismatches; pinning the version keeps the install reproducible. +- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** + Clean uninstall path, clear ownership, and doesn't interfere with a + user's personal conda install if they later add one inside the same + distribution. +- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from + ~10 min to ~1 min, but balloons the installer from a few KB of scripts + to 300–500 MB, requires CI infrastructure, and needs code signing to + avoid SmartScreen warnings. A scripted online installer is the + lowest-maintenance starting point; the pre-built rootfs path remains + open for a future v1. diff --git a/tools/windows/.gitattributes b/tools/windows/.gitattributes new file mode 100644 index 00000000000..2cffb7bcfb4 --- /dev/null +++ b/tools/windows/.gitattributes @@ -0,0 +1,6 @@ +# Shell scripts must have LF line endings so bash inside WSL can parse them. +*.sh text eol=lf + +# Batch files are Windows-only; keep CRLF. +*.bat text eol=crlf +*.cmd text eol=crlf diff --git a/tools/windows/README.md b/tools/windows/README.md new file mode 100644 index 00000000000..1bf57699710 --- /dev/null +++ b/tools/windows/README.md @@ -0,0 +1,253 @@ +# ABACUS Windows Installer + +A lightweight one-click installer that brings ABACUS to Windows via WSL2 and +conda-forge. No C++ toolchain, no MPI build, no manual dependency juggling — +run `install-abacus.bat` once and type `abacus` from any Windows terminal. + +## How it works + +ABACUS depends on a heavy Linux-native scientific stack (OpenMPI, ScaLAPACK, +ELPA, FFTW, libxc, OpenBLAS, …) that is painful to build natively on Windows. +Instead of porting, this installer provisions a standard Linux environment +inside WSL2 and exposes it through thin Windows launchers. + +The pipeline, end to end: + +1. **`install-abacus.bat`** (runs on Windows, requires admin) + - Checks the Windows build (≥ 19041) and whether WSL is installed; if not, + runs `wsl --install --no-launch` and asks the user to reboot once. + - Optionally enables TUNA (Tsinghua) mirrors for users in Mainland China. + - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL + registry key `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This + is immune to UTF-16 parsing pitfalls and to Store appx leftovers that + can make `wsl -d -- true` falsely report success. + - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is + missing, then verifies the registry entry appeared. + - Invokes `provision.sh` inside the distribution, stripping any `\r` + bytes on the fly (`sed 's/\r$//' script | bash`) so Windows line + endings don't break shell parsing. + - Writes two small launcher `.cmd` files and adds them to the user PATH + via PowerShell (avoiding `setx`'s 1024-character truncation). + +2. **`provision.sh`** (runs as root inside the WSL distribution) + - Optionally rewrites `/etc/apt/sources.list` to TUNA. + - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, + bzip2). + - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases + mirror) and installs it to `/opt/abacus-miniforge`. + - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA + conda-forge channel) — a single package pulls in the entire scientific + runtime. conda-forge ships `abacus` for `linux-64` and `linux-aarch64`, + which is exactly what WSL2 provides. + - Writes two system-wide launchers, `/usr/local/bin/abacus` and + `/usr/local/bin/abacus-mpi`, that activate the env and exec the real + binary. Both set `OMP_NUM_THREADS=1` by default to avoid thread + oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE + "allow run as root" environment variables and passes + `--allow-run-as-root` to `mpirun`, so the default WSL root user can + launch parallel jobs without creating a non-root user. + +3. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) + - Added to `%LOCALAPPDATA%\ABACUS\bin` and the user PATH. + - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` + so thread-count overrides set on the Windows side are visible inside WSL. + - Body is just: + ``` + wsl -d Ubuntu-22.04 --cd "%CD%" -- abacus %* + ``` + `--cd "%CD%"` maps the current Windows directory (`C:\…\case`) to its + WSL path (`/mnt/c/…/case`), so users can `cd` into a case directory in + `cmd`/PowerShell/Terminal and just type `abacus`. + +4. **`uninstall-abacus.bat`** + - Reads `install-state.txt` (written by the installer) to learn whether + the Ubuntu-22.04 distribution was pre-existing or added by us. + - If it was added by us, prompts whether to `wsl --unregister` the entire + distribution, or to only wipe `/opt/abacus-miniforge` and the launchers. + - If it was pre-existing, only the ABACUS files inside are removed. + - Cleans Windows-side launchers and removes the bin directory from the + user PATH. + - Does **not** touch WSL itself (runtime, Windows optional features, or + other distributions). See *Uninstallation* below for how to fully + remove WSL if you want to. + +## Requirements + +- Windows 10 build 19041 (2004) or newer, or any Windows 11. +- Administrator privileges for the first run (to enable WSL features). +- Virtualization enabled in BIOS/UEFI. +- ~2 GB free disk space (Ubuntu + conda env). +- Network access to GitHub and conda-forge, or to TUNA if you choose the + China mirror option. + +## Installation + +1. Clone or download this repository. +2. Right-click `install-abacus.bat` → **Run as administrator**. +3. Answer the China-mirror prompt (`y` recommended inside Mainland China). +4. If this is the first time WSL is installed on the machine, the script + will ask you to reboot and run it again. +5. Wait for `[*] Provisioning ABACUS …` to finish (5–15 minutes on first + run; most of it is the conda-forge download). +6. When you see `Installation complete!`, **open a new terminal window** + (so the updated PATH takes effect) and verify: + ``` + abacus --version + ``` + +## Usage + +Serial run in any case directory: + +``` +cd path\to\my_case +abacus +``` + +Parallel run with 4 MPI ranks: + +``` +abacus-mpi -n 4 +``` + +Hybrid MPI + OpenMP (e.g. 4 MPI ranks × 2 threads each): + +``` +set OMP_NUM_THREADS=2 +abacus-mpi -n 4 +``` + +Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in +your Windows shell and the launcher will forward the value into WSL through +`WSLENV`. Unset, it defaults to 1 — a safe choice when running pure MPI. + +Interactive Linux shell (for advanced debugging, manually running +`mpirun`, inspecting logs, etc.): + +``` +wsl -d Ubuntu-22.04 +``` + +Inside the shell you can `conda activate abacus_env` to get access to +`mpirun`, `mpiexec`, and other tools from the conda environment. + +## Uninstallation + +### Standard: remove ABACUS only + +Run `uninstall-abacus.bat`. This handles the common case: + +- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers + inside WSL. +- If the installer added the `Ubuntu-22.04` distribution, asks whether you + also want to `wsl --unregister` it (pick `y` to reclaim the disk space, + `n` to keep the Linux environment for other uses). +- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from + your user PATH. + +This is enough for almost every user. WSL itself and any *other* WSL +distributions you have stay untouched — important because WSL is commonly +shared with Docker Desktop, VS Code Remote, and other toolchains. + +### Nuclear: remove WSL itself + +Only do this if you truly have no other use for WSL on this machine. +Removing WSL will break Docker Desktop, VS Code Remote-WSL, any other +Linux distros you have, and so on. Run the following in an elevated +PowerShell: + +```powershell +# 1. Unregister every WSL distribution (this wipes all their files). +wsl --list --quiet | ForEach-Object { wsl --unregister $_.Trim() } + +# 2. Uninstall the WSL runtime itself (wsl.exe + the Linux kernel package). +# This is Microsoft's official command; it does not disable the Windows +# optional features and does not touch any distro appx packages. +wsl --uninstall + +# 3. Optionally remove leftover distribution appx packages from the Store +# (e.g. "Ubuntu 22.04 LTS"). `wsl --unregister` deletes the data only; +# the Store app that installs the distro is separate. +Get-AppxPackage *Ubuntu* | Remove-AppxPackage + +# 4. Optional: disable the Windows optional features (requires a reboot). +# Skip this step if anything else on the machine still uses Hyper-V +# virtualization (Docker Desktop, Windows Sandbox, Hyper-V VMs, ...). +dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart +dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart + +# 5. Remove user config if present. +Remove-Item "$env:UserProfile\.wslconfig" -ErrorAction SilentlyContinue + +# 6. Reboot to finalize. +Restart-Computer +``` + +After the reboot `wsl.exe` no longer exists. If you also ran step 4, the +Hyper-V virtualization layer used by WSL2 is disabled. + +> On older Windows builds where `wsl --uninstall` is not available (WSL +> shipped via the in-box `wsl.exe` rather than the Store package), use +> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a +> fallback for step 2. + +## Performance notes + +- Files under `/mnt/c/...` are served through the 9P protocol and are + noticeably slower than native ext4. For heavy I/O (large SCF, MD + trajectories), run the case from inside the WSL filesystem: + ``` + wsl -d Ubuntu-22.04 + cp -r /mnt/c/path/to/case ~/case + cd ~/case + abacus + ``` +- The first `wsl` invocation after a boot triggers a 10–30 s VM cold start. +- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network + overhead between ranks — you get near-native parallel performance. + +## File layout + +``` +tools/windows/ +├── install-abacus.bat # Windows entry point (admin, interactive) +├── uninstall-abacus.bat # Clean removal, optionally including the distro +├── provision.sh # Linux-side installer (runs as root in WSL) +├── .gitattributes # Pin *.sh to LF, *.bat/*.cmd to CRLF +└── README.md # This file +``` + +Artifacts created at install time: + +``` +%LOCALAPPDATA%\ABACUS\ +├── bin\ +│ ├── abacus.cmd # Windows launcher (serial) +│ └── abacus-mpi.cmd # Windows launcher (MPI) +└── install-state.txt # Records whether we created the WSL distro + +Inside WSL (Ubuntu-22.04): +/opt/abacus-miniforge/ # Private Miniforge install +/opt/abacus-miniforge/envs/abacus_env/ # conda env holding abacus +/usr/local/bin/abacus, /usr/local/bin/abacus-mpi # Linux-side launchers +``` + +## Design choices and trade-offs + +- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's + MPI + ScaLAPACK + ELPA stack has no reliable native Windows build. Going + through WSL2 lets us reuse the Linux binaries conda-forge already ships, + turning a multi-week porting problem into a 200-line shell script. +- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is + built against glibc from 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks + mismatches; pinning the version keeps the install reproducible. +- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** + Clean uninstall path, clear ownership, and doesn't interfere with a + user's personal conda install if they later add one inside the same + distribution. +- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from + ~10 min to ~1 min, but balloons the installer from a few KB of scripts + to 300–500 MB, requires CI infrastructure, and needs code signing to + avoid SmartScreen warnings. A scripted online installer is the + lowest-maintenance starting point; the pre-built rootfs path remains + open for a future v1. diff --git a/tools/windows/install-abacus.bat b/tools/windows/install-abacus.bat new file mode 100644 index 00000000000..2af99d09eba --- /dev/null +++ b/tools/windows/install-abacus.bat @@ -0,0 +1,151 @@ +@echo off +setlocal EnableExtensions EnableDelayedExpansion +title ABACUS for Windows (WSL2) Installer + +set "DISTRO=Ubuntu-22.04" +set "INSTALL_DIR=%LOCALAPPDATA%\ABACUS" +set "BIN_DIR=%INSTALL_DIR%\bin" + +echo ========================================= +echo ABACUS Windows Installer (WSL2) +echo ========================================= +echo. + +REM --- 1. Admin check --- +net session >nul 2>&1 +if errorlevel 1 ( + echo [!] Please right-click this script and choose "Run as administrator". + pause + exit /b 1 +) + +REM --- 2. Windows build check (WSL2 requires 19041+) --- +for /f "tokens=4-6 delims=. " %%a in ('ver') do set "BUILD=%%c" +if %BUILD% LSS 19041 ( + echo [!] Windows build %BUILD% detected. + echo [!] WSL2 requires Windows 10 build 19041 or newer, or Windows 11. + pause + exit /b 1 +) + +REM --- 2b. Offer China mirror (TUNA) for faster downloads --- +if not defined ABACUS_CHINA_MIRROR ( + set "ABACUS_CHINA_MIRROR=0" + set /p CHINA_INPUT="Use TUNA mirror for faster downloads (recommended inside Mainland China)? (y/N): " + if /i "!CHINA_INPUT!"=="y" set "ABACUS_CHINA_MIRROR=1" +) + +REM --- 3. Ensure WSL itself is present --- +where wsl >nul 2>&1 +if errorlevel 1 ( + echo [*] WSL not found. Installing WSL2 runtime... + wsl --install --no-launch + if errorlevel 1 ( + echo [!] WSL installation failed. + echo [!] Make sure virtualization is enabled in BIOS/UEFI. + pause & exit /b 1 + ) + echo. + echo [!] WSL was just installed. Please REBOOT Windows, + echo [!] then run this script again to continue. + pause + exit /b 0 +) + +REM --- 4. Ensure target distro registered --- +echo [*] Updating WSL2 runtime if needed (Microsoft's progress bar shows below)... +wsl --update +wsl --set-default-version 2 + +REM Detect distro via registry (reliable, ANSI output, no UTF-16 pitfalls). +set "DISTRO_PREEXISTED=0" +reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss" /s /v DistributionName 2>nul | findstr /i /c:"%DISTRO%" >nul +if not errorlevel 1 set "DISTRO_PREEXISTED=1" + +REM NOTE: keep this block flat (no nested parens) so `if errorlevel 1` after +REM each wsl.exe call reads the *runtime* errorlevel, not the parse-time one. +if "%DISTRO_PREEXISTED%"=="1" goto :distro_ready + +echo [*] Installing %DISTRO% into WSL ^(Microsoft's download progress shows below^)... +wsl --install -d %DISTRO% --no-launch +if errorlevel 1 ( + echo [!] Failed to install %DISTRO%. Reboot and retry, or run + echo [!] wsl --install -d %DISTRO% + echo [!] manually and finish any setup prompt, then re-run this script. + pause + exit /b 1 +) + +echo [*] Initializing %DISTRO% (first cold-start can take 30-60s)... +wsl -d %DISTRO% -u root -- /bin/true >nul 2>&1 + +reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss" /s /v DistributionName 2>nul | findstr /i /c:"%DISTRO%" >nul +if errorlevel 1 ( + echo [!] %DISTRO% still not registered after install. Possible causes: + echo [!] - Microsoft Store blocked/unreachable + echo [!] - A reboot is required to finish the initial WSL setup + echo [!] Reboot, then re-run this script. Or run manually: + echo [!] wsl --install -d %DISTRO% + pause + exit /b 1 +) + +:distro_ready + +REM --- 5. Run provisioning script inside the distro --- +echo [*] Provisioning ABACUS via conda-forge inside %DISTRO%. +echo This downloads ~400 MB and takes 5-15 minutes on first run. +echo. + +echo [*] Translating script path into WSL... +set "WSL_SCRIPT=" +for /f "usebackq delims=" %%i in (`wsl -d %DISTRO% wslpath "%~dp0provision.sh" 2^>nul`) do set "WSL_SCRIPT=%%i" +if not defined WSL_SCRIPT ( + echo [!] Could not translate script path into WSL. Aborting. + pause & exit /b 1 +) + +REM Strip any CR bytes that a Windows editor / git autocrlf may have injected +REM into provision.sh, then pipe the cleaned script into bash. Without this, +REM bash reads `set -euo pipefail\r` and errors on the literal \r. +wsl -d %DISTRO% -u root -- bash -c "sed 's/\r$//' '!WSL_SCRIPT!' | ABACUS_CHINA_MIRROR=!ABACUS_CHINA_MIRROR! bash" +if errorlevel 1 ( + echo [!] Provisioning failed. See output above. + pause & exit /b 1 +) + +REM --- 6. Install Windows-side launchers --- +if not exist "%BIN_DIR%" mkdir "%BIN_DIR%" + +> "%BIN_DIR%\abacus.cmd" echo @echo off +>> "%BIN_DIR%\abacus.cmd" echo set "WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:%%WSLENV%%" +>> "%BIN_DIR%\abacus.cmd" echo wsl -d %DISTRO% --cd "%%CD%%" -- abacus %%* + +> "%BIN_DIR%\abacus-mpi.cmd" echo @echo off +>> "%BIN_DIR%\abacus-mpi.cmd" echo set "WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:%%WSLENV%%" +>> "%BIN_DIR%\abacus-mpi.cmd" echo wsl -d %DISTRO% --cd "%%CD%%" -- abacus-mpi %%* + +REM Record install state so the uninstaller knows whether we added the distro. +> "%INSTALL_DIR%\install-state.txt" echo distro=%DISTRO% +>> "%INSTALL_DIR%\install-state.txt" echo distro_preexisted=!DISTRO_PREEXISTED! + +REM --- 7. Add BIN_DIR to user PATH (idempotent, no 1024-char truncation) --- +powershell -NoProfile -ExecutionPolicy Bypass -Command ^ + "$b='%BIN_DIR%'; $p=[Environment]::GetEnvironmentVariable('PATH','User'); if([string]::IsNullOrEmpty($p)){[Environment]::SetEnvironmentVariable('PATH',$b,'User')} elseif(($p -split ';') -notcontains $b){[Environment]::SetEnvironmentVariable('PATH',$p.TrimEnd(';')+';'+$b,'User')}" + +echo. +echo ========================================= +echo Installation complete! +echo ========================================= +echo. +echo Open a NEW terminal window, cd into a case directory, then run: +echo abacus +echo. +echo For parallel execution with N processes: +echo abacus-mpi -n 4 +echo. +echo To enter the Linux shell for advanced use: +echo wsl -d %DISTRO% +echo. +pause +exit /b 0 diff --git a/tools/windows/provision.sh b/tools/windows/provision.sh new file mode 100644 index 00000000000..2007243c482 --- /dev/null +++ b/tools/windows/provision.sh @@ -0,0 +1,112 @@ +#!/usr/bin/env bash +# Provisions ABACUS inside a WSL2 Ubuntu distribution. +# Expected to run as root (installer invokes `wsl -u root`). + +set -euo pipefail + +MINIFORGE_DIR="/opt/abacus-miniforge" +ENV_NAME="abacus_env" +ENV_BIN="$MINIFORGE_DIR/envs/$ENV_NAME/bin" +CHINA_MIRROR="${ABACUS_CHINA_MIRROR:-0}" + +if [ "$CHINA_MIRROR" = "1" ]; then + MINIFORGE_URL="https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease/Miniforge3-Linux-x86_64.sh" + CONDA_FORGE_CHANNEL="https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge" +else + MINIFORGE_URL="https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh" + CONDA_FORGE_CHANNEL="conda-forge" +fi + +log() { printf '[provision] %s\n' "$*"; } + +if [ "$(id -u)" -ne 0 ]; then + echo "[provision] Must run as root." >&2 + exit 1 +fi + +if [ "$CHINA_MIRROR" = "1" ]; then + log "China mirror mode: using TUNA (Tsinghua) for apt / Miniforge / conda-forge." + if [ -f /etc/apt/sources.list ] && grep -qE 'archive\.ubuntu\.com|security\.ubuntu\.com' /etc/apt/sources.list; then + log "Rewriting /etc/apt/sources.list to TUNA (backup at sources.list.orig)..." + cp -n /etc/apt/sources.list /etc/apt/sources.list.orig + sed -i \ + -e 's|http://archive.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g' \ + -e 's|http://security.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g' \ + /etc/apt/sources.list + fi +fi + +log "Installing apt prerequisites (apt-get update + curl/ca-certs/bzip2)..." +export DEBIAN_FRONTEND=noninteractive +apt-get update +apt-get install -y --no-install-recommends curl ca-certificates bzip2 + +if [ ! -x "$MINIFORGE_DIR/bin/conda" ]; then + log "Downloading Miniforge installer (~80 MB)..." + tmp="$(mktemp --suffix=.sh)" + trap 'rm -f "$tmp"' EXIT + curl -fL --progress-bar -o "$tmp" "$MINIFORGE_URL" + log "Installing Miniforge into $MINIFORGE_DIR..." + # Run the installer via its own shebang (dash on Ubuntu) rather than + # `bash installer.sh`. Some Miniforge builds have a sourced-check that + # misfires under bash and aborts with "Please run using bash/dash/...". + chmod +x "$tmp" + "$tmp" -b -p "$MINIFORGE_DIR" + rm -f "$tmp" + trap - EXIT +else + log "Miniforge already present at $MINIFORGE_DIR." +fi + +# shellcheck disable=SC1091 +source "$MINIFORGE_DIR/etc/profile.d/conda.sh" + +if conda env list | awk 'NF && $1 !~ /^#/ {print $1}' | grep -qx "$ENV_NAME"; then + log "Updating existing env '$ENV_NAME' (channel: $CONDA_FORGE_CHANNEL)..." + conda install -n "$ENV_NAME" -y --override-channels -c "$CONDA_FORGE_CHANNEL" abacus +else + log "Creating env '$ENV_NAME' (channel: $CONDA_FORGE_CHANNEL)..." + conda create -n "$ENV_NAME" -y --override-channels -c "$CONDA_FORGE_CHANNEL" abacus +fi + +log "Installing system launchers..." + +cat > /usr/local/bin/abacus < /usr/local/bin/abacus-mpi </dev/null 2>&1; then + /usr/local/bin/abacus --version || true +elif [ -x "$ENV_BIN/abacus" ]; then + log "abacus binary present at $ENV_BIN/abacus (no --version flag)." +else + log "WARNING: abacus binary not found after install." + exit 1 +fi + +log "Done." diff --git a/tools/windows/uninstall-abacus.bat b/tools/windows/uninstall-abacus.bat new file mode 100644 index 00000000000..3c8e210f6bc --- /dev/null +++ b/tools/windows/uninstall-abacus.bat @@ -0,0 +1,70 @@ +@echo off +setlocal EnableExtensions EnableDelayedExpansion +title ABACUS Uninstaller + +set "DISTRO=Ubuntu-22.04" +set "INSTALL_DIR=%LOCALAPPDATA%\ABACUS" +set "BIN_DIR=%INSTALL_DIR%\bin" +set "STATE_FILE=%INSTALL_DIR%\install-state.txt" + +REM --- Read state file to learn whether the installer added the distro --- +set "DISTRO_PREEXISTED=1" +if exist "%STATE_FILE%" ( + for /f "usebackq tokens=1,2 delims==" %%a in ("%STATE_FILE%") do ( + if /i "%%a"=="distro_preexisted" set "DISTRO_PREEXISTED=%%b" + ) +) + +echo This will remove: +echo - Launchers under %BIN_DIR% +echo - %BIN_DIR% from your user PATH +if "!DISTRO_PREEXISTED!"=="0" ( + echo. + echo The installer added the '%DISTRO%' WSL distribution. + echo You can either remove the whole distribution, or just remove the + echo ABACUS files inside it and keep the Linux environment. +) else ( + echo - /opt/abacus-miniforge inside WSL ^(%DISTRO%^) + echo. + echo The %DISTRO% distribution existed before installation and will NOT be removed. +) +echo. + +set /p CONFIRM="Continue? (y/N): " +if /i not "!CONFIRM!"=="y" ( + echo Aborted. + exit /b 0 +) + +set "REMOVED_DISTRO=0" +if "!DISTRO_PREEXISTED!"=="0" ( + echo. + set /p REMOVE_DISTRO="Remove the entire '%DISTRO%' WSL distribution? This wipes all files inside it. (y/N): " + if /i "!REMOVE_DISTRO!"=="y" ( + echo [*] Unregistering %DISTRO%... + wsl --unregister %DISTRO% + if not errorlevel 1 set "REMOVED_DISTRO=1" + ) +) + +if "!REMOVED_DISTRO!"=="0" ( + where wsl >nul 2>&1 + if not errorlevel 1 ( + wsl -d %DISTRO% -u root -- /bin/true >nul 2>&1 + if not errorlevel 1 ( + echo [*] Removing conda env and launchers inside %DISTRO%... + wsl -d %DISTRO% -u root -- bash -c "rm -rf /opt/abacus-miniforge /usr/local/bin/abacus /usr/local/bin/abacus-mpi" + ) + ) +) + +if exist "%BIN_DIR%" rd /s /q "%BIN_DIR%" +if exist "%INSTALL_DIR%" rd /s /q "%INSTALL_DIR%" + +powershell -NoProfile -ExecutionPolicy Bypass -Command ^ + "$b='%BIN_DIR%'; $p=[Environment]::GetEnvironmentVariable('PATH','User'); if($p){$n=(($p -split ';') | Where-Object { $_ -and ($_ -ne $b) }) -join ';'; [Environment]::SetEnvironmentVariable('PATH',$n,'User')}" + +echo. +echo Uninstall complete. +pause +exit /b 0