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.)
.cc") and header files (which have names ending in "
.h" and which are named in
#includestatements in one or more
.ccfiles). 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:
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.
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 "
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 "
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.
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.
Once your programs are built from two or more source files, you are to
manage the project by copying the standard
this course into the project directory and editing it according to the
comments given in the
Makefile. You can copy the standard
Makefile you will find a line that says:
OBJS = main.o myClass.oIt'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
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
If you don't want the executable file to be named
edit the line of
Makefile that looks like this:
main: $(OBJS)and change the word
mainto 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.
main.cc, the command to build an executable program named
mainfrom it is:
$ g++ -g -Wall main.cc -o mainThe
-goption 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.
-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).
-o option is followed by the name of the executable file
you want to generate. If you omit it, your executable file will be
a.out. Remember, the man page you write for
the program must have the same name as the executable file with an
If the program is to be built from more than one
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
you could use this command:
$ g++ -g -Wall main.cc sub.cc -o mainHowever, 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:
Makefileto the project directory and edit it as described earlier in this page.
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
#includestatements in any of the source files for the project.
gmake" to build the project. Edit source files and repeat this command as necessary.
corethat is created automatically if a program you are running "bombs". I suggest that you copy the file
~vickery/.logoutinto 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.)
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". If your account name is "abcqc," these would be the steps to build the file
project_directory. You would create a tar file named "abcqc.tar" by using the command:
$ tar cvf abcqc.tar project_directoryThe "
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.
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.
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
README file in the project directory, and we will look at
Attach the tar file to the message with the
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
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
which works only when the cursor is in the header part of the