How to use the CVS server

To manage my sources for the robot software I installed a CVS server. CVS is a version control system to record the history of source files. The CVS server stores all files in a centralized "repository". To edit a file, it must be "checked out" to copy it to your local system. Then you can modify and test it in anyway you want. When you're satisfied with the changes, you "commit" it (copy it back) to the repository. If somebody else also changed the same file, the CVS server will try to merge the changes. If that fails, it will report so and give you a chance to merge the two versions by hand. The CVS server remembers all committed versions of a file and it is easy to go back to any previous version if you want to start over again. Files in the repository are bundled in sets called modules. (Don't confuse this with the modules from Pieters paper!) When a module is ready for general use (i.e. the set is stable), you can "tag" them to give the current versions of the files in the module a symbolic name.

An important feature of CVS is the abiltiy to work on a module with a team. The CVS server prevents team members overwriting each others versions. Team members can independently edit their local copies of a module. When a team member commits a file to the CVS server, it tries to merge the local changes with the current file in the repository. This current file may be different from the checked-out version, because other team members commited changes already. If the CVS server can't merge the local and repository versions, it will report an error and not commit the file. So changes will never get lost. Consult the CVS info files (info cvs) for more information about CVS and its usage.

Some remarks

The repository for the RoboSoccer project is control-lab.et.tudelft.nl:/user0/home/will_cvs. The basic module, which includes all sub-modules is "apps". The "apps" module itself consists of just a Makefile. Use this file to (re)build the object files and executables in all sub-modules after retreiving the latest version from the repository.

Every sub-module should have its own Makefile. The Makefile file should have an entry for "wrapper" to build object files and libraries, an entry "module" for executables, an entry for "install" for commands to execute as the root user, and an entry "clean" to remove all generated files (object files, executables, bitmap files etc.) Makefiles for sub-modules should use relative paths to other modules, i.e. "../msg/Msg.o" in stead of "/home/will_g/apps/msg/Msg.o".

A module and a directory are two different things. A module is a list of files in the repository. Although checking out a module will copy all files into one directory-tree, not all files in a directory-tree are in a module. Files must explicitly be added to a module. Do not add binary files, like object files or executables, to a module. These files should be generated by the Makefile. When you add a subdirectory to a module, it will become a module in its own.

Important CVS commands

cvs -d :pserver:jaap@control-lab.et.tudelft.nl:/user0/home/will_cvs login: This gives jaap access to the CVS repository in /user0/home/will_cvs (if jaap knows his password). After a succesful login jaap may retreive files from the repository.
cvs -d :pserver:jaap@control-lab.et.tudelft.nl:/user0/home/will_cvs checkout msg: This creates jaap's private copy of the source files in the msg module in the repository. It will create a subdirectory msg in the current working directory. Jaap should chdir to this subdirectory before using any of the remaining cvs commands.
cvs update -d: Updates the local copies of the source files from changes that others have checked in to the repository. It will also copy new files and directories from the repository.
cvs add new_file.c: Adds a new file to the module in the current working directory. This file will be added to the repository when jaap runs cvs commit to check in his changes.
cvs remove old_file.c: Erases a file from the module in the current working directory. The file must be removed from the directory before it can be removed from the module. The file will be removed from the repository when jaap runs cvs commit.
cvs commit: Publishes changes to the module in the current working directory to the repository. Any files that have been changed or added to the module will be copied to the server. Files in the directory but not in the module will be ignored.
cvs -d :pserver:jaap@control-lab.et.tudelft.nl:/user0/home/will_cvs release -d msg: Removes the subdirectory msg from the current working directory. Any changes in the files will be forgotten. The repository will not be changed.
cvs tag msg-1_3: Gives a symbolic name msg-1_3 to the set of files in the current working directory, . This set can be retreived from the repository with cvs -r msg-1_3 checkout msg. Changes made to the files after tagging them will not be included in the set.
cvs logout: This denies jaap access to the repository. He can no longer retreive files or commit changes. Nothing will be changed, neither locally nor in the repository.