CS 270 Programming Assignment #0 (PA0)

Due Tuesday, September 2nd (by 11:59pm)

Introduction:

Programming assignments and the associated homework questions are to be done individually. The homework questions listed in this assignment description should be answered in the README file.

The purpose of this assignment is to introduce you to the C programming language, using make and a Makefile to compile your C source files, the GNU debugger gdb, and the checkin facility to turn in your programs. This assignment is not worth very much of your grade so make all the mistakes now :-). The C source files and a Makefile will be provided. Please DO NOT CHANGE the Makefile rules unless instructed to do so.

The Assignment

Log in using your computer science linux account and make a directory for all your CS270 assignments and within that a directory for PA0.
(Do the following at the prompt)

Type cd <press enter> to ensure you are in your home directory.

Type mkdir CS270 <press enter>

Type mkdir CS270/PA0 <press enter>

Type ls <press enter> to list out the files and directories in the current directory.
Here is the actual output :
```
    % mkdir CS270
    % mkdir CS270/PA0
    % ls
    CS270
    % cd CS270
    % ls
    PA0
    %
```

Create a README file within the PA0 directory and put your full name and username in the README file. It is easier to see that the next step has worked if you have at least one file in the PA0 directory.

At this point, you must set up a subversion repository for PA0. See SVN Notes for directions for setting up a subversion repository and working directory.

cd to subversion working directory PA0 (cd PA0).

Type the C source files from the handout you got in class into the files pa0.h, main.c, printHello.c, printBirthDateInfo.c, and sum3.c, respectively. You can use your favorite editor (vi/vim, emacs, pico, etc.) to type the files and save them in the PA0 directory. Type in the comments as well as the code so as to practice the coding style that will be expected in this course. Use your real login, name, etc. in place of the bogus student info.

Make sure to do an (svn add) for each file when it is first created, and do an (svn commit) anytime files are modified to frequently save revisions of the whole project.

There is a Makefile template for PA0 in the public directory (~cs270/public). Copy the PA0 Makefile into your PA0 directory. To accomplish this do the following at the command prompt, pressing Enter after each line:
```
    % cd ~CS270/PA0
    (Just to make sure you are in the PA0 directory.)
    % cp ~cs270/public/Makefile-PA0 Makefile
    (Note you are naming the copy in your PA0 directory Makefile without
the -PA0 suffix.)
```
Make sure to do an (svn add Makefile) and then do an (svn commit) to save a revision of the PA0 project.

Now you have the source files (which you created) and the Makefile in your PA0 directory. You need to run "make" to compile these files. Simply type make at the prompt. This will create the executable necessary to run the program -- by default, the target executable will be named a.out. Make will abort if any errors are found in the program code by the compiler.

After compiling using make just type ./a.out at the prompt to execute your code. You should see
```
    Hello, my name is: Joe Jane Student
    My birth date is: December 17, 1978
    The sum of 1, 2, and 3 = 6
```
printed out on your screen (it should have your own personal info).
Once you have checked, compiled, executed your code, and finished your README file (see below), and you are ready to turn it in, you MUST do make clean in order to remove all the object files, core dumps, and executables.

README and Homework Questions

Along with your source code, you will be turning in a README (use all caps) file with every assignment. For this assignment the README file should contain your name and userid and answers to the debugger questions.
Follow the instructions below and answer the questions in your README file.

To start the gnu debugger, at the prompt type: 
        gdb <executable-name>
In our case it will be 
        gdb a.out
        
Once the debugger is loaded, type the following:  
	break main
	run

1) What lines do you see printed to the screen?



Type print name.

2) What is the value of name?

3) What happens if you type step at this point? Why? (Hint: Do
another print name).



Type list. This should show you about 10 lines from your main
program.
(you can type list at any point during the debugging process
and it will show you the code that is around the line you are executing)

Type step until you see the following line:
		printHello( name );

4) At this point if you type step again, what happens?



type step until you see the following line:
        printBirthDateInfo( &bDayInfo );
        
5) Now what happens when you type next?  Look up some gdb
documentation to help explain the difference between step and
next.


Another way to set a breakpoint is to specify the file and line number
for the break point.  Determine the line number for "return a+b+c" in
sum3.c and then type break sum3.c:28, where 28 is replaced with
your line number for that 
line of code.  

6) What happens after you type cont to continue execution?  Why?

7) What happens after you type where?  Show what is printed and
explain what the printed information is telling you.

For more information about GDB see the online docs or type help or help <command> while running gdb. Of course there is always google for even more information (gdb tutorial).

Submitting your Assignment

Make sure you typed in all the code and comments and that your project compiles with no warnings and runs. The provided code has comments that satisfy the coding requirements for this course (see http://www.cs.colostate.edu/~cs270/Programs/code-requirements.html). Make sure the code you enter also satisfies the requirements.
Put all of the required information and answer the associated homework questions in the README file.

The subversion.txt file should include output from the following commands:

    % svn log -r HEAD:1
    % svn info
    % svnlook tree REPOSITORY_PATH  // svnlook must be issued on
the machine where the repository is stored

Do a "make clean" before creating the tar ball for the assignment.
Include all the source files, the README file, the Makefile, and a subversion.txt file in a tar file.
```
  % cd ~/CS270
  % tar cvf pa0_username.tar PA0
```
Submit assignment using checkin utility
```
~cs270/bin/checkin PA0 pa0_username.tar
```
Sanity Check (procedure we will use to grade your assignment):
```
    % tar xf pa0_username.tar
    % cd PA0
    % make      
    % ./a.out  
  
```
We will be reading through the code comments for the code style requirements portion of the grade.

If there is anything in these procedures which needs clarifying, please feel free to ask any TA, the instructor, or send email to the class mailing list.

Late Policy

Late assignments will be accepted up to 24 hours past the due date and time for a deduction of 20% and will not accepted past this period. One minute late is still late.

Make

Make is a UNIX tool used to compile a group of source files in a particular way based on compilation rules written down in a file named Makefile. Using make makes it much easier to compile large projects. We can look at the sample Makefile provided as part of programming assignment zero to review the techniques of writing a Makefile. The Makefile can be found in the directory "~cs270/public/" from your computer science account.

The "#" symbol is used for commenting. The Makefile starts by defining some global environment variables to denote the C source files, C_SRCS. The object files (.o files) produced by compiling the sources are referred to by the environment variable OBJS. The files defining these variables will change from one assignment to another and it is your responsibility to change it accordingly. This is followed by a set of rules to compile the sources and the target executable file. These rules are standard and need not be modified for the rest of your assignments. If there are any changes we will modify the template and notify you, so you can copy that into your directories.

The rules specify paths for the various compilation tools. Using variables like GCC to define these simplifies the task of writing the rules. Anytime the paths change, we just need to change it at one place. Following this, we have variables to define the various compilation flags. These flags each have a purpose as given below:

-c: This tells the compiler to stop the compilation once the .o files are generated and not go to the linking stage. This is needed because linking cannot be done without having all the .o files first. Most programs are written as multiple source files which are dependent on one another. The -c flag compiles each of them separately into object files.

-g: this option is used to generate debugging information which can be later used by the debugger (gdb).

-std=c99: This tells gcc to make sure the code satisfies the c99 standard.

-Wall: This tells gcc to generate all warnings.

The standard rules are defined to compile the .c files into object files. You can now see the usefulness of using environment variables. Lastly, we define the target executable, which can be obtained by using the linker to link all the object files. The default name for the target executable is a.out. Note that the -c flag is not used for linking (the LD_FLAGS just define -g). Another target called "clean" is used to clean the directory of all garbage which are not needed for turning in (object files, executables, core files, etc.). You MUST do a make clean before turning in your code. Again, please do not edit the Makefiles rules unless instructed to do so.

mstrout@cs.colostate.edu .... August 31, 2008