1. Chris Onions Getting started with CVS in ATLAS 11 Getting started with CVS in ATLAS Chris Onions (Tutorial based on that of Raúl Ramos Pollán CERN / IT Division)

2. Chris Onions Getting started with CVS in ATLAS 22 What is CVS? Version Control System. It’s a TOOL to maintain collections of (text) files. Helps in keeping track of the evolution of your projects. Helps in maintaining and coordinating the work on SOURCE files. It’s a statement of organisation.

3. Chris Onions Getting started with CVS in ATLAS 33 Basic Concepts The Repository: –A place where all files are centralised. –It’s populated with a hierarchy of files and directories. –You ONLY access the repository through CVS commands. –CVS gives developers a working copy. –CVS updates the repository with the changes made by developers

4. Chris Onions Getting started with CVS in ATLAS 44 ATLAS repository The ATLAS repository is on AFS in directory /afs/cern.ch/atlas/software/cvs The repository can also be accessed via the cvs server - see the URL home.cern.ch/~onions/cvs_server.html The repository can be browsed from URL atlasinfo.cern.ch/atlas-bin/cvsweb.pl

5. Chris Onions Getting started with CVS in ATLAS 55 Basic Concepts Files in the repository are organised in directories. Directories are organised in Packages Files have revisions. ATLAS only uses the modules feature of CVS in it’s most basic form (a directory is a module).

6. Chris Onions Getting started with CVS in ATLAS 66 Scenario 1 cd ~work cvs checkout -d dice offline/dice >> cvs checkout: Updating dice.. >> U dice/PACKAGE.. etc. cd dice... edit PACKAGE file.… cvs commit -m “Fixed first bug” >> Checking in PACKAGE; >> /afs/cern.ch/atlas/software/cvs/offline/dice/PACKAGE,v <-- PACKAGE >> new revision: 1.3; previous revision: 1.2 >> done Look at the file in your working directory cvs status -v PACKAGE Once committed, remove it from your directory cvs release -d PACKAGE

7. Chris Onions Getting started with CVS in ATLAS 77 cvs status cvs status -v PACKAGE File: PACKAGE Status: Up-to-date Working revision: 1.4 Thu Nov 12 09:53:15 1998 Repository revision: 1.4 /afs/cern.ch/atlas/software/cvs/offline/dice/PACKAGE,v Sticky Tag: offline-00-00-14 (revision: 1.4) Sticky Date: (none) Sticky Options: (none) pto

8. Chris Onions Getting started with CVS in ATLAS 88 cvs status contd. Existing Tags: offline-00-00-14 (revision: 1.4) dice-03-20-03 (revision: 1.4) offline-00-00-13 (revision: 1.2) offline-00-00-12 (revision: 1.2) dice-03-20-02 (revision: 1.2) offline-00-00-11 (revision: 1.2) offline-00-00-10 (revision: 1.2) dice-03-20-01 (revision: 1.2) offline-00-00-09 (revision: 1.1.1.1) offline-00-00-08 (revision: 1.1.1.1) offline-00-00-07 (revision: 1.1.1.1) etc.

9. Chris Onions Getting started with CVS in ATLAS 99 Multiple Developers CVS does not use file locking* Whenever it encounters conflicts it tries to solve them. If it can’t merge, it warns. A file has a status: –Up to date –Locally modified –Needing update –Needing merge * Temporary locking of directories

10. Chris Onions Getting started with CVS in ATLAS 1010 File status update and checkout print a line per file with a one character status of the file: U file brought up to date w.r.t. repository P“ “ “ “ “ “ A filewill be added on next commit R filewill be removed on next commit M filefile is modified in local directory C filea conflict detected during merge ? filein local directory, not in repository

11. Chris Onions Getting started with CVS in ATLAS 1111 Scenario 2: Merging DEVELOPER 1: cvs checkout -d arve offline/arve edits arve/examples/Snail/Snail.cxx file but doesn’t commit... DEVELOPER 2: cvs checkout -d arve offline/arve edits arve/examples/Snail/Snail.cxx file and commits DEVELOPER 1: cd arve cvs commit -m ‘comment’ >> cvs commit: Examining arve >> cvs commit: Examining arve/examples/Snail >> cvs commit: Up-to-date check failed for `arve/examples/Snail/Snail.cxx' >> cvs commit: Examining arve/examples/Clam >> cvs [commit aborted]: correct above errors first! cvs update arve/examples/Snail/Snail.cxx >> RCS file: >> //afs/cern.ch/atlas/software/cvs/offline/arve/examples/Snail/Snail.cxx,v >> retrieving revision 1.2 >> retrieving revision 1.3 >> Merging differences between 1.2 and 1.3 into main.c >> M arve/examples/Snail/Snail.cxx BOTH:cvs status -v arve

12. Chris Onions Getting started with CVS in ATLAS 1212 Scenario 2: Conflicts BOTH:.... if not up to date cd ~work cvs checkout -d arve offline/arve... edit same part of Snail.cxx... DEVELOPER 1: cvs update cvs commit -m “Commented out something” DEVELOPER 2: cvs update >> cvs update: Updating arve >> cvs update: Updating arve/examples/Snail >> RCS file: >> /afs/cern.ch/atlas/software/cvs/offline/arve/examples/Snail/Snail.cxx,v >> retrieving revision 1.2 >> retrieving revision 1.3 >> Merging differences between 1.2 and 1.3 into main.c >> rcsmerge: warning: conflicts during merge >> cvs update: conflicts found in arve/examples/Snail/Snail.cxx >> C arve/examples/Snail/Snail.cxx... edit Snail.cxx, ChangeLog,.... cvs update cvs commit -m ‘See ChangeLog’

13. Chris Onions Getting started with CVS in ATLAS 1313 Scenario 2: Independency DEVELOPER 1: cvs checkout -d arve offline/arve cd arve... work on arve/arve/DataControl.cxx.... cvs commit -m ‘See ChangeLog’ arve/DataControl.cxx DEVELOPER 2: cvs checkout -d arve offline/arve cd arve... work on arve/arve/TestBeam.cxx cvs commit -m ‘See ChangeLog’ arve/TestBeam.cxx CVS is recursive on the directory structure of the current directory THIS:cd arve cvs update arve/DataControl.cxx IS EQUIVALENT TO: cvs update arve/arve/DataControl.cxx

14. Chris Onions Getting started with CVS in ATLAS 1414 Adding and removing files You have to tell CVS what files you want it to take care of. cvs add aa.h >> cvs add: scheduling file `aa.h' for addition >> cvs add: use 'cvs commit' to add this file permanently cvs commit -m “Added some dummy file”... cvs remove aa.h >> cvs remove: scheduling `aa.h' for removal >> cvs remove: use 'cvs commit' to remove this file permanently cvs commit -m “Just removed the dummy file” >> cvs commit: Examining. >> cvs commit: Committing. >> Removing aa.h; >> /afs/cern.ch/atlas/software/cvs/offline/arve/aa.h,v <-- aa.h >> new revision: delete; previous revision: 1.1 >> done

15. Chris Onions Getting started with CVS in ATLAS 1515 Tagging The developer can give a symbolic name to file(s) with the rtag command to identify specific revisions The recommended way to tag your sources, after committing: cvs rtag mypackage-01-01-02 offline/mypackage

16. Chris Onions Getting started with CVS in ATLAS 1616 Tagging contd. The tag command tags the nearest repository versions to your working sources. cd working_directory/mypackage cvs tag mypackage-01-01-02 This should be used with caution!! Unpredictable results can occur in the case of sticky tags branches uncommitted changes

17. Chris Onions Getting started with CVS in ATLAS 1717 Software Releases A Release is made of revisions of files file1file2file3file4 1.1 1.2 1.3 1.1 1.2 1.3 1.1 1.2 1.3 1.1 1.2 1.4 1.5 offline-00-00-14

18. Chris Onions Getting started with CVS in ATLAS 1818 Comparing revisions of a file To see what has changed in your working directory cvs diff compared to the repository head cvs diff -roffline-00-00-13 compared to given tag To see what has changed between revision 1.2 and 1.3 of a file: cvs diff -r1.2 -r1.3

19. Chris Onions Getting started with CVS in ATLAS 1919 Software Evolution For every “versionable” item there is a main trunk and eventual branches 1.1 1.2 1.3 1.4 1.1.2.1 1.1.2.2 HEAD branch head

20. Chris Onions Getting started with CVS in ATLAS 2020 Scenario 3: Creating Branches... lets create and add some other files (arve/examples/Snail/Trail.cxx)... cd ~work/arve/examples/Snail emacs Trail.cxx (and emacs../../../ChangeLog) cvs add Trail.cxx cvs update cvs commit -m ‘See ChangeLog’... we mark a release of the package. We call it arve-00-01-09 cvs rtag arve-00-01-09 offline/arve... we continue working on files.... emacs Trail.cxx cvs update cvs commit -m ‘See ChangeLog’... an urgent bug must be fixed in 01-09 but development in the next version is too advanced but not settled. Create a branch from arve-00-01-09 on which to fix the bug. cvs rtag -b -r arve-00-01-09 arve-00-01-09-branch arve

21. Chris Onions Getting started with CVS in ATLAS 2121 Scenario 3: Merging Branches... we fix the bug (say it was in arve/examples/Snail/Trail.cxx, note this is not its latest version) and commit the changes.... cd ~work/arve/examples/Snail emacs Trail.cxx cvs update cvs commit -m ‘See ChangeLog’... we try to merge it with the main trunk.... cd ~work cvs checkout -d arve offline/arve cd arve cvs update -jarve-00-01-09-branch cvs commit -m “Included release 1.0 bug fix”

22. Chris Onions Getting started with CVS in ATLAS 2222 Reverting changes To revert a file (e.g. control/dicever.F in dice) to an earlier revision 1.2 –cd ~work/dice/control –cvs up -A dicever.F gives you the head revision, e.g. 1.4 –cvs co -p -r1.2 offline/dice/control/dicever.F >dicever.F –cvs ci -m ‘reverting to old version’ dicever.F If you need some corrections from revision 1.3: –cvs up -j1.3 dicever.F

23. Chris Onions Getting started with CVS in ATLAS 2323 Setting up CVS in ATLAS Every developer must: set the environment variable CVSROOT to /afs/cern.ch/atlas/software/cvs have a working directory of his own cvs checkout [whatever] Recommended entries in.cvsrc file: cvs -z9 diff -u update -d Importing a new package: cd ~work/new_package cvs import -m “new_package initial version” \ offline/new_package ATLAS new_package-00-00-00 A package can only be imported into a domain once the domain coordinator has agreed!! For a new top-level pacakge, DIG must agree.

24. Chris Onions Getting started with CVS in ATLAS 2424 Requirements for packages in the repository Packages in the repository are built using srt and thus each package must have –a PACKAGE file –an srt compatible GNUmakefile –most packages will have a GNUmakefile.in configure.in

25. Chris Onions Getting started with CVS in ATLAS 2525 Trying out commands To see what a cvs command will do without actually running it, use the option ‘-n’ e.g. cvs -n update

26. Chris Onions Getting started with CVS in ATLAS 2626 Keywords There are some keywords which you should include in your sources, and CVS will update them: $Id$ $Name$ Never edit these lines by hand! If you copy a file and edit it to create another,replace the original lines by $Id$ and $Name$

27. Chris Onions Getting started with CVS in ATLAS 2727 ATLAS specifics ATLAS software is organised in packages Each package should have a ChangeLog file to record changes made Checking out of several packages into the user’s work area requires that the user does –srt new work e.g. srt new my_work_dir 0.0.14 cd my_work_dir cvs checkout …. for each package

28. Chris Onions Getting started with CVS in ATLAS 2828 Be careful which revision to check out!!! The head revision, which you get by default, is the one under development and may change at any time If you wish to work with a specific release, e.g. offline-00-00-12, check out that tagged version

29. Chris Onions Getting started with CVS in ATLAS 2929 Warning!! Don’t play around with commit, rtag or import in the official repository! If you want to test, set up your own repository: export CVSROOT=myrepository cvs init Packages in the repository are protected against un- controlled changes via access control lists for commit and tagging operations.

30. Chris Onions Getting started with CVS in ATLAS 3030 Miscellaneous Check Outs: cvs history -o Successful Merges: cvs history -x G Unsuccessful Merges: cvs history -x C Files Added: cvs history -x A Releases Made:cvs history -x F Logs on Files: cvs log io/io.c

31. Chris Onions Getting started with CVS in ATLAS 3131 Mailing lists Sign up for the following lists atlas-cvs-notify notification of commit and tagging atlas-sw-developers software development news (releases, etc.) atlas-srt srt developements

32. Chris Onions Getting started with CVS in ATLAS 3232 Finally CVS is just a tool –It’s not a build system (like make) - srt is used to build software releases from the ATLAS repository –Does not substitute communication and management. Automates important tasks. Helps and warns. Transmits the idea of centralisation to your workgroup. Useful even in “stand alone” mode. The ATLAS software will be maintained with cvs and srt as of December 1998

33. Chris Onions Getting started with CVS in ATLAS 3333 More information ATLAS specific http://home.cern.ch/~onions/srtcvs.html AT CERN: http://wwwinfo.cern.ch/dis/asis/products/GNU.DVP/cvs-1.9/Welcome.html On the Internet: http://www.loria.fr/~molli/cvs-index.html http://www.cs.utah.edu/csinfo/texinfo/cvs/cvs_toc.html http://www.cyclic.com/tkcvs/index.html