SE 3800, Assignment 1
Google Test with Docker

In this assignment will set up your computer to do C++ development with Docker and write tests in Unix. The directions assume you are using the school laptop with Windows installed. If you have a Linux system already set up and find that more convenient to use, you can use that as well. Mac OSX users might also be able to use the Unix on their system.

Warning: do not install Docker directly into Windows on your school laptop. Doing so will make it difficult, if not impossible, to use VirtualBox on the same system. This will make it difficult to complete other CS/SE courses. It can be very difficult to remove Docker once it is installed; we have stories of students having to reimage their laptops to remove it. (As of version 6 of Virtual Box there is some support for using Virtual Box with Hyper-V, but it is still highly possible that you will need to reimage your laptop to use VirtualBox in other courses.)

Note: to complete these steps, some Windows users at MSOE will need to turn on virtualization support in the BIOS. This is not an issue for macOS computers. If your MSOE laptop does not have virtualization support enabled, you will need to visit IT to have it turned on. This can be done at any point - you can install the software without virtualization, but some steps will fail. You may also need VT-x (that is, Intel Hyper-threading) to be enabled in the BIOS. See IT if you cannot access the BIOS yourself. In some cases you may need to disable Hyper-V in the Windows Feature list.

The following directions have you install Ubuntu, but you can use other variants of Unix to complete this assignment. The primary reason to use Ubuntu in this assignment is that it's been tested. You should be able to complete the assignment using any version of Unix (such as Mac OSX) that supports Docker.

Note: If you run into problems, there is a good chance someone else has run into it as well. Check the Common Problems and Solutions section at the bottom of this page, and if your problem is not in that list then contact your instructor with the error message and symptoms you are seeing.

Steps:

  1. Download and install VirtualBox
    • Unless you are using a nonstandard operating system on your school laptop, you will want to download the Windows version.
    • Be sure to install all parts including the USB and Network Devices
    • Download and install the Oracle VM VirtualBox Extension Pack (available on the same page) after installing VirtualBox. This enables USB 2.0/3.0 and other features.
  2. Download Ubuntu22v3Cucumber.ova. You may have to log in to Box to access it. You can save it to a permanent folder, but running out of the downloads folder is fine, and you can delete the file once your Ubuntu system is running. This is a recent Ubuntu image with desktop support enabled. If you cannot access this image, you can install a different Ubuntu image instead; talk to me if you need help.
  3. Start VirtualBox and select Import Appliance... from the File menu. Browse to the Ubuntu image.
  4. To support copy/paste between the host and guest, right click on the imported virtual machine image (what VirtualBox calls the "appliance" in the previous step) and select Settings... Click on the Advanced tab and set both Shared Clipboard and Drag'n'Drop to Bidirectional. But note you will also need to an additional step below.
  5. In VirtualBox, use the menus to start the image. You will probably want to resize the window so it uses more of the screen.
  6. When Ubuntu starts up, log on as user osboxes using password "osboxes"
    If you wait at least five minutes and the password prompt is still not there - that is, the screen is blank - try halting the image and restarting it. If that doesn't work, you may have missed a step; it's important that all of the above steps are executed carefully. An ultimate fix is to uninstall VirtualBox, reboot your computer, and then reinstall it, following the above directions very carefully. Be sure you do not have Docker installed as a Windows application - it must be run from within a VM! If a reinstall does not help, talk to your instructor.
    • If you already installed Docker, you will need to uninstall it and visit this page for hints on cleaning up after Docker. In particular, you will need to disable Hyper-V. Some people report success by following this page instead.
  7. Once Ubuntu is running, click on the Devices menu and select Insert Guest Additions CD image... If nothing starts, open the CD image by opening it, right clicking on autorun.sh, and selecting Run as a Program. Go through the installation steps as indicated (selecting any defaults). You may have to shut down and restart the VM to enable copy/paste. You can right click on the .iso to eject it from your Ubuntu desktop.

    8. If you have problems with installing guest additions, a simple fix is to use apt:

    $ sudo apt install virtualbox-guest-utils
  8. Explore Ubuntu. Some things to consider changing:
    • To change the timeout and reduce the number of times you have to enter the password, click on the machine control icon picture of multiple connected computers in the upper right corner, Settings, select the Power tab and select Never for when to blank the screen. You might also try turning off Automatic Suspend (both on battery power and when plugged in). Use the X in the upper right corner to close the window.
    • Open up a terminal prompt (see below) and change your password by entering the command passwd.
  9. Press Ctrl-Alt-T to open a terminal window. This is also known as a command prompt. If you cannot remember the shortcut, or it does not work, click on the applications icon 9 dot icon in the lower left corner and enter "ter" in the search box. Terminal will be one of the results. Note the triple-bar menu has a way to increase font size.

    10. The prompt for the Terminal window defaults to giving your username, machine name, current directory, and a $. For brevity, the prompt will be shown in this writeup as simply $.

    You should be able to copy/paste text from the main computer into the Ubuntu window, but you can open this writeup in Firefox from within Ubuntu to copy/paste from there instead.

  10. Confirm that Docker is installed and running:
    $ sudo docker run hello-world
    If things are working, you'll get a message saying "Hello from Docker!" along with other information. If you don't, post your error to Teams and someone will help. The most common error is to not type the command exactly as written above; upper case or underscores instead of dashes will make things fail.
    • One simple thing to try if Docker is not working is to update Ubuntu. Open up the list of applications and run Software Updater. This will look for updates and attempt to install them. You can do the same thing from the command prompt by opening a Terminal window and typing
      $ sudo apt update $ sudo apt upgrade
      likely followed by a Linux reboot. However, Software Updater is more robust.
  11. Type
    $ sudo docker ps -a
    to view the running Docker containers. Unless you have run hello-world more than once, you would likely see just one item. You can remove all of the docker containers by typing
    $ sudo docker rm $(sudo docker ps -aq)
    The docker ps -aq command lists all running container ids, putting it between $( and ) substitutes those numbers on the command prompt, and docker rm deletes the named containers.
  12. Use Git to retrieve the code for this lab:
    $ git clone https://hasker@bitbucket.org/hasker/cube
  13. Change the current directory to the newly created one:
    $ cd cube
    Note you can type cd .. to go "up" to the current directory's parent and cd ~ to go to your home directory.
  14. From the cube directory, type
    $ sudo docker build ./
    to build the Docker container. This is controlled by the Dockerfile (you can click the link to view the file) which creates a container with version 18.04 of Ubuntu, installs G++, git, and GoogleTest, sets up GoogleTest, and copies the source files into the directory /cube in the Docker container. The nice thing is that if you repeat the build, Docker does not have to re-execute all of these steps, making it much faster. It will finish by building cube_test and running it; all test cases should pass.

    15. The last line of this should say Successfully built followed by a large hex number. This is the ID of the container. You can use mnemonic ids, but it's not important at the moment. Again, if you see other results, post on Teams for help. A nice thing about virtual machines (VMs) is that you can create copies for future experiments without destroying work that you have already done.

  15. Modify the code so that the tests fail. To do this, you'll need an editor. One option is vi (sudo apt install -y vi), but most students will be happier with a mouse-based editor. I use Atom; this should be installed, but if not you can install it by
    $ snap install atom
    If you are used to a different Unix editor, feel free to install and use that instead.

    Be careful! Make sure your modified code still builds and passes at least some of the tests. Syntax errors or errors that fail every test are not particular interesting ways to ensure your Docker environment can catch programming errors.

    16. Once you have modified the code, re-run the tests to confirm they now fail:

    $ sudo docker build ./

  16. If you type docker ps -a you will see that new containers have been created. Adding the --rm option to build will remove the containers when they are done.
  17. Revise the code so all tests will pass again and confirm that they do by typing
    $ sudo docker build --rm ./

Submission

Your submission to this assignment will be an evidence document that shows that you successfully installed Docker, can use it to identify when tests fail, and can use it to show that all tests pass. Much of this is done by capturing screen output. Use Windows Snip & Sketch (or Control-Command-4 on a Mac) to capture the output; do not copy/paste directly from the terminal. Be careful in how you capture the screen output; if you have lots of blank space, your text is too small for someone else to read. It is like trying to count craters on the moon in a picture when the moon is small surrounded by lots of black space. Be sure you crop your image to the important parts so your evidence document is focused on the important bits. This usually includes output and critical context such as the commands you used to generate that output.

As part of your submission, you will need to extend the tests in cube_test.cpp and improve the implementation for the cube program. The provided code works fine for small integers, but large integers result in numeric overflow. Type

$ g++ main.cpp cube.cpp $ ./a.out
to build and run the program under Ubuntu (rather than Docker). Try cubing 1000 and notice that it gives a large number near 2 billion. Then try cubing 2000; the fact that the result is negative shows your processor overflowed. Since 10003 is very close to 2 billion and 15003 is too large, you can use a bit of trial-and-error (hint: use binary search!) to find the largest number that does not overflow. Change cube.cpp to return 0 for all of the cases where it overflows. (Often you would raise an exception, but we are going for simplicity.) Then add tests that ensures the largest number returns the right result and the next largest number returns 0.

  1. Use Docker to ensure all tests pass. Do not capture any evidence data from this run.
  2. Modify cube.cpp so that one of the tests fails. Then type
    $ sudo docker build --rm ./
    Then use Windows Snip & Sketch to capture running the docker command, keeping in mind the dangers of capturing a lot of blank space. (A little is fine, of course; really bad cases are where half the image is blank.)
    If you have run Docker on exactly this code before, it will tell you that the results are unchanged from a previous run. Simply edit cube.cpp by adding a few spaces at the end of a line (or some other trivial change) to force rebuilding and reexecuting the project, then use Snip & Sketch to capture this run instead.
  3. Create a Word document with the assignment name, your name, and the date you completed the assignment at the top. Copy the output from the first Docker run to this document.
  4. Type
    $ cat cube.cpp $ cat cube_test.cpp
    and use Snip & Sketch to capture this output and place it in your Word document. Note you are displaying the code with both the overflow correction in place and the error you introduced so I know what you broke and what tests you have that show this is an error. These are separate steps so the source code does not scroll the other output off the top of the terminal window. If you need to, resize windows or otherwise manipulate them so you capture useful evidence.
  5. Fix your code (undoing the error you introduced in step 2 above), make one other change to the code such as adding a space to the end of a line, and re-run the Docker command, capturing the output now showing your solution is correct. You do not need to capture the fixed version of the code; my goal is to make sure you know how to use Docker to show your code fails and to show that it works. Copy this run to the Word document. Caution: if you return your code to an exact state that it was earlier, Docker will just report that the new results are the same without re-running the tests. I need to see the output showing that all tests are now passing. Adding a space or other whitespace to your file will ensure the tests are re-run.
  6. Use print-to-PDF or some other tool to convert the Word document into PDF format.

Submit your evidence document (as a PDF) to Canvas. Please do not submit any additional files; in particular, do not submit zip files or additional sources.

Common Problems and Solutions