Set Up Your Development Environment (Without Docker)¶

Windows 10¶

Note: I have done my best to make sure these instructions are correct and complete by going through them a couple of times on my own laptops. However, those already had the tools installed and so there might have been some vestiges from previous installations when I went through the reinstallation process. As a result, some things might have worked for me that might not for you. If this is the case and if things don’t go according to plan, notify the instructional staff right away (via Piazza) so that we can issue a clarification / correction. If you figure out the right steps yourself, post that to Piazza.

The basic steps are:

• Enable Windows Subsystem for Linux

• Install Ubuntu 20.04 from the Microsoft Store and launch it once to set username and password

• Go through some magic steps to configure your Windows Subsystem for Linux (WSL) environment

• Install additional packages

• Install and configure Visual Studo Code (vscode)

Enable Windows Subsystem for Linux

You can enable WSL through a control panel rather than on the command line: Open the control panel and select “turn windows features on or off”. Check the box next to “Turn Windows Subsystem for Linux.” You will need to reboot for this to take effect.

Install Ubuntu 20.04

Once you have rebooted, go to the Microsoft Store and search for “ubuntu”. You will have choice of 3 (or more) versions. Choose 20.04 and select install. For this course, we will be accessing WSL via vscode. However, there is a setup process to go through (just once) before we use it through vscode. You can launch a bash shell by typing bash into the start menu. NB: You can also use the command “ubuntu” in the start menu.

Additional info on installing ubuntu on WSL can be found here:

https://ubuntu.com/wsl

When the bash window launches for the first time it will ask you for a username and a password. This “account” is completely within the WSL universe and has nothing to do with your account on the host (Win10) computer. For a username you can enter anything you like, but I suggest using your UW network id or the username that you use on your machine. Choose whatever password you like. Once you have gone through that process you will be presented with a prompt; you can exit from bash with the “exit” command.

Cast Two Magic Spells The linux subsystem that has been installed ``thinks’’ it is in its own world. The filesystem and directory structure appear as they would for a natively installed linux distro – in the default post-install configuration, it will not be connected to the files and folders that you see through Windows Explorer. But, since vscode (and all other native Windows applications) work with files and folders in the Windows space – we need to connect the two. To do that, we are going to create a course folder in your Documents folder and set that to be your home directory under WSL.

In the first magic spell, we need to adjust the configuration of how WSL “sees” the windows NTFS file system. To do this we will n eed to install a text editor. From a WSL window, type the following:

$ sudo apt update

Do not type the dollar sign – that is just a placeholder for the terminal prompt. The apt update command will update your the ubuntu package manager so that it knows which packages it can install and where to download them from. The apt command requires elevated privileges—typing sudo before a command will allow that subsequent command to be executed under elevated privileges. Note that you may be asked for your WSL password.

Next we need to install the “nano” text editor using the apt-get command:

$ sudo apt-get install -y nano

Once nano is installed we are ready to configure the WSL filesystem.

To cast the first Magic Spell, from a WSL window, type the following

$ sudo nano /etc/wsl.conf

(This is a privileged file, hence we need to edit it with elevated privileges.) This will open the nano editor on a new file /etc/wsl.conf. In the nano window, type the following:

[automount]
options = "metadata"

Make sure to put a new line after the second line.

Type the key combination ^O (ctrl-O) to save the file and then ^X to exit.

Now we need to restart WSL. First, close all of your WSL windows. Then, from the start menu, type “command” to open a command window. In the command window type

C:\> wsl --shutdown

(don’t type the C:\> – that’s a placeholder for whatever your prompt is.) This will shutdown WSL on your system. When we start it again, it will have the new settings we just established.

Next, in the command window, type the following:

C:\> wsl -u root

You should get back something like

root@machine:/mnt/c/Users/<win10id>#

where win10id is your Windows short user id.

Now issue the Magic Spell

root@machine:/mnt/c/Users/<win10id>#  usermod -d /mnt/c/Users/<win10id>/Documents/amath583 -m <userid>

where userid is the user id that you created above when you first started WSL. This will make a new directory in your documents folder called “amath583” and designate that as your home directory under WSL.

Next, type

root@machine:/mnt/c/Users/<win10id>#  exit

and then close the command window.

OneDrive Users If you are using OneDrive on your Windows 10 laptop, your Documents folder may be in a different place, depending on how you have OneDrive configured. If you are syncing your Documents folder to OneDrive, you may want to use

root@machine:/mnt/c/Users/<win10id>#  usermod -d '/mnt/c/Users/<win10id>/OneDrive - UW/Documents/amath583' -m <userid>

rather than the path above. Make sure to include the single quotes in this case so that the spaces in the path are properly handled.

Now, start wsl again by typing either bash or ubuntu in the start menu. You will get a slightly different terminal window depending on which you invoke but there should not be any functional difference. You may want to pin whichever window you open to the task bar to make it easier to open in the future.

Now, let’s verify your home directory was properly set. First, navigate with Windows to your Documents and folder and verify that there is now a sub-folder there named amath583.

Second, from the prompt in a WSL window

$ pwd

This requests the shell you are in (the bash shell) to print the directory you are in. If you invoked ubuntu, it should print the directory we just created above. If you invoked bash, it may print some system directory. In that case, issue the commands

$ cd
$ pwd

The cd commmand will change the directory to your home directory and the pwd will print it. At that point, it should be the home directory created before.

Next, list the files in that directory

$ ls

You should get nothing back – the directory appears to be empty. If you instead type

$ ls -a

you will see a few “dot files”. Files starting with the dot character are typically used as configuration files and are normally hidden when you list a directory — unless you specify the “-a” flag. Dot files are not special in Windows. When you navigated to this folder under Windows you should also have seen the dot files.

Example On my Windows laptop my login id is “tony”. If I look in the Users subdirectory on the C: drive, there is a folder called “tony” and that is where all of my files are. When I need to login to my Windows laptop it shows “tony” as the user. (Personal computers sometimes will try to be helpful and show you your actual name instead – you don’t want to use that, you want the actual short user id). Further, the linux id I created for linux is the same as my UW id – “x0”. So I changed /home/x0 to /mnt/c/Users/x0/Documents/amath583

Important Despite the utter coolness of being able to run actual Linux programs under Windows, the two systems don’t always play nicely together. Be careful of using Windows programs (other than vscode) on the files in your working directory. Bad things can happen.

Install Your Development Tools As mentioned above, you need to install a few tools in your linux environment. The package manager tools in Ubuntu Linux are called apt and apt-get. To use them to install the necessary tools for this course, issue the following sequence of commands:

$ sudo apt-get update
$ sudo apt-get install apt-utils
$ sudo apt-get install clang lldb man make net-tools ssh wget

This process may run for a while but after some minutes you will be back at the bash prompt. You may be prompted (on the command line) whether or not to continue with certain installations – it is safe to answer ‘y’. You can also use the -y option in the install steps:

$ sudo apt-get install -y apt-utils
$ sudo apt-get install -y clang lldb man make net-tools ssh wget

to automatically answer ‘yes’ to proceeding.

You may also be prompted to choose your geographical area and timezone. Choose as is appropriate for your local situation.

To check quickly that the installation worked, type

$ c++ --version

It should report to you that clang version 10 is installed.

Install Visual Studio Code You can search for Visual Studio Code with Google and download the installer from a site at Microsoft. Note that Visual Studio Code is not the same (at all) as Visual Studio, so be sure to search for Visual Studio Code and not just Visual Studio.

Customize Visual Studio Code Once vscode is installed, you need to adjust a couple of settings. Right click on the gear icon in the lower left corner of vscode and select ``Command Palette’’. At the command palette prompt, type ``Terminal: Select Default Shell’’. You will get a drop down menu with three choices. Select ``WSL Bash.’’

Now click on Terminal in the vscode menu bar and select ``New Terminal’’. A window will open in the bottom half of vscode. You should see a bash prompt there. Issue the command

$ cd

To go to your home directory. (The shell defaults to a different initial directory than your home.) You can also start a terminal with the ctrl+ \ key combination (control and back-tick together). The terminal should behave just like a bash shell that you start from the start menu.

Finally, in the left hand column there are some icons, the bottom of which are four square boxes (more or less). Click on that to bring up an extensions panel. The third (or so) entry should be C++ intellisense. Click to install that. There are a huge number of other extensions that you might want to browse and explore, but the most important one is C++ intellisense. If C++ intellisense is not the near the top of the list, you can search for it in the search bar at the top of that column.

(I suggest also installing live share and live share extensions to enable collaborative editing.)

Mac OS X¶

Mac OS X has a version of Unix at it’s heart (the Berkeley Standard Distribution, or BSD) that actually predates Linux. As such, many of the tools we need are already installed (or installable via the Mac OS X ecosystem), so creating the course standard configuration is much more straightforward.

The basic steps are:

• Install command-line tools for Xcode

• Install visual studio code

You can actually install the command-line tools without installing all of Xcode. Since we only need the command-line tools, this is what I recommend.

Open a terminal (launch Terminal.app) – this will bring up a window with a bash shell. From that window type

$ xcode-select --install

This will bring up a pop-up window. Just select “install”.

NB: If you just select install rather than installing all of xcode you may require an extra step on Mojave (and Catalina).

For Mojave and earlier, check if there are files contained in the path /usr/include. That is, in a terminal window, run the command

$ ls /usr/include

If there are no files (or no include directory), then run the following:

$ sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /

For Catalina and later, check that there are files in the following directory:

$ ls /Library/Developer/CommandLineTools/SDKs/MacOSX10.15.sdk/usr/include/

Remember the path where you found the include files, you’ll need it for compiling the assignment below.

All of the tools needed for the course (for now) will now be installed.

Make a Work Directory Since Mac OS X is Unix, the command line tools are completely integrated and compatible with the GUI tools – and there is only one filesystem. I suggest creating a subdirectory under your Documents folder (or wherever you like) to hold all of your course materials in one place.

When you open Terminal.app the shell will start up at your home directory. Issuing

$ pwd

will print

/Users/<yourid>

If you issue

$ ls

it will print the contents of your home folder (home directory), which may have alot of things, including your Documents folder, Pictures folder, etc.

Install Visual Studio Code The Mac OS X installer, with corresponding instructions, for vscode can be found here

https://code.visualstudio.com/download

The key combination for starting a terminal shell within vscode on Mac OS is ctrl+~.

Linux¶

If you are running your own linux, review the list of tools above for WSL and make sure you have those installed. Most important will be a recent version of clang. Visual Studio Code is also available for Linux, so make sure to install that as well.

$ cd /
$ cd tmp

$ cd /tmp

$ ls tmp
$ ls /tmp

$ man ls