CS-200 Project Management

(How to Prepare and Submit Assignments)


This page tells you how to manage project directories that you will use for the assignments in this course.

Project Directories

Each programming assignment you submit for this course, whether it is a set of homework exercises or a programming project, is to be developed in its own subdirectory, which is referred to as the project directory for the assignment. There are two basic reasons for this requirement. The first is that it encourages you to manage your part of the filesystem rather than clutter up your home directory with an odd collection of unrelated files. The second is that it establishes a precedent for project development in the real world, where you are likely to work on large projects, each of which consists of numerous source files. Keeping the files for each project in separate directories is the only way to keep the different projects you work on under control.

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

The files in a project directory will be some combination of source files, documentation files, and project management files.

Source Files

Some of the early exercises you do will be coded as single C++ files, but once you start defining new classes and functions, the files for each executable program will consist of source code files (which have names ending in ".cc") and header files (which have names ending in ".h" and which are named in #include statements in one or more .cc files). Both source code files and header files are called "source files" because they both contain C++ program text that you prepare using a text editor.

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

Documentation Files

There are three types of documentation for a project, each designed for a different audience:
  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

For simple programs with only one source file, there will be no 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
It's on line 38 of the file at the time this page is being written.

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)
and change the word main to whatever you want your executabel file to be. (Line 51 of Makefile.) Use a descriptive name for your executable program. However, it is part of the Unix tradition for programs to have terse names (to save typing), so that is all right to do.

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

Assuming you have a single source file named main.cc, the command to build an executable program named main from it is:
    $ g++ -g -Wall main.cc -o main
The -g option tells the compiler driver to preserve symbolic debugging information in the executable file, and must always be used when developing an application so that it can be debugged using an interactive symbolic debugger like gdb. The use of gdb is an advanced topic in this course.

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
However, it is more efficient to save all your object modules and to recompile only the ones that need to be recompiled because of changes you make to the corresponding source files. To do this, use the gmake utility:
  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

When you are ready to submit an assignment for grading, follow the sequence of steps listed here.

Clean the Project Directory

You are going to submit all the files from your project directory (and any subdirectories) for grading. Before you submit an assignment, make sure that the only files present in the project directory are actually part of the project. There must be: Use the "ls -la" command to see all the files in your project directory and use the "rm" command to delete the ones you are not going to submit. (Or use "mv" to move them into another directory if you want to save them.)

tar the Project Directory

Here is how you copy all of a directory tree into a single tar file. (The name tar stands for "(t)ape (ar)chive" because it was originally used to copy directory trees to magnetic tape for backup.) The name of the tar file you create is to be your qcunix1 account name, with an extension of ".tar". If your account name is "abcqc," these would be the steps to build the file abcqc.tar:
  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

To submit the project, send e-mail to your instructor's qcunix1 account. Dr. Vickery's account name is vickery, and Mr. Lusinyants' account name is rrlqc. (The middle character of Mr. Lusinyants' account is the first letter of his last name, not a numeral.)

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.

Christopher Vickery
Queens College of CUNY
Home Page