These notes walk you through the process of constructing a virtual machine that you can use for developing and running the LLP sample programs and exercises. They have been updated to show the most recent versions of the VirtualBox software and Ubuntu Linux that were available in December 2018, but some changes will likely be needed as new versions of these programs are released. These instructions also assume that you are using a computer with macOS; again you will need to make some adjustments if you are using a different type of computer, although the overall process should look very similar.

[Last updated: January 4, 2019. Added gcc-multilib and g++-multilib to the list of recommended/required packages because it seems that some attempts to compile 32-bit code on a 64-bit machine (using the -m32 flag) may not work correctly without them. Note that although the text has now been updated to include these packages, the associated screenshot has not been modified.]

Step 1: Download VirtualBox-5.2.22-126460-OSX.dmg and SHA356SUMS.txt from https://virtualbox.org. As an optional step, you can verify that the download was correct by using the following commands (the two output hashes should match):

    cat SHA256SUMS.txt | grep dmg
    shasum -a 256 VirtualBox-5.2.22-126460-OSX.dmg 

Step 2: Download ubuntu-18.04.1-desktop-amd64.iso from https://www.ubuntu.com/#download (Select 18.04 LTS).

Step 3: Open VirtualBox:

When prompted for details about the hard disk, choose a size somewhere in the region of 20-25GB, VDI format, dynamically allocated, and then press "Create":

Step 4: After the new virtual machine has been created, press the "Settings" button:

And then select the "Storage" tab followed by the "Empty" CD Rom drive icon under "Controller: IDE":

Click on the CD Rom icon on the right of "IDE Secondary Master" (in the "Attributes" section on the right hand side); select "Choose Virtual Optical Disk File ..." and navigate to the the Ubuntu image file that you downloaded in Step 2. Click "OK" and then double click on the LLPVM to start your virtual machine for the first time so that we can install Linux on it!

Step 5: After the virtual machine boots from the (virtual) CD Rom, it will display a splash screen like the following:

Select "Install Ubuntu", and the appropriate keyboard type. On the "Updates and other software" screen, select "Minimal installation (Web browser and basic utilities)" and "Download updates while installing Ubuntu" and then press "Continue":

Next, select "Erase disk and install Ubuntu" and then press "Install Now":

Confirm the details that are displayed:

And then enter a suitable user name and password. In the following, I've used llp as the user name and cemlabs as the password; unless you're planning to make the virtual machine accessible to the Internet, you probably don't need to worry too much about using a complex password: access to your virtual machine will be restricted and protected in the same way as your account on the host machine:

The installer will now begin to copy the necessary files to run Linux on to the virtual hard drive of your virtual machine; this may take a few minutes (or longer, depending on the speed of the host computer):

When the installation is complete, press the "Restart Now" button to restart your virtual machine. You may need to eject the virtual CD Rom containing the Ubuntu distribution at this point; you can take care of this using the CD Rom icon on the bottom of the Virtual Box window:

Step 6: Your new virtual machine should now boot and display a login page. Click on the llp user name (or whatever name you chose):

Enter your password and press "Sign In":

And you will be greeted by a sequence of screens introducing you to "What's new in Ubuntu":

Soon, you will be looking at a clean desktop something like this:

Step 7: The next step is to install the extra software packages that we need to compile and run LLP programs. For starters, we're going to be using the "Terminal" a lot, so click the Apps icon in the lower left corner of the screen and select the "Terminal" application:

I recommend that you add the "Terminal" app to the dock on the left of the screen; to do this, just click the icon and select "Add to Favorites":

In the terminal type the following command to download and install each of the named packages:

   sudo apt install gcc make perl linux-headers-$(uname -r) \
      build-essential dkms clang llvm qemu xorriso libc6-x32 \
      parted default-jdk git ant gcc-multilib g++-multilib

The command about can be typed on one line as shown in the screen shot, or you can do it in steps, repeating the sudo apt install part of the command for each group of packages. Either way, because you're using the sudo command here, you'll be asked to enter your password:

The system will then figure out which packages it needs to download and install (which will likely be much longer than the specific list you provided because it will also include all the additional package dependencies). Enter "Y" and press "Enter" to confirm that this is ok:

And now wait for the downloads and installation to complete. The following screen shot shows what this might look like part way through the process:

Step 8: Now we should be able to intall the "VirtualBox Guest Additions", which will give you a bit more flexibility in using the virtual machine (including the ability to resize the virtual machine window, used shared folders, and even copy and paste between your virtual machine and the real computer). To begin this process, use the option at the bottom of the "Devices" menu while the virtual machine is running; this will simulate the effect of inserting a (virtual) CD in to a (virtual) drive and will result in a pop-up message like the following:

Once again, you will be expected to provide your password:

And then you will have to wait again for the installation to finish. As the message on screen says: "This may take a while." ...

... but it should still finish successfully, at which point you can press "Return" to end the process. This might also be a good time to eject the virtual CD (from the "Device" menu, the icon at the bottom of the screen, or on the Linux desktop):

Step 9: We're almost done, but we need to configure "Shared Folders" so that your virtual machine can access files stored on your host computer; this feature will make it easy to transfer files between the two machines. As a first step, we need to execute the following command so that the llp account has access to the shared folders feature:

   sudo adduser user  vboxsf

To complete the process, we need to turn off the virtual machine so that we can modify its settings. Start by clicking on the down-arrow symbol in the top right corner of the screen, and then press the button marked with a power symbol:

Press "Power Off" to confirm that this really is what you want to do!

Once you are back in the VirtualBox interface, bring up the settings for your virtual machine and navigate to the "Shared Folders" tab. Select the folder on your host machine that you want to have access to in the virtual machine (this might be your ~/Documents/llp folder for example, although the screen shot shows a different path); enter llp as the "Folder Name"; select "Auto-mount" so that you will automatically have access to the shared folder every time the virtual machine starts; and then press "OK":

Restart your virtual machine, open a terminal window, and enter the following command:

  ln -s /media/sf_llp llp

Step 10: Now, at last, the fun begins! Once you have downloaded the LLP "hello" demo to your llp folder, for example, you will be able to use the following commands to compile and run a simple "bare metal" demonstration program:

  cd ~/llp/hello
  make run

Happy (virtual) computing!