CSE 333 18su Homework #0

Out: Wednesday, June 20, 2018
Due: Monday, June 25, 2018 by 11:00 pm.

Summary.

For homework #0, you will fetch a source distribution that we have prepared. Next, you will trivially modify a simple hello world C application, use "make" to compile it, and run it to learn the magic code. You will also run a tool that checks your code for memory leaks and another that checks for potential style problems. Finally, you will package up and submit your code.

As you can probably tell, the real goal of this homework is to make sure that all of the course infrastructure is working for you.

Part A -- Fetch the code

Overview

Assignments will be distributed and collected using your CSE 333 GitLab repository. Starter code will be added to your repository by the course staff and you will tag your repository when you are done with an assignment to indicate which revision should be evaluated and graded by the course staff. More information about git and GitLab is given below and in other writeups on the course web site. We will demonstrate and discuss the process in sections during the first week of class.

Clone your GitLab repository

If you have not done so already, change to a directory where you want to store the local repository for your CSE 333 projects, then follow the instructions in the git writeup to clone your CSE 333 repository. The writeup is also linked to the main CSE 333 web page, and there are links there to the CSE GitLab site and other git resources. You can use the CSE GitLab web interface to browse your files and find out information about your repository, but you must clone a copy to a Linux machine to do your work.

You might have additional personal projects and repositories in GitLab for your own work, but be sure to use the repository provided by us for your CSE 333 course projects.

Once you have cloned the repository, change into that directory (it will be named something like cse333-18su-xyzzy, where xyzzy is your userid) then enter a ls command. You should see something like this:

bash% git clone git@gitlab.cs.washington.edu:cse333-18su-students/cse333-18su-xyzzy.git
-- git output appears here
bash% cd cse333-18su-xyzzy
bash% ls -a
.gitignore clint.py hw0

The .gitignore file lists file types that should not normally be saved in the repository. These are typically things like editor backup files (names ending in ~) and object files (ending in .o). They are files that are generated and used locally while you are working but are recreated as needed from files that are in the repository rather than archived permanently.

If you originally cloned your repository before the staff added the hw0 directory to it, enter a git pull command to bring your local copy up to date. Once you see the hw0 directory, enter cd hw0 to change into that directory to work on the assignment.

Part B -- edit, compile, and run hello_world

In the hw0 directory, type make. This command will use the instructions in file Makefile to compile the hello_world application using the gcc compiler. Run hello_world by typing the command ./hello_world. You should see one line of output that looks like:

bash% ./hello_world
The magic code is: <xxxxx>
bash%

for some <xxxxx>. Now, edit hello_world.c using your favorite Unix-based editor (mine is emacs), and change the printf so that it instead says:

bash% ./hello_world
The magic word is: <xxxxx>
bash%

Execute make to rebuild, and then re-run hello_world to make sure it does what you expect.

Part C -- experience the gdb debugger

You're unlikely to have any run time bugs in this homework, but let's use the debugger so that you know what it can do. Here is a session that launches the debugger, sets a breakpoint on source line 19 of hello_world.c, prints the values of a couple of variables and an expression, prints a "backtrace" of the stack (showing the sequence of procedure calls that led to executing line 19 of hello_world.c), and then continues execution. Type the italicized lines. (You may see some differences in gdb or Linux version numbers, or exact addresses of variables and code, but the data values should be basically the same.)

bash$ gdb ./hello_world 
GNU gdb (GDB) Fedora (7.4.50.20120120-54.fc17)
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-redhat-linux-gnu".  
For bug reporting instructions, please see: ...  
Reading symbols from /home/auser/cse333/hw0/hello_world...done.
(gdb) b 19
Breakpoint 1 at 0x400511: file hello_world.c, line 19.
(gdb) r
Starting program: /home/auser/cse333/hw0/hello_world 

Breakpoint 1, main (argc=1, argv=0x7fffffffe0c8) at hello_world.c:19
27  printf("The magic code is: %X\n", a + b);
(gdb) p argv[0]
$1 = 0x7fffffffe394 "/home/auser/cse333/hw0/hello_world"
(gdb) p a
$2 = -889262067
(gdb) p /x a
$3 = 0xcafef00d
(gdb) p a+b
$4 = -559038737
(gdb) bt
#0  main (argc=1, argv=0x7fffffffe0c8) at hello_world.c:19
(gdb) c
Continuing.
The magic code is: <xxxxxxxx>
[Inferior 1 (process 6760) exited normally]
(gdb) q
bash$

Notes: For gdb to be useful, you must give the -g switch to gcc when compiling. The make file we distributed does that. If you have already modified your file for part B you will see the new output message after "Continuing."

Part D -- verify you have no leaks

Throughout the quarter, we'll also be testing whether your code has any memory leaks. We'll be using Valgrind to do this. Try out Valgrind for yourself, to make sure you can run it:

  bash% valgrind --leak-check=full ./hello_world

Note that Valgrind prints out that no memory leaks were found.

Part E -- check for style issues

Another requirement during the quarter is that your code must be written in good style. Although there are many opinions about what constitutes "good style", in this course we will generally follow the Google C++ Style Guide for both C and C++ code. The repository files for this assignment included a Python script clint.py to check C source files for style issues. Try it yourself to be sure you can run it:

  bash% ../clint.py hello_world.c

No style-checking tool is perfect, but you should try to clean up any problems that clint detects unless clint flags something that is definitely not a problem in this particular context (but be sure you have very good reasons to ignore any warnings).

Turn in

Before turning in your assignment: create a README.TXT file in directory hw0 that contains your name, student number, and UW email address. As well, write a sentence that reveals the magic word you learned from Part B.

Once you're done, "turning in" the assignment is simple -- create an appropriate tag in your git repository to designate the revision (commit) that the course staff should examine for grading. But there are multiple ways to get this wrong, so you should carefully follow the following steps in this order. The idea is:

Tidy up and be sure that everything is properly committed and pushed to your GitLab repository.
Add a tag to your repository to specify the commit that corresponds to the finished assignment, after you have pushed all of your files.
Check out a fresh copy of the repository and verify that everything has been done properly.

1. Tidy up and be sure everything is properly committed. Commit all of your changes to your repository (see the beginning of the assignment or the main course web page for links to git information if you need a refresher on how to do this). Then in the hw0 directory:

  bash% git pull
  bash% make clean
  bash$ git status
  On branch master
  Your branch is up-to-date with 'origin/master'.
  nothing to commit, working directory clean

If you see any messages about uncommitted changes or any other indications that the latest version of your code has not been pushed to the GitLab repository, fix those problems and push any unsaved changes before going on.

Then repeat the above steps to verify that all is well.

2. Tag your repository and push the tag information to GitLab to indicate that the current commit is the version of hw0 that you are submitting for grading:

  bash% git tag hw0-final
  bash% git push --tags

Do not do this until after you have pushed all parts of your hw0 solution to GitLab.

3. Check that everything is properly stored and tagged in your repository. To be sure that you really have updated everything properly, create a brand new, empty directory that is nowhere near your regular working directory, clone the repository into the new location, and verify that everything works as expected. It is really, really, REALLY important that this not be nested anywhere inside your regular, working repository directory. Do this:

  bash% cd <somewhere-completely-different>
  bash% git clone git@gitlab.cs.washington.edu:cse333-18su-students/cse333-18su-xyzzy.git
  bash% cd cse333-18su-xyzzy
  bash% git checkout hw0-final
  bash% ls
  hw0

Use your own userid instead of xyzzy, of course. The commands after git clone change to the newly cloned directory, then cause git to switch to the tagged commit you created in step 2, above. We will do the same when we examine your files for grading.

At this point you should see your hw0 directory. cd into it, run make, run any tests you wish (something that will be crucial on future assignments). If there are any problems, immediately erase this newly cloned copy of your repository (rm -rf cse333-18su-xyzzy) go back to your regular working repository, and fix whatever is wrong. It may be as simple as running a missed git push --tags command if the tag was not found in the repository. If it requires more substantive changes, you may need to do a little voodoo to get rid of the original hw0-final tag from your repository and re-tag after making your repairs. To eliminate the hw0-final tag, do this (this should not normally be necessary):

  bash% git tag -d hw0-final
  bash% git push origin :refs/tags/hw0-final

Then make and commit and push your repairs, and only after all the changes are pushed, repeat the tag and tag push commands from step 2. And then repeat this verification step to be sure that the updated version is actually correct.

Note: if you discover that repairs are needed when you check your work, it is crucial that you delete the newly cloned copy and make the repairs back your regular working repository. If you modify files in the cloned copy you may wind up pushing changes to GitLab that will leave your repository in a strange state, and files may appear to mysteriously vanish. Please follow the instructions precisely.

Grading

For hw0, we'll give you 3 points if you learn the magic code and correctly submit your work.