How to: Install e3 on Windows 10/11 with WSL

If you are working in a Windows environment and need to run EPICS locally to test some IOC, most likely you have to install a Linux VM or have a dual booting machine.

In order to avoid the overhead of a VM or to boot one or the other OS in your machine, you can work with both OS seamlessly, installing a Linux Bash Shell on Windows 10/11 through Windows Subsystem for Linux (WSL).

In the bash shell1 you can install all the packages you need via apt command, like the GNU Linux Compiler Collection and all the libraries you need to compile EPICS.

This is a guide to install EPICS on a Windows 10 or 11, with Debian 12/Ubuntu 22.04 WSL12 (only Windows 10) or WSL2 (Windows 10 or 11). Although the current Linux OS used for IOC deployment is CentOS7, we will soon move to Ubuntu 22.04, so this guide could also be helpful to check the EPICS modules compatibility between the two Linux distros3.

Important

For any clarification, questions, concerns, please send a mail to mailto:alfio.rizzo@ess.eu

Tip

It is highly suggested to change the ownership of the EPICS installation directory to your username/usergroup (look at man chown for instructions) if it is located in path where root is the owner (e.g. / , /usr/local , /opt), to avoid to use the sudo command during the installation.

Tip

You can parallelize the compilation using the make -j option, so the installation can be speeded up ! Set this environment variable before to start the compilation: export MAKEFLAGS="-jN", where N is the number of CPUs you want to use. However we suggest to use only 2 CPUs since the compilation of the e3-base could sporadically stop if you put more cores, moreover not all the e3 modules are built to be compiled in parallel mode (e.g. sequencer), but at least the compilation time will be reduced by a factor of two.

Note

The guide below is applicable also to a pure Debian/Ubuntu Linux OS if the steps followed are the same as the ones for WSL2.

Step-by-step guide

  1. Install WSL and your preferred Linux Shell (Debian or Ubuntu) (see https://docs.microsoft.com/en-au/windows/wsl/install-win10 )

  2. Once you run the Shell, it will ask you to create a UNIX username/password.

    Tip

    It is suggested to create an account with the same username (password) as the one in the ESS domain, since it would be more practical when working in the ESS network.

  3. Update the system:

    [user@host:~]$ sudo apt update
[user@host:~]$ sudo apt upgrade

  4. Install the packages needed to compile the different EPICS modules. Depending on the specification file you will use, you would need to install several packages. The packages needed for almost the epics modules installation are listed in this text file epicspkg.txt, which is stored in the following git repo: wslpkg

    Warning

    If your installation fails since there were some missing packages, please open a MR then they will be added in the epicspkg.txt file.

    So then please download the file and run the following command:

    [user@host:~]$ xargs -a epicspkg.txt sudo apt install

  5. Install the e3 tool package, then go directly to point 10 if you have WSL2

    • https://gitlab.esss.lu.se/e3/e3

      Tip

      You can install e3 with pipx package, using the following command:

      [user@host:~]$ pipx install --index-url="https://artifactory.esss.lu.se/artifactory/api/pypi/pypi-virtual/simple" e3

  6. Create an e3 build directory in your $HOME or elsewhere, e.g.

    [user@host:~]$ mkdir epicsbuild

  7. Clone in the build directory the e3-base with the same tag you have in your specification file

    [user@host:~/epicsbuild]$ git clone https://gitlab.esss.lu.se/e3/wrappers/e3-base/ -b <tag>

  8. Go inside the e3-base directory and open the configure/CONFIG_BASE file and change the absoulte installation path E3_EPICS_PATH:=/epics to your preferred installation location. Copy the patch file blocking_udp_transport_wsl.p0.patch to the patch directory.

  9. Then do

    [user@host:~/epicsbuild/e3-base]$ make init
[user@host:~/epicsbuild/e3-base]$ make patch
[user@host:~/epicsbuild/e3-base]$ make build

  10. Run the e3-build script using your preferred specification file. For instance we have selected some of the EPICS modules in the specification files 2023q1_snippet.yml, 2024_snippet.yml, which are needed to run a PLC IOC, a SNL IOC or a StreamDevice IOC. The use case to run those IOCs is mostly for testing/simulation purpose, e.g. the Siemens PLC Sim Advannced4 tool along with the related IOC/OPI. Below an exanple of the compilation script you may want run using the 2023q1_snippet.yml specification file.

[user@host:~]$ e3-build -v -t <epics_installation_dir> -b <epics_build_dir> <path_to_your_spec_folder>/2023q1_snippet.yml

with for instance <epics_installattion_dir> = /epics and <epics_build_dir> = ~/epicsbuild

Warning

Only for WSL1:

The build directory (<epics_build_dir>) must be the same you have created in point 6.

The epics installation path (<epics_installation_dir>) must be the one you have declared in point 8.

And, at the end…

If the build ends successfully, then you can run your local IOC!

Note

Only for WSL1 or WSL2 on Windows10 Build < 19044:

As optional, if you like to have also a X Window Server to open Linux GUI, you can install Xming or VcXsrv X server

So then remember to add this environment variable to your .bashrc

WSL1: export DISPLAY=localhost:0.0

WSL2: export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):0.0

Note

Only for WSL2 on Windows 10 Build 19044+ or Windows 11:

X11 and Wayland Server are natively supported seamlessly and the $DISPLAY environment variable is set automatically, see https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps.

Tip

From the Linux Shell you can access your Windows disk as well, which is usually mounted on /mnt/c.

And you can run also Windows exe files from the shell, like for instance NETSTAT.exe.

1

If you like to open multiple shells in a console window you can use the new windows terminal.

2

There is only one caveat for WSL1, which is the different way Windows and Linux bind a multicast UDP socket (needed by PV Access, while there is no problem with CA access). So even if you are using GCC Linux, since you are not running on a VM, you should use the Windows way to bind the socket. This is not handled in the EPICS source code, but it can be fixed with a patch on the file blockingUDPTransport.cpp. and in this guide it is explained how to apply the patch. However the binding of multicast UDP socket was fixed in WSL2, so we strongly suggest to upgrade to WSL2 when possible, since in addition to containing fixes and improvements, WSL2 uses a subset of the Hyper-V architecture to enable virtualization, thus resulting in a pure virtual machine.

3

For those who prefer other Linux OS distros, WSL2 also supports CentOS/Fedora Linux distros including also RedHat, see for instance installation instruction for RedHat here.

4

The Siemens PLC Sim Advanced tool run only on Windows, so it is most natural to use WSL to run a local IOC.