CS-200 Project Management

(How to Prepare and Submit Assignments)

• Introduction
• Project Directories
• Project Files
  • Source Files
  • Documentation Files
  • Project Management Files
• Building an Application
• Submitting a Project
  • Clean the Project Directory
  • tar the Project Directory
  • Attach the tar File to a Mail Message

Introduction

Project Directories

There is a pragmatic reason for creating a separate directory for each assignment, too. You will be submitting your assignments to your instructor by e-mail. In this page you will learn how to bundle up all the files in a subtree into a single bundle (a tar file) that you will e-mail to us for grading. For this course, the "subtree" will typically consist of just the files in a single directory, but the same mechanism will work when you use a project management tool such as RCS to keep track of different versions of the files in a project. (RCS is a Unix tool that manages a database of all the versions of all the files in a project. The RCS database for a project is kept in its own subdirectory within the project's project directory.)

Project Files

Source Files

A project will contain some mix of the following source files:

• A separate header file for each class declaration in the project. The class declaration may include "simple" class member function definitions.
• A header file containing prototypes for any functions that you define which are neither members nor friends of classes.
• File(s) containing C++ member function definitions.
• A file containing the function definition for main(), which we will generally refer to as the "driver program" in this course.

Documentation Files

1. System Administration Documentation

   This type of documentation tells the person who is going to build and install the application how to do that. For a complex project, this documentation normally takes the form of a text file named "README" that provides the necessary information, and is left in the project directory. For this course, you can omit this documentation unless there is something unusual that your instructor should know in order to build and test your program. If you do want to tell us something about your project, do not put it in the e-mail message; put it in a README file in the project directory. Your e-mail is not always available when the actual grading of an assignment takes place.

2. User Documentation

   This is the information that tells a user what the program does and how to use it. It does not tell the user how the program works internally. You should assume that the user knows how type a command to get the program started, so what you need to provide here is information about command line options or environment variables that affect the behavior of the program and which the user should be told about.

   If your program has a Graphical User Interface, you would provide at least some of the information about how to use the program when the user selects the "Help" button.

   For traditional command-line applications, however, the standard format for this documentation is the Unix man page, with which you should already be somewhat familiar. Look at the man pages for some standard Unix commands to see what format this file should follow. The conventional name of a man page for a command is the name of the command with a suffix of ".1" because commands are documented in "Section 1" of the Unix manual. For example, if the executable file is named "mycmd," the man page would be named "mycmd.1."

   Unless your instructor says otherwise, you must provide a man page for each program you submit this term, but for this course it will typically be just plain text file containing a sentence or two, like the SYNOPSIS section of a real man page.

3. Programmer Documentation

   The third person who needs information about your program is the next programmer who works on it. Outside of academia, most programming consists of fixing bugs or adding features to existing code. The comments you put in your source code files should be written to help other programmers navigate through your code easily in order to find bugs or to determine where to add new features. Thus, it is important to pay attention to how the code is laid out on the screen (indentation) and to use meaningful variable names, as well as to write comments that are concise yet clear.

   Programmer documentation should be concise so the person who reads it doesn't have to spend too much time to find what he or she is looking for.

   Even though your code will actually be read only by yourself and the person who grades it, write the comments as if they would be read only by another programmer who needs to modify it. How well you follow this rule will be one of the factors that determines your grade!

   What I've just said about Programmer Documentation is true for all programming languages, but object oriented languages such as C++ make us distinguish between two different types of programmers: programmers who define classes and programmers who use classes. A major value of using an object oriented language is that it promotes code reuse: one person develops a class type and makes it available somehow to other programmers. Other programmers then either reuse the class directly in their application programs or extend the original class definition in some way(s) to tailor it to a particular application. Again, working as a student makes this distinction difficult because you have to play both roles in order to do a complete assignment. Nonetheless, the comments in your code should be written with the type of your real-world audience in mind: When documenting class definitions the comments should focus on making it clear how to use the class and any special provisions you made for extending the definition. When documenting your driver program (the one that tests your class definitions) you should make the structure of the program clear so that, for example, someone would be able to change the user interface or the nature of the tests the program performs.

Project Management Files

Once your programs are built from two or more source files, you are to manage the project by copying the standard Makefile for this course into the project directory and editing it according to the comments given in the Makefile. You can copy the standard Makefile from ~vickery/CS-200/Makefile.

In the Makefile you will find a line that says:

    OBJS = main.o myClass.o

This says that there are two object modules needed to build the application, main.o and myClass.o. You have to edit this line to substitute a list of all the object modules the have to be linked to build the program you are creating. (One for each of your .cc files.)

If you don't want the executable file to be named main, edit the line of Makefile that looks like this:

    main: $(OBJS)

Note: Do not name your executable file test. Not only is it not a descriptive name, but it is also the name of a Unix command (/usr/bin/test; look it up with the man command), and the Unix command will be executed instead of your own program whenever you enter a "test" command!

If you would like to experiment with an advanced project management tool that allows you to keep version numbers for your files and add revision history comments to your code, RCS is available on the system. Its use is beyond the scope of this course, though. There are man pages on line telling you how to use RCS.

Building an Application

    $ g++ -g -Wall main.cc -o main

The -Wall option tells the compiler to print warning messages if your program contains anything that does not conform to the current standard for C++, even if the problem might not cause a run-time error. It is a requirement for this course that you always use this option and that all your code compiles with not warning or error messages from the compiler (or any other processing program invoked by the g++ compiler driver). The -o option is followed by the name of the executable file you want to generate. If you omit it, your executable file will be named a.out. Remember, the man page you write for the program must have the same name as the executable file with an extension of .1.

If the program is to be built from more than one .cc file, it can be built by listing all of the source files on the g++ command line, and the compiler driver will preprocess, compile (and assemble) each one into a separate object module, and then link all the object modules together with ld. For example, if you have two files, named main.cc and sub.cc, you could use this command:

    $ g++ -g -Wall main.cc sub.cc -o main

1. Copy the default Makefile to the project directory and edit it as described earlier in this page.
2. Use the command "gmake depend" to build the header file dependency list in your project's Makefile. You need to issue this command any time you change the #include statements in any of the source files for the project.
3. Use the command "gmake" to build the project. Edit source files and repeat this command as necessary.
4. Test the program.

Submitting a Project

Clean the Project Directory

• No executable files. We will re-build your executable program files as part of the process of grading your assignment, so don't send us any executable files. They won't fit in our mailbox anyway.
• No test programs you wrote while developing the project.
• No debugging output files.
• No test data files unless they are actually part of the project.
• No "core" files. (A core file is a file named core that is created automatically if a program you are running "bombs". I suggest that you copy the file ~vickery/.logout into your home directory; it will delete all core files, as well as all files named "temp," "test," and "a.out" from each of your directories and subdirectories every time you log out, thereby saving file space for you.)
• No "tar" files. As you will see below, you are going to create something called a tar file that combines all the files (and subdirectories) for your project into a single file that you will mail to your instructor. Until you get the hang of it, it's easy to create a tar file inside the project directory, in which case you will end up with a tar file inside a tar file, and your mail message will be too big.

tar the Project Directory

1. Use the cd command to change your current working directory to the directory immediately above the project directory. (If you are in the project directory, the command would be "cd ..".)
2. Pretend the name of the project directory is project_directory. You would create a tar file named "abcqc.tar" by using the command:

       $ tar cvf abcqc.tar project_directory
   

   The "cvf" part of the command are the flags to (C)reate a tar file, showing a (V)erbose list of all the files and directories as the archive is built, and to name the output (F)ile "abcqc.tar." It is conventional to give tar files names that end in ".tar," and you should use your own account name as the base part of the filename.

3. If you want to, you can be sure you built the tar file correctly like this: Make a new directory somewhere outside of the project directory, change to it, copy the tar file to it, and give the command "tar xvf abcqc.tar". This should create a copy of your original project directory under the new directory. (This command uses "xvf" instead of "cvf" because 'x' causes tar to e(X)tract files from a tar file.) Use "ls -l" to check the copy, and then use rm and rmdir to delete the directories and files you don't need.

Attach the tar File to a Mail Message

Make sure the Subject: line tells which assignment you are submitting. You can put any text you want to in the message body, just like a regular mail message, but that text will not stay with the tar file as the assignment is graded. If there is something you think we need to read when grading your assignment, leave a README file in the project directory, and we will look at it.

Attach the tar file to the message with the ^J command while the cursor is in the header part of the message. When pine asks you for an "Attachment comment" you can type something similar to what you used in the Subject: line. Now you can use ^X to send the e-mail message in the usual way. You should try sending yourself an assignment to be sure it works before you really submit one to your instructor.

Note: Do not use the ^R command to read the tar file into the body of an e-mail message. tar files contain non-ASCII information that will corrupt the entire message if it is put in the body of your e-mail. One of the reasons you are using pine instead of some other mail program is that pine knows how to handle binary attachments. You have to send the tar file as an attachment using the ^J command, which works only when the cursor is in the header part of the message.

• Using Your Unix Account - Contents
• CS-200 Home Page