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:
- 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.
- 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.
- Start VirtualBox and select Import Appliance... from the File
menu. Browse to the Ubuntu image.
- 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.
- In VirtualBox, use the menus to start the image. You will
probably want to resize the window so it uses more of the screen.
- 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.
- 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.
If
you have problems with installing guest additions, a simple fix is to
use apt:
$ sudo apt install virtualbox-guest-utils
- 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
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.
- 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
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.
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.
- 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.
- 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.
- Use Git to retrieve the code for this lab:
$ git clone https://hasker@bitbucket.org/hasker/cube
- 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.
- 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.
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.
- 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.
Once you have modified the code, re-run the tests to confirm they now fail:
$ sudo docker build ./
- 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.
- 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 1000
3 is very close to 2
billion and 1500
3 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.
- Use Docker to ensure all tests pass. Do not
capture any evidence data from this run.
- 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.
- 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.
- 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.
- 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.
- 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
- You get a blank screen when Ubuntu starts up. Sometimes this clears
in several minutes; it pays to be patient. But this is also a symptom of
having installed Docker directly on Windows (instead of in the Ubuntu
VM); you will need to uninstall Docker to get VirtualBox to work for this
and other courses.
- The VM is not responding to mouse clicks. For example, you can
open a Terminal window but cannot move it using the mouse. Try shutting
down the Unix session ("ACPI Shutdown") and then completely shut down
VirtualBox. On Windows, it seems necessary to reboot your computer.
If that does not work, please contact me.
- You get the message Unable to insert the virtual optical
disk.../VBoxGuestAdditions.iso into the machine. This
typically means the disk is already inserted; check for a disk icon in
the Activities bar on the left hand side of the screen. If you see it,
then it's already loaded.