Windows notes

Disclaimer
Linux on Windows
Native mode
Additional Docker configuration
Drive mount configuration
Directory location
Text file formats
Running Git

TL;DR If you have issues you cannot fix, we recommend using Google Cloud Shell to develop remotely on a Linux machine instead of developing locally on Windows.

Disclaimer

Linux integration on Windows can be difficult to work with because of conflicting filesystem conventions, which necessitate some hacky ways to connect Linux-generated files to the native Windows filesystem. We have done some work to set up our development environment for Windows, but this environment is untested and unmaintained because none of the instructors have access to a native Windows environment. Windows users may try the instructions below to get the development environment running, but you will need a solid understanding of Linux, the way that Linux integrates with Windows, and how to fix subtle issues with drive mappings / permissions in order to get everything to work.

If you have issues you cannot fix, we recommend using Google Cloud Shell.

Linux on Windows

The development environment contains a few bash shell scripts to manage various options and docker commands. On Windows 10+, you can set up the Windows Subsystem for Linux to install Ubuntu 22.04 and have access to bash for running the scripts. You will probably want to enable copy and paste inside the ubuntu program.

Native mode

Since WSL runs the same version of Ubuntu by default as used in the development environment, the development environment scripts have been adapted to run natively in WSL. The scripts install a set of required packages and libraries, and some utility scripts. Note that these installations happen directly in WSL, so running native mode affect your WSL installation. The package update scripts will ask for your password in order to run sudo to install packages.

To start the environment in native mode run with the -n flag:

$ tools/env/start.sh -u ${USER} -n

Additional Docker configuration

NOTE: If the docker command already works inside WSL (which may be the case with newer installations) then you should skip these steps.

In Docker for Windows Settings, go to the Resources tab and WSL INTEGRATION subtab. Enable Enable integration with my default WSL distro and then turn the toggles on for the Linux distro you are using for this class.

Quit docker and restart it. Docker should now work within WSL as long as Docker Desktop is running in Windows.

Verify that docker works:

$ docker run -it hello-world

See this article from Microsoft for more info.

Drive mount configuration

Next you’ll need to tell WSL to mount drives at / instead of /mnt, because the Docker for Windows program expects drives at / (e.g. C: is at /c/, not /mnt/c/), and docker in ubuntu will be passing native paths directly to Docker for Windows. You’ll also want to enable metadata on the mounts so that you can have unix-compatible permissions on your Windows drives:

$ sudo tee -a /etc/wsl.conf << EOF
[automount]
root = /
options = "metadata"
EOF

Directory location

The portion of Docker for Windows that runs containers is running outside of WSL, so it does not have access to any of the native paths inside WSL. As such, you will need to locate your main development cs130 directory somewhere on your C: drive, and access it through WSL via /c/some/path/to/cs130. You should clone the tools repository into this directory, and also run the start.sh script from this directory under /c/.

Text file formats

Since you will be potentially using a Windows IDE to edit the same files that you are processing on Linux, and Linux tools do not handle Windows-style carriage returns well, you should ensure that your text files are saved in Unix format, with \n line feeds (as opposed to \r\n in Windows format). To ensure files are saved into your repository in this format, create a .gitattributes file in the root of your project:

$ echo "* text eol=lf" > .gitattributes
$ git add .gitattributes
$ git commit

This will force git to check out all files in Unix format, and keep them in Unix format in the repository. Visual Studio Code allows editing of Unix-format files on Windows (see the LF indicator in the lower right).

See this article on github for more information.

Running Git

You will have the best results by always running git inside WSL.