Files
muSRFlow/docs/source/install-windows.rst

209 lines
7.9 KiB
ReStructuredText

.. _windows-installation:
Windows installation
====================
The Windows installer includes muSRFlow, ROOT, and musrfit. Install WSL2
first; muSRFlow prepares its own Linux runtime on first launch. You do not
need Node.js, npm, Ubuntu, or a separate ROOT/musrfit installation.
Already installed muSRFlow? Read `Existing installations`_ as well: updating
the application does not update an already imported WSL runtime.
Before you start
----------------
* Use a **64-bit Intel/AMD PC**. The current package is x64.
* Windows 11 is recommended. Windows 10 requires build 19044 or newer for
WSLg, which displays the musrview spectrum windows.
* Administrator access is needed to enable the Windows virtualization features.
* Obtain the Windows installer, named ``muSRFlow-<version>-x64.exe``, from
the project's `Releases <https://gitea.psi.ch/salman/muSRFlow/releases>`_
or the **musrflow-windows** package in
`Packages <https://gitea.psi.ch/salman/muSRFlow/packages>`_. Verify its
SHA-256 checksum against the accompanying ``.sha256`` file. The Windows
installer includes the bundled runtime (``musrfit``, ``musrt0``, ``musrview``,
``msr2data``, ``dump_header``, ``root-config``) for use inside WSL2; only
markers are placed in the app resources.
* For a test build that has not been published yet, download the
**musrflow-windows-x64** artifact from a successful **Build Windows
installer** workflow run and extract the installer.
**Avoid old rc.5 installers.** Early builds lack the WSL fixes. The current
runner-built installer includes them and has passed Windows installation,
runtime setup, data download, Fit/Plot, and multi-run smoke tests.
See `Microsoft's WSL GUI requirements
<https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps>`_ for the
Windows prerequisites.
Install step by step
--------------------
1. **Install WSL.** Open **PowerShell as Administrator** and run:
.. code-block:: powershell
wsl --install --no-distribution
**Restart Windows afterwards.** Skip this step if WSL is already installed.
muSRFlow supplies its own distribution, so Ubuntu is not required.
2. **Update and check WSL.** In administrator PowerShell, run:
.. code-block:: powershell
wsl --update
wsl --version
Follow any restart instructions. The output should include WSL and WSLg.
These commands are described in the `Microsoft WSL command reference
<https://learn.microsoft.com/en-us/windows/wsl/basic-commands>`_.
3. **Install muSRFlow.** Double-click the Windows installer and complete setup.
The runtime archive ``muSRFlow-runtime-rootfs.tar.gz`` is included; do not
extract or import it manually for a normal installation.
4. **Launch muSRFlow** from the Start menu using your normal Windows account.
First launch imports the runtime as ``muSRFlow-runtime`` and can take
several minutes. Fit and Plot wait until preparation finishes. Afterwards,
verify in PowerShell:
.. code-block:: powershell
wsl --list --verbose
The list should contain ``muSRFlow-runtime`` with **VERSION 2**.
``Running`` and ``Stopped`` are both normal when idle. The runtime is
stored under ``%LOCALAPPDATA%\muSRFlow\muSRFlow-runtime`` for this account.
5. **Choose work and data folders before fitting.** Create folders such as:
.. code-block:: text
C:\Users\<your-name>\muSRFlow\work
C:\Users\<your-name>\muSRFlow\data
In **File / Preferences**, select them as **Work directory** and
**Data directory**. Leave **musrfit binaries** and **musrfit startup XML**
on automatic detection, then save. Enter normal Windows paths; muSRFlow
translates them for WSL.
Use a work folder outside the application installation directory. The
default ``.`` can resolve to the installation folder and place your
results among files managed by the installer.
6. **Try Plot, then Fit.** Select a known instrument, year, and run. Click
**Plot** and confirm that the spectrum window opens. Missing run data
can be downloaded from ``musruser.psi.ch`` after confirmation when the
server is reachable. Then click **Fit**, check that the parameter table
updates, and inspect the generated files in your work directory.
Existing installations
----------------------
1. Preserve any MSR/data/result files currently stored inside the muSRFlow
installation folder: move them to a separate work folder before upgrading.
2. Close muSRFlow and install the refreshed Windows application.
3. If your runtime was imported from an older bundle, add the missing Boost
headers from PowerShell:
.. code-block:: powershell
wsl -d muSRFlow-runtime -- dnf -y install boost-devel
This needs access to the distribution's package repositories. ROOT uses
these headers when loading musrview plotting classes. Fresh runtimes
from the corrected installer already include them.
4. Reopen muSRFlow, select your work directory in Preferences, and retry Plot
and Fit.
Reinstalling the application preserves an existing ``muSRFlow-runtime``
distribution, so the application update alone does not add those headers.
The command above repairs it in place; do not unregister the distribution
as part of this update. The Linux **Install runtime...** preference is not
used on Windows.
Troubleshooting
---------------
Required feature is not installed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For ``HCS_E_SERVICE_NOT_AVAILABLE`` during runtime preparation, Windows
could not create the WSL virtual machine. In **administrator PowerShell**:
.. code-block:: powershell
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart Windows. Check **Task Manager / Performance / CPU** for
**Virtualization: Enabled**; if disabled, enable hardware virtualization in
BIOS/UEFI. If Windows itself is a virtual machine, its host must expose nested
virtualization. If the error persists, check the boot setting:
.. code-block:: powershell
bcdedit /enum | findstr -i hypervisorlaunchtype
Only if it reports ``Off``, enable it and restart:
.. code-block:: powershell
bcdedit /set hypervisorlaunchtype Auto
See `Microsoft's WSL troubleshooting guide
<https://learn.microsoft.com/en-us/windows/wsl/troubleshooting>`_.
Cannot find wsl.exe
~~~~~~~~~~~~~~~~~~~
For ``spawn wsl.exe ENOENT``, first check that ``wsl --version`` works in
PowerShell. If it does, install the refreshed muSRFlow build: early rc.5
builds incorrectly replaced the Windows executable search path. Also check
that the selected work directory exists and is writable.
Cannot load libCore.so
~~~~~~~~~~~~~~~~~~~~~~
Install the refreshed muSRFlow build. It passes the ROOT library directory
inside WSL for every bundled command. Setting a Windows ``ROOTSYS`` or
``LD_LIBRARY_PATH`` is not a substitute for this launcher fix.
Missing boost/version.hpp or plotting crash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow `Existing installations`_ to install ``boost-devel`` in an older
runtime. The corrected runtime includes it. If plotting still crashes,
include the full command output when reporting the problem.
No spectrum window appears
~~~~~~~~~~~~~~~~~~~~~~~~~~
Confirm that ``wsl --version`` lists WSLg, update WSL, and inspect the
muSRFlow run log. Successful runtime import or a successful fit alone does
not verify interactive graphics support.
Reporting a problem
~~~~~~~~~~~~~~~~~~~
Include the muSRFlow version, full run log, and the output of:
.. code-block:: powershell
wsl --version
wsl --status
wsl --list --verbose
The corrected runtime has completed a real fit and generated a PNG in a
Linux container. Interactive Windows/WSLg plotting still needs validation
on the target PC.
Ready packages (downloads)
~~~~~~~~~~~~~~~~~~~~~~~~~~
Prebuilt Windows installers are published on the
`Gitea releases page <https://gitea.psi.ch/salman/muSRFlow/releases>`_.
Download the Windows installer for the desired release (for example
``1.0.0``) and follow the instructions above.