Installation

  1. Download and install VirtualBox. Note: it is safe to keep all of the defaults for installation. If you are having trouble, there are more detailed instructions on the site.
  2. Download the virtual machine image. If your browser asks you what you want to do with the file, just save it – don’t try to open it yet. NOTE: The file is large; this may go faster if download it from NAC rather than from home.
  3. To install the virtual machine, use the File..Import appliance menu, or just hit Ctrl-I. The steps are simple, and it is safe to keep all of the defaults.
  4. Make sure the virtual machine is working: select it from the list on the left and hit “start” from the menu, or just hit enter, or double-click it. This should start the OS in a new window.
  5. You should soon be greeted by a picture of some bamboo or something. If so, rejoice :D Otherwise, you might want to check that the download completed properly. To do this (on a *nix system, including mac), check the SHA-1 hash by running sha1sum arch-103-S17.ova1 and making sure that the output is:

    8191a0143f43e5b173cd62bdb0b742fd03703253

Notes

Getting Started

The virtual machine uses a tiling window manager which may take a moment to get used to. Here are the basic commands you’ll need to know to make good use of it.

  1. To open a program by name, hit alt+d and then type the name. Use the tab key to auto-complete. Try opening firefox this way.
  2. You can close any window with shift+alt+q.
  3. To get a new terminal, just press alt+enter. From the command line, you can use the command $ open [filename] and it will usually figure out the right program to open filename with.
  4. You have multiple desktops / workspaces. You can reach them with alt+1,alt+2,alt+3, etc. Try opening firefox in a new workspace (switch to workspace 2, and then open firefox).
  5. You can move between windows with or without the mouse. Using the mouse, just move the cursor over the desired window to focus it. Using the keyboard, press alt+j to focus a window to the left, alt+; to focus the right. alt+k and alt+l move up and down.
  6. If a window feels too small, you can make it fullscreen with alt+f, or move it to another workspace with say, shift+alt+2 (this moves it to workspace 2).
  7. If you want the next window to appear below the current, use alt+h before running the next program. To go back to a vertical split, use alt+v.
  8. Try to use Vim. It is so worth it… Just run the command $ vimtutor to get started. There are also some links to tutorials on the course information page.
  9. I would recommend using cd, ls, cp, mv, rm and such instead of a file manager, but if you long for that windows explorer feel, try running thunar.
  10. Important: To gracefully shutdown the machine, use shift+alt+e, and then press w. Do not just close the virtual machine window! (Closing the window is the equivalent of pulling the plug on a real machine, and may leave the disk in an inconsistent state.)

Other Remarks

  1. The virtual machine has all the tools you’ll need to build C++ programs, and should give you a pleasant programming experience. Feel free to develop on other platforms if you want, but in that case, help with technical issues will not be forthcoming.
  2. Use full-screen mode to get resolution beyond 1024x768. (Something like right-control + f.) If this doesn’t work, see below.
  3. Sometimes keys (e.g. the shift key) get “stuck” after moving from the virtual machine back to the regular OS. This can usually be avoided by using the mouse to switch to and from the VM window (instead of alt-tab). If a key does get stuck, random button mashing might actually be the answer. Just do it somewhere safe!
  4. Copy and pasting in the terminal: If you just highlight text with the mouse in your terminal it will be copied to a clipboard. To paste this into another terminal window, you can use Shift+Insert, or middle click the mouse (if you only have two buttons, try tapping them both at the same time to get a middle click). However, pasting stuff into your terminal can be dangerous as you may end up running an unintended command. As an alternative, you can try using tmux, which lets you do all this (and much more) with the keyboard.

Setting the Screen Size

You can put VirtualBox in full screen mode from the menus, or by hitting ctrl-f (using the right control key by default). Normally the resolution will expand to fill the entire screen, leaving no black regions on the sides, top, or bottom. However, in some cases this does not work, and the screen does not fill the entire space. I’ve left a workaround for this already. Here are the steps:

First, you need to figure out what screen resolution is right. To get a list of candidates, you can either lift it from your normal OS, or run this command in the virtual machine, first making sure full screen mode (with the black borders) is active:

$ xrandr -q --current

Look for a mode with a + next to it. This is supposed to be the “preferred” mode for your screen. The current mode will be marked with an asterisk *. For my laptop, 1366x768 is preferred. In what follows, replace that with your choice, of course. Important: you should test out the mode before setting it! Do it like this:

$ modetest 1366x768

Hit ctrl-c if the new resolution looks right (it will be restored automatically in a few seconds otherwise).2 Once you have the right mode, do the following to make the changes permanent, again replacing “1366x768” with your choice.

$ cd ~/packages/dotfiles-103/
$ git pull
$ ln -s ~/packages/dotfiles-103/start-i3.sh ~/.config/
$ echo "1366x768" > ~/.config/x11mode

Backing Up / Sharing Data

It may be desirable to share data between your operating system and the virtual machine. This is easily accomplished by any of the following, in descending order of preference.

Getting Started with Linux

Here are a few references you might find useful if you haven’t used linux / unix much.

Advanced Configuration + Troubleshooting

  1. If you get an error along the lines of “hardware acceleration not available on your system”, then virtualization might not be enabled in your system’s BIOS. This isn’t strictly necessary, but doing everything in software can be quite slow. This article or this one might help you find the right settings if you haven’t been through your BIOS much.
  2. The VM is set to use 1GB of memory, which should be plenty (the desktop and some terminals should take only 60MB). However, if your computer does not have at least 2GB, you will want to reduce this amount, which can be done through the menus “Machine .. settings .. system .. motherboard”. I would try to give it at least 300MB if you want to run firefox, but you can get away with under 100MB and still run all the essential tools.
  3. If you don’t like the transparent terminal windows, or if they are misbehaving, you can turn them off via
    sed -i -e 's/\(^compton\)/# \1/' ~/.xinitrc
    and you can turn them back on again by running
    sed -i -e 's/^# \(compton\)/\1/' ~/.xinitrc
  4. You might be able to speed things up by enabling 2d acceleration in the virtual machine settings.
  5. The username and password of the main account are both csc103 if you ever need them. This is also the root password.


Back to the class homepage


  1. On windows, sadly you must resort to 3rd party software. You can try this, but I can’t vouch for it. Hopefully it just works in the first place!

  2. The modetest is a simple thing I left in your .bashrc. It is more or less just xrandr --output VGA-1 --mode 1366x768 && sleep 7 && xrandr --output VGA-1 --auto.