209 lines
7.9 KiB
ReStructuredText
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.
|