$Id: cvsguidelines.txt,v 1.2 2004/12/10 15:15:05 paul Exp $ Guidelines for using CVS in the tina project -------------------------------------------- Tony Lacey [a.lacey@man.ac.uk] Updated paul.bromiley@man.ac.uk 15/11/2004 This document is a collection of material to advise and assist developers in using the tina cvs repository correctly. It aims to be a complete guide to interacting with the repository under all circumstances and to provide sufficient detail that even the novice cvs user is able to undertake virtually any task necessary (although they probably won't be allowed!). All the examples provided are given as command line cvs commands. If you use some form of gui based client you will need to perform equivalent operations. If you are unfamiliar with cvs take a look at some of the resources suggested in appendix A. of this document 1. System summary ----------------- CVS for tina is hosted by us on a dedicated linux server at ISBE, University of Manchester. CVS Server Hostname: cvs.tina-vision.net CVS Root : /home/tina/cvs Username/Password : anonymous checkout (a.lacey will advise individually) Modules: tina-libs : main tina library system tina-tools : traditional graphical tools and application libraries 2. Basic client operation (everybody) ------------------------------------- This section is aimed at new users (who don't yet have repository write access) and users who wish only to acquire the latest tina software using cvs but are not developing within the tina modules themselves (developing other code which links to the libraries does not count as being a tina developer). It also provides a basic introduction to acquiring and updating tina software for anyone new to cvs. i. Checkout Before you can work with the software under cvs control you need to "checkout" a working copy from the repository onto your local machine. This will provide you with all the code available as part of the module you requested at whatever revision you request. By default you will receive the latest revision of the software (probably what you want anyway). The first time you want access to the server you will need to login. Unless you have been given a specific username and password you should login using the username anonymous. This is done as follows; cvs -d:pserver:anonymous@cvs.tina-vision.net:/home/tina/cvs login when prompted for a password simply hit return. Unless you explicitly logout from the system using the 'logout' command you will not have to login again. Next you can get the latest version of the module you require. First enter the directory you want to create the source tree in and run the following command; cvs -d:pserver:anonymous@cvs.tina-vision.net:/home/tina/cvs checkout tina-libs This will download the latest revision of the module tina-libs and create a top level directory called tina-libs/ The only addition to the source directory structure is a directory called CVS in each directory of the source tree. You can safely ignore these. Hey presto! You now have the complete tina-libs source tree and can begin building the libraries by following the instructions in the README file. You will probably also want to do something similar for the tina-tools module; cvs -d:pserver:anonymous@cvs.tina-vision.net:/home/tina/cvs checkout tina-tools Once you have a checkout version of the software you don't need to checkout again (unless you delete all the files). To get the latest revisions you should follow the details in updating, next. ii. Updating As the software is developed by others they will commit changes to the repository. These changes will introduce differences between the latest repository revision and the revision checkout by you in your working copy. If you subscribe to the developer mailing list you will receive notifications of these commits as they are made. You can check at anytime to see what files have changed since you last updated (or checked out) using the update command from within the top level directory (e.g. tina-libs); cvs -d:pserver:anonymous@cvs.tina-vision.net:/home/tina/cvs -n -q update This will list files with newer revision numbers (i.e. are newer) than those in your working copy. If you want to investigate any of the differences further you can run the 'diff' command on any file. Simply move into the directory which contains the file you are interested in and run; cvs -d: diff For instance if you wanted to see what differences there are in the file sysPro.h in tina-libs/tina/sys are you would do; cd tina-libs/tina/sys cvs -d:pserver:anonymous@cvs.tina-vision.net:/home/tina/cvs diff and a list of the differences (as found by diff) would be shown. In most cases if you are not modifying the tina files yourself you will not be interested in checking differences and can safely update your copy with the latest revisions whenever you become aware of additions you want (you won't do any harm if you update regularly). To update run the following from within the modules top level directory; cvs -d:pserver:anonymous@cvs.tina-vision.net:/home/tina/cvs update -d This will automatically bring your working copy up to date with the latest revision in the repository and you will have access to all the latest additions! Follow the build instructions for cvs builds in the README file to rebuild the libraries. iii. Shortcuts You can greatly reduce the size of the cvs commands by setting the CVSROOT environment variable (or equivalent default repository location in your cvs software). For command line UNIX using sh you would do; export CVSROOT="pserver:anonymous@cvs.tina-vision.net:/home/tina/cvs" From then on commands can be executed without the need to specify the repository. So for instance the update command would be executed as simply; cvs update -d Much more pleasant! 3. Advanced client operation (developers) ----------------------------------------- This section assumes you are developing code within one of the repository modules. i. Developing code and submitting changes 1) The first step is to checkout a copy of the module(s) you want to work with as described above. Remember "checkout" is something you do quite rarely unless you want loose your local copy and start again. 2) Do your work. Edit existing files as you please, create new ones, build and test your code. You don't need any connection to the repository while you are working. 3) While you are working if you receive notifications of other peoples commit's, you can as you wish perform an update on your module (tina-libs, tina-tools, etc). Changes from the commit will be merged with any changes you have made. If changes have been made to the same or adjacent lines then the file will be annotated with ">>>>>" lines and you will need to resolve these manually. At the time of the update cvs will inform you that such files conflicts you need to resolve. 4) Once you have resolved the issues and your code builds and tests correctly you are ready to submit your code (if you want). The process of submitting updates depends on your status. If you have repository write access you can go on to section 6. If not you need to perform the step 5 only. 5) So you don't have repository write access. Ok well you can still contribute your code by simply generating a compressed tarball of your module directory area (without the object and other built files) and submitting it to myself at the email address given at the top of this document. On most UNIX like systems this can be done with the commands below from the top level module directory; make clean cd .. tar -xvf -.tar gzip -.tar where is the name of the module directory you are submitting and is, errrmm, your email address. Please document the changes you have made in the email in the same manner as a changelog entry (see the ChangeLog file for precise details and examples). If you have submitted changes to us before and want feel you have earnt write access then contact us. You can carry on with your daily routine and ignore the rest of the points 6) So you have write access to the repository. Don't abuse them. Make sure you have read all of this document and are happy using cvs. 7) If you have added any new files to your module area you need to inform the respository that they exist with a 'cvs add' command. Similarly if you have removed any files you should also inform the repository with a 'cvs remove' command. You *do* need to be online to do these. 8) Identify the commit ID from the ChangeLog file as the next available (from the top). Modify the ChangeLog file with the details of your modifications (as described at the top of the ChangeLog file). 9) *IMPORTANT* immediately before you commit your changes perform an update again in case a commit has happened (or is underway) since you last updated (don't think about it just DO IT). Resolve any conflicts which arise and build and test your code. If this takes some time you must do an update again until no changes/conflicts are reported. 10) Commit your changes using the 'cvs commit' command. When prompted for the CVS log entry simply use "ID:xxx" where xxx is the build number used in the ChangeLog file. 11) Send a copy of your ChangeLog entry to the developer mailing list as outlined in the ChangeLog file. 12) Continue working. A. Other resources ------------------ . http://developer.tina-vision.net/ - tina developer website . developer-list@tina-vision.net - tina developer mailing list . http://www.cvshome.org/docs/ - for documentation on CVS . http://faq.cvshome.org/fom-serve/cache/1.html - useful FAQ's B. FAQs ------- If you have any questions regarding the use of the tina cvs respository then send them to the email address at the top of this document.