chris onions getting started with cvs in atlas 11 getting started with cvs in atlas chris onions...

Getting started with CVS in ATLAS 1

Chris Onions 1

Getting started with CVS in ATLAS

Chris Onions(Tutorial based on that of

Raúl Ramos Pollán

CERN / IT Division)


Chris Onions 2

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.


Chris Onions 3

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


Chris Onions 4

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


Chris Onions 5

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).


Chris Onions 6

Scenario 1cd ~workcvs 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 directorycvs status -v PACKAGE

Once committed, remove it from your directorycvs release -d PACKAGE


Chris Onions 7

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


Chris Onions 8

cvs status contd. Existing Tags:

offline-00-00-14 (revision: 1.4)

dice-03-20-03 (revision: 1.4)







offline-00-00-09 (revision: 1.1.1.1)



etc.


Chris Onions 9

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


Chris Onions 10

File statusupdate 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 file will be added on next commit

R file will be removed on next commit

M file file is modified in local directory

C file a conflict detected during merge

? file in local directory, not in repository


Chris Onions 11

Scenario 2: MergingDEVELOPER 1:

cvs checkout -d arve offline/arveedits arve/examples/Snail/Snail.cxx file but doesn’t

commit ...DEVELOPER 2:

cvs checkout -d arve offline/arveedits arve/examples/Snail/Snail.cxx file and commits

DEVELOPER 1:cd arvecvs 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


Chris Onions 12

Scenario 2: ConflictsBOTH: .... if not up to date

cd ~workcvs checkout -d arve offline/arve... edit same part of Snail.cxx...

DEVELOPER 1:cvs updatecvs 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 updatecvs commit -m ‘See ChangeLog’


Chris Onions 13

Scenario 2: IndependencyDEVELOPER 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 directoryTHIS: cd arve

cvs update arve/DataControl.cxx

IS EQUIVALENT TO:cvs update arve/arve/DataControl.cxx


Chris Onions 14

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


Chris Onions 15

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


Chris Onions 16

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


Chris Onions 17

Software Releases

• A Release is made of revisions of files

file1 file2 file3 file4

1.1

1.2

1.3

1.1

1.2

1.3

1.1

1.2

1.3

1.1

1.2

1.41.4

1.5

offline-00-00-14


Chris Onions 18

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 <filename>


Chris Onions 19

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


Chris Onions 20

Scenario 3: Creating Branches... lets create and add some other files (arve/examples/Snail/Trail.cxx) ...

cd ~work/arve/examples/Snailemacs Trail.cxx (and emacs ../../../ChangeLog)cvs add Trail.cxxcvs updatecvs commit -m ‘See ChangeLog’

... we mark a release of the package. We call it arve-00-01-09cvs rtag arve-00-01-09 offline/arve

... we continue working on files ....emacs Trail.cxx cvs updatecvs 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


Chris Onions 21

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/Snailemacs Trail.cxxcvs updatecvs commit -m ‘See ChangeLog’

... we try to merge it with the main trunk ....cd ~work cvs checkout -d arve offline/arvecd arvecvs update -jarve-00-01-09-branchcvs commit -m “Included release 1.0 bug fix”


Chris Onions 22

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


Chris Onions 23

Setting up CVS in ATLAS

Every developer must: set the environment variable CVSROOT to/afs/cern.ch/atlas/software/cvshave a working directory of his owncvs checkout [whatever]

Recommended entries in .cvsrc file:cvs -z9diff -uupdate -d

Importing a new package:cd ~work/new_packagecvs import -m “new_package initial version” \

offline/new_package ATLAS new_package-00-00-00A package can only be imported into a domain once the domain coordinator has agreed!! For a new top-level pacakge, DIG must agree.


Chris Onions 24

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


Chris Onions 25

Trying out commands

• To see what a cvs command will do without actually running it, use the option ‘-n’

e.g.

cvs -n update


Chris Onions 26

KeywordsThere are some keywords which you should include in yoursources, and CVS will update them:

$Id$

$Name$

Never edit these lines by hand!

If you copy a file and edit it to createanother,replace the original lines by$Id$ and $Name$


Chris Onions 27

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 <version>

e.g. srt new my_work_dir 0.0.14

cd my_work_dir

cvs checkout …. for each package


Chris Onions 28

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


Chris Onions 29

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.


Chris Onions 30

Miscellaneous

Check Outs: cvs history -oSuccessful Merges: cvs history -x GUnsuccessful Merges: cvs history -x CFiles Added: cvs history -x AReleases Made: cvs history -x F

Logs on Files: cvs log io/io.c


Chris Onions 31

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


Chris Onions 32

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 maintainedwith cvs and srt as of December 1998


Chris Onions 33

More informationATLAS 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.htmlhttp://www.cs.utah.edu/csinfo/texinfo/cvs/cvs_toc.htmlhttp://www.cyclic.com/tkcvs/index.html

chris onions getting started with cvs in atlas 11 getting started with cvs in atlas chris onions...

Documents