Base Utilities

Author

Jon Reades

Published

September 7, 2023

In order to access the majority of the features that this module uses, you will need to install several ‘base’ utilities:

You need the Xcode Command Line Tools installed on your Mac. In some cases this may have already been installed, but it’s the same process to check as to install:

  1. Open the Terminal application (which can be found under Utilities in your Applications folder).
  2. Type the following: xcode-select --install and then hit Enter (⏎)

Unless you get an outright error you can proceed to the next step:

  1. Although not strictly necessary, you’ll eventually want the Homebrew package manager, which can also be installed directly from the Terminal.

You will need to install WSL2 but, strangely, you do not actually need to install a full Linux O/S, so as far as we can tell this means you only need to run the following commands in the Windows PowerShell:

  1. wsl --install should quickly install the subsystem that we need.
  2. wsl --update will ensure that the most up-to-date version is available.

That should be it: Docker should now run without complaint.

If You Need More Help
  1. There is good guidance from Microsoft for Windows 11 and more recent ‘builds’ of Windows 10.
  2. There are also older instructions for Windows 10.

Common installation errors are covered here.

Finally, if you are still being told that you can’t install WSL2 and Linux, then the most likely cause of this issue is a setting in the BIOS of the computer itself. There are a couple of settings that need changing at a very low level to enable Hyper-V virtualisation. I would start by following this MS guide and, if there is still a problem, check this blog post.

Windows + Linux + Shell

Creating a Linux User

If you want to install a full Linux distribution (e.g. because you want to do more than just run Docker) then make sure you set up a new Linux user and do not end up running everything as root.

To make full use of WSL2 and Linux (if you want to do more than just use Docker) you will need to familiarise yourself with how having two operating systems that can talk to each other works. That is covered in the next section. This will actually be useful for understanding how Docker works, as it can be profoundly confusing.

The behaviour of the ‘shell’ (command line) is quite confusing because, with WSL2, you effectively end up with two ‘home’ directories: one for your Windows user, and one for your new Ubuntu user. Starting a Linux shell/command line puts you in your Linux home directory (the username may be completely different from your Windows username). Starting a Windows shell/command line puts you in your Windows home directory (again, the username may be completely different from your Linux username).

So the first, and perhaps most important, thing is understanding where ‘data’ is being stored:

  • Under Linux the user directory is apparently something like: \\wsl$\<DistroName>\home\<UserName>\ but you can usually get it by simply typing cd $HOME and then pwd when starting a new Linux shell.
  • Under Windows the user directory is: C:\Users\<UserName>\ or /mnt/c/Users/<UserName>/, and you can often simply type pwd when opening a new Windows shell.

So these are different locations on your computer’s hard drive, and you will not see your Linux files in your Windows Home Directory and vice versa. To make it easy to switch between the two, I found this page on Microsoft’s web site that goes through some of the post-WSL2 installation steps, but see especially the additional page on Windows Terminal configuration.

Slightly confusingly, you can run Linux commands directly from Windows, usually be adding wsl in front of the Linux command (e.g. wsl ls *.csv from Windows, where in Linux the command would be ls *.csv).

To make it easy to move from the Linux side of your machine to the Windows machine you can also do this:

  1. Work out where your CASA files are stored on the Windows side (see above: /mnt/c/Users/<UserName>/My\ Documents/CASA/... where <UserName> is your Windows user name).
  2. cd to this location and type pwd to output the full path to the CASA directory.
  3. Copy this.
  4. Now start a Linux shell and run the following command once (you do not need to do it ever again): echo "export WIN_HOME=\"/mnt/c/Users/.../CASA/\"" >> $HOME/.bashrc. Replace the ... with the rest of the actual path! The \" is very important, don’t try to change those!
  5. Now run source .bashrc and you should see no errors.

Once you have done this you will have added a single line to your .bashrc file in Linux. This will create a ‘shortcut’ for bash in Linux. From here on out you should be able to type cd $WIN_HOME and move immediately over to the CASA directory on the Windows side. This will save having to remember (and type) the Windows path each time.