This is how to <ahref="https://www.theregister.com/2022/11/23/wsl_microsoft_store_default_version/">
install and use WSL</a> and by default we use Ubuntu24.04. We assume that you have a relatively recent machine. If not, see the bottom of this page about WSL1, which is different and old.
<var>\\wsl.localhost\Ubuntu\home\username\expo\</var>filesystem, not in <var>C:/Users/username/expo</var> not even if you have mounted it as <var>/mnt/c/username/expo</var>. If you try that you will hit file permissions problems and it will also be quite slow (but see WSL1 below).
<p>If you have PuTTY installed and working, but you now want to use WSL rsync, you need to set up a key again within the WSL environment.
<p>[ Now that Microsoft allows installation of OpenSSL using <ahref="">standard Windows tools</a> on Windows 10 and 11, we need someone to revise all the Windows/troggle documentation for a PuTty-free route. Volunteers? ]
The generated key is in the current directory and you need to move them to ~/.ssh/ as is standard on Linux (which is not at all the same place that puTTY uses to keep keys on Windows).
<p>Now you have to complete the <ahref="keyexchange.html">key-pair setup</a> with the new key "id_ras_wsl.pub". But you don't need anyone else's help this time as you can use puTTY to ssh into the server and copy your key to the right place yourself: it is a <ahref="keyexchange.html#secondmachine">"Second Machine"</a>.
<p>If you are disturbed by the instructions to produce an entirely different SSL key for WSL to use when your PC already has a perfectly good PuTTy key installed on the server, then you are right. It is inelegant. But it works, the instructions are shorter and there are fewer things that go wrong. If you are terribly offended by that then you can set your PC up to use one key shared between WSL and normal-Windows as described in <ahref="https://devblogs.microsoft.com/commandline/sharing-ssh-keys-between-windows-and-wsl-2/">this October 2019 article</a>. (Don't set up a password on the key because then you don't need to install keychain.) But beware, this sort of thing goes out of date quite rapidly.
<h3id="pain">Python on WSL</h3>
<p>WSL installs python by default, but it may be a rather old python (depending on the history of your laptop, phase of moon etc.) and if you want development speed you want python3.13. [NB check what version of python is running on the server. It was 3.11.2 in December 2024.].
<p>We used to have lengthy instructions fo installing python using "deadsnakes" but since December 2024 we just use the <var>uv</var> utility for everything, see <ahref="troglaptop.html">⚒ troggle development machine</a>
<p>To install python3.11 and pip follow <ahref="https://www.linuxcapable.com/how-to-install-python-3-11-on-ubuntu-linux/">these instructions</a> to the letter. But that's not enough, you need to configure pip to work properly with python3.11 (this is because it's a bit bleeding edge as yet), so you ALSO then need to re-install the latest with:
<p>Do not use WSL1. And with WSL2, put all your development files into the <var>ext4</var> filesystem on <var>\\wsl.localhost\Ubuntu\home\username\expo\</var>. In 2024 the hassles of working with NTFS files under WSL are not worth it. If your Windows laptop can't install WSL2, install a Xubuntu dual-boot system on a separate disc partition or SD card.
<p>
<ahref="https://learn.microsoft.com/en-us/windows/wsl/compare-versions?source=recommendations">WSL2 is now noticeably even slower</a> for NTFS files mounted as /mnt/c or /mnt/d, so now it is only really useable if you move all the troggle code into your Linux filespace on <var>\\wsl.localhost\Ubuntu\home</var> which means that those files will only be accesible from Linux.
<p>WSL now installs as WSL2 by default, but older machines (mostly laptops) may not have the Hyper-V Virtualization hardware and may have to run WSL1.
This may be fine: the behaviour is nearly identical so far as an expo laptop is concerned, where you just want to use rsync and scp. An old 2011-era PC had
been doing troggle development happily using WSL1. However time is clearly running out for WSL1, and the file handling is now very noticably slower. If your laptop won't run WSL2 then you are advised to get rid of Windows completely and install Xubuntu as a dual boot system.
<h3>WSL2 - things to watch for</h3>
<p>On some Windows 10 laptops WSL1 fails to install properly and
<ahref="https://learn.microsoft.com/en-us/windows/wsl/compare-versions?source=recommendations">you have to use WSL2</a>.
<p>You should <ahref="https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconf">check that the configuration files</a> do what you want.
<p>When running a full troggle development laptop (see separate <ahref="../troggle/troglaptop.html">troggle documentation</a>)
you will want to use a virtual environment (python venv or uv). This barfs untidily if you have the code on NTFS, e.g. if mounted on <var>/mnt/c/</var>. You almost
'network' method <var>\\wsl$\Ubuntu\home\expo\troggle\</var>. This means that file access is noticably faster too. You will need to make sure that your backup/archive methods access this filesystem though.
<p>NB rsync doesn't work with NTFS partitions the way that WSL1 does.
<p>Read <ahref="https://code.visualstudio.com/blogs/2019/09/03/wsl2">WSL & Visual Studio Code</a> and go back and read the bits about VS Code
running remotely in the ※Windows data maintenance laptop page.
<h3>WSL1 gotchas and tips</h3>
<p><ahref="https://linuxnightly.com/mount-and-access-hard-drives-in-windows-subsystem-for-linux-wsl/">WSL using files on NTFS</a>
unfortunately introduces a wonderful new problem of file permissions. Every file on the Windows filesystem NTFS has a set of
permissions managed by the filesystem. Every NTFS file that WSL knows about (if mounted with -o metadata) acquires a completely parallel set of file
permissions that are fundamentally different things and are never in sync in any sense. <a
href="https://devblogs.microsoft.com/commandline/chmod-chown-wsl-improvements/">All sorts of fun</a> results. The alternative is to store all your data
in the \\wsl$\ ext4 filesystem (WSL2 only, not WSL1).
<p>Having happily used WSL1 for a couple of years since 2020, it was a rude awakening to try this with a new laptop with a small
hard-drive, so all the expo code was re-mounted on a plugged-in SD card. The problem of permissions that seemed to be purely a WSL2 issue reappeared with
<p>The recommended WSL procedure (Jan.2021) said to mount the drive using
<ahref="https://devblogs.microsoft.com/commandline/chmod-chown-wsl-improvements/">a new 'metadata' setting</a>:
<pre><code>sudo umount /mnt/d
sudo mount -t drvfs D: /mnt/d -o metadata,uid=1000,gid=1000,umask=22,fmask=111</code></pre>
<p>This is probably why there is a difference between automatically-mounted drives (e.g. C:, /mnt/c) and plug-in drives:
"<em>By default, WSL will set the uid and gid to the default user with drives that are auto-mounted during instance start. If you mount manually, you will
have to set these explicitly (the default user that gets created when WSL is first installed has a uid=1000 and gid=1000).</em>"
<p>And of course you will need to arrange that this happens automatically whenever you start WSL, so you will need to set
<ahref="https://help.ubuntu.com/community/Fstab"><var>/etc/fstab</var></a>, so ensure that the relevant line says:
The trick is to make sure that all the files in your development folders, e.g. <var>C:\expo\</var> which contains your repos e.g. <var>C:\expo\troggle\</var> are owned in the Windows system by the default Windows user e.g. <var>MACHINENAME\philip</var> and owned in the Linux system e.g. <var>/mnt/c/expo/</var> by the default Linux user, e.g. <var>philip:philip</var> using <br><var>sudo chown -Rhv philip:philip *</var>
<br>
and then <em>reboot your machine</em> as this doesn't seem to properly take effect until you do that.
<p>
See also <ahref="https://learn.microsoft.com/en-us/windows/wsl/file-permissions">WSL File Permissions</a>.
<li><ahref="https://www.hanselman.com/blog/CoolWSLWindowsSubsystemForLinuxTipsAndTricksYouOrIDidntKnowWerePossible.aspx">Cool WSL tricks</a> - running Windows commands from WSL environment and running Linux commands from Windows terminal.
<li><ahref="https://code.visualstudio.com/blogs/2019/09/03/wsl2">deep integration</a> - Don't use gitforwindows, install the linux git client in WSL2
<li><ahref="https://blog.anaisbetts.org/using-github-credentials-in-wsl2/">using-github-credentials-in-wsl2</a> - How to use gitforwindows and WSL to connect to GitHub.
</ul>
<p>When things go wrong when trying to sort this out, you may find these pages useful. I did.
<tt><ahref="https://serverfault.com/questions/423075/rsync-failed-to-set-permission-operation-not-permitted">rsync - failed to set permission - operation not permitted</a></tt>
