CPS 124/296.3 : Fall 2001

CPS 124/296.3
Fall 2001

Getting Started

This document is a brief introduction to managing OpenGL projects in Unix. It assumes you are familiar with using the Unix operating system, writing and compiling C++ programs, and using a modern window manager. If not, consult this tutorial. You should spend as much time as you need experimenting with the concepts introduced here until you become comfortable with the tools. Feel free to post concerns and additions to the course newsgroup.

For each course, we suggest that you make a separate directory to contain the projects, examples, and test programs you write without getting cluttered with files from other courses. Thus your first act should be to create a directory called cps124 within your home directory.

Starting a Project

For each project, we suggest you create a separate directory within your cps124 directory to contain the files for your program. For this example project, create a directory called starting within your cps124 directory. As with many of the projects for this course, you will start by copying some sample code created by the course staff. Depending on which system you are using, you can find the code for this project in the following places:

on acpub: ~rcduvall/cps124/src/starting/
on cps: /usr/project/cwd/cps124/current/code/starting
on www: http://www.cs.duke.edu/courses/cps124/current/code/starting

With each project, we will distribute a Makefile that you can use to compile your program on any Unix system available. To configure the Makefile to work for your particular project and system, you will need to modify the variables at the top of the file:

EXEC 	  name of executable file
SRC_FILES space separated list of source files that must be linked to create executable
ARCH 	  system on which you are compiling (one of CPS, ACPUB, LINUX, CYGWIN)

After copying the necessary example files into your project directory and modifying the Makefile for your system, you should be ready to compile the demo project by simply typing make. Depending on your system, you may see some warnings within the OpenGL header files when you compile. You can run the resulting OpenGL program only while you are sitting at the console of the machine you compiled it on.

Getting Started with SourceForge

In this course, we will be using SourceForge to help you manage your projects. It contains a number of useful tools including: concurrent version control (CVS), bug tracking, task lists, discussion lists, and project submission.

CVS is a program that manages your source code by allowing you to "back out" of changes that you have made, or have several versions of your program available quickly and easily. CVS works by storing only the differences between versions of your program in a separate directory, called a repository. This repository is being kept by SourceForge.

Getting a SourceForge account

To start using SourceForge, you will need to create an account with the system, following these steps:

Go to our SourceForge homepage: http://sourceforge.cs.duke.edu/.
Click on the 'New User' link at the left side of the window.
Follow the directions to create an account.
When you submit the form, you should receive an e-mail giving you directions to register your new account. To register your new account, you will need to fill in another web form.

Once you have completed the registration process, you can return to the SourceForge homepage and login into the system by clicking on the 'Login' link at the left side of the window. This will automatically take you to your personal homepage on SourceForge. This is where you will manage all of your projects for the course.

Creating a SourceForge project

From your personal SourceForge homepage, you can click the 'Register New Project' link at the left side of the window. Again you will be directed to follow a series of instructions through a number of pages. In general, you should pick meaningful, unique names for your project --- for this project, only one person in the class will get the generic name starting. If you are feeling uncreative, you can use starting, where XYZ are your initials.

Once your project is created, go back to your start page by clicking the ever-present link 'My Personal Page' from the left side of the window. A new link to your project should now be available on your personal homepage. Go to your project page by clicking on the name of your project at the right side of the window.

As the person that registered the project, you are labeled as the Project Administrator by default (later, you can add others to the project and allow them to be administrators as well). As Project Administrator, you have access to modify anything about the project. To do this, click on 'Project Admin' link at the left side of the window.

The project administration page lets you set the project's home page and public description by clicking the 'Edit Public Info' link. It also lets you categorize your project by clicking 'Edit Trove Categorization,' and lets you add people to your project by typing their username in the 'Unix Name' blank and clicking 'Add User'. You should set the project home page, description, and categories for every project you create. The category should be the current project under the classes category.

From the 'Project Admin' screen you can also click on 'Edit Member Permissions' to edit which members of the group are administrators for certain duties: bug tracking, task management, forum moderation, documentation management, or general project management. You may assign duties and permissions however you see fit. Note, only bug administrators can assign bugs.

Starting a CVS tree

The last thing you need to do to set up your project correctly is to go back to your acpub account and set up CVS so that you (and your group members) can work on your project from your acpub account, but allow SourceForge to maintain control over your changes. Note, you can follow these instructions for any system you want to work on: acpub, CPS, your own home Linux system, etc.

First, append the following two lines to your .cshrc file in your home directory (or .environment if you have run the CPS setup command for this or a previous course), where you means the name of the SourceForge account you just created and project means the name of the project you created with that account.
```
       setenv CVS_RSH ssh
       setenv CVSROOT you@sourceforge.cs.duke.edu:/cvsroot/project
```
Type cd ~/cps124/starting to change into the directory that contains your code. In general, this directory does not need to contain code to start.
To import your project into CVS so that you can start keeping track of your changes, type the following command, where project can be whatever name you want but should probably be the same as your project above, vendor can be whatever you want (make up a company name, use your own name, use your dog's name, use foo), and release-name describes the current version of the code ("first" or "start" is good).
```
       cvs import project vendor release-name
```
Now cd up out of that directory and download a fresh copy of the code (or lack thereof) that you just imported, complete with revision history. From the project's parent directory type the following CVS command where project must be the same name you used when importing, above.
```
       cvs checkout project
```

At this point, you have a directory named project containing any code you imported, plus a CVS directory with some meta-information about your revisions. You can edit your code within that project directory and keep track of your edits (and those of your group members) by using the SourceForge system.

Projects: Editing, Updating, and Checking in

For group projects, each group member should have her own checked-out copy of the source tree and should do her editing independently within that tree. Coordinate your efforts using SourceForge, but edit separate copies of the source code -- that is the point of CVS!

However, when working on a group project, it is very important to make sure that your changes to the code do not break the program as a whole for your group. CVS works by giving each project member their own copy of the source code to work on. As you make changes you may need to reconcile those made by your group members --- it is your job to try to make sure you do that before submitting your own changes.

Thus, each time you make changes to the code, it is necessary to follow a process of edit, compile, test, update, compile, test, checkin.

Committing your updates to CVS

After you have edited, compiled, and tested your code within the project directory produced by the CVS checkout above, you will almost be ready to commit your changes to the group. Before you can do that though, you need to reconcile your edits with those of your other group members. Do this by updating your personal copy, then compiling and testing the new version before committing your changes to make sure your updates are still current.

	To get updates within your personal copy that other people have uploaded to the CVS tree, type cvs up
	To commit updates that you have made to your personal copy, type cvs commit When you type 'cvs commit' you will get an editor window in which you type a description of the changes you have made since you last committed.
	To add a new file to the CVS repository, create it first in your personal copy, then type cvs add filename This flags the file to be uploaded the next time you commit. It does not immediately upload the file.
	To remove a file from CVS, delete it in your personal copy tree, then type cvs remove filename This flags the file for deletion the next time you commit. It does not immediately remove the file. (Note, the file is actually moved to 'attic' in the repository, so it is still there if you need to see it later.)

WebCVS

When logged in to SourceForge you can easily see the changes your group has made to the project.

From your project's start page, you can click the CVS icon (the one with the arrow between the pyramid and box) near the upper-right corner of the screen. Alternatively, you can use the 'CVS Repository' link on the bottom of the left column.
Once on the CVS screen, click 'Browse CVS Repository.'
Then click on the directory corresponding to your project name.

Finally, you will see all of the files associated with the project. You can click on any one of them to download a current or previous version or to compare the differences between two versions.

Conflicts

If you and another developer work on the same file concurrently, your changes may conflict when the second person goes runs 'cvs up' or 'cvs commit.' Conflicts occur when concurrent changes happen in the same file within a few lines of each other. Good developer communication can help prevent conflicts, but you will probably get a few anyway.

When you get a conflict, the file with the conflict will have a section delimited by

<<<<<<
[your new code]
======
[other group member's conflicting code]
>>>>>>

You will need to figure out which section is the best choice or combine the two sections manually and delete the delimiters that would cause compiler errors.

Tracking Bugs

Any user can submit a bug report to any public project in SourceForge. You will be expected to submit bug reports for your own projects and you may feel free to submit constructive bug reports to other groups' projects as well. Bugs found in your submitted code may be penalized less if they are documented sufficiently in the SourceForge bug report page for the project.

To submit a bug to a project, find the project's central page either through your own start page or through the 'Software Map' link in the upper-left corner.

Click on the bug icon or the 'Bug Tracking' link.
Click 'Submit A Bug' near the top of the page.

Bugs assigned to you will show up on your personal start screen until you reassign or close them.

Submitting your Project

Every assignment must have a README file submitted with it (please use all capital letters). In your README file, include your name, your partner's names, the date, an estimate of how long you worked on the project, and a list of your project's extra features.

When your code is ready to submit, you should make a file release. Clean up your source directory by deleting all compiled (*.o, *.a, and binary) files by using the command 'make clean' and all backup (*~) files. Then change to the project's parent directory and type:

tar cvzf project.tgz project-directory

This will produce the file project.tgz, which contains all of the source code from that project directory in one bundle. You will then submit your code by releasing it to SourceForge using the following steps:

Upload your tar file by anonymous FTP by typing
```
       ftp sourceforge.cs.duke.edu
```
Fill in anonymous when it prompts for a user name and nothing when it prompts for the password. Once at the FTP prompt, type
```
       cd /incoming
       put project.tgz
       quit
```
Go back to the 'Project Admin' page for your project (only project admins can do this), and click on 'Release New File'. The tar file file you uploaded will appear in the selection box. Pick it and click 'Submit'. Choose a version number and description for your file and click 'Submit' again.
You can find your own (and other people's) released files by clicking on the 'Downloads' icon on a project's central page, or by clicking on 'New Releases' in the upper-left corner of any SourceForge page.

All released files are time stamped when they are submitted. We will use these time stamps to verify your program submission is on time.

Feedback?