Describe cscope.

[pintos-anon] / doc / devel.texi

diff --git a/doc/devel.texi b/doc/devel.texi
index 9a4ed26da74ee1b1177d1b22162cb8ebd9b047f2..d5439ed7e926f0ba6300ae39b4c234ef02f62ae9 100644 (file)
--- a/doc/devel.texi
+++ b/doc/devel.texi
@@ -1,10 +1,11 @@
-@node Development Tools, , Debugging Tools, Top
+@node Development Tools

 @appendix Development Tools
 
 Here are some tools that you might find useful while developing code.
 
 @menu
 * Tags::                        
 @appendix Development Tools
 
 Here are some tools that you might find useful while developing code.
 
 @menu
 * Tags::                        

+* cscope::                      

 * CVS::                         
 * SourceForge::                 
 * VNC::                         
 * CVS::                         
 * SourceForge::                 
 * VNC::                         


@@ -26,6 +27,33 @@ the default target.  If a tag name has multiple definitions, @kbd{M-0
 M-.} jumps to the next one.  To jump back to where you were before
 you followed the last tag, use @kbd{M-*}.
 
 M-.} jumps to the next one.  To jump back to where you were before
 you followed the last tag, use @kbd{M-*}.
 

+@node cscope
+@section cscope
+
+The @command{cscope} program also provides an index to functions and
+variables declared in a program.  It has some features that tag
+facilities lack.  Most notably, it can find all the points in a
+program at which a given function is called.
+
+The @file{Makefile} in @file{pintos/src} produces @command{cscope}
+indexes when it is invoked as @code{make cscope}.  Once the index has
+been generated, run @command{cscope} from a shell command line; no
+command-line arguments are normally necessary.  Then use the arrow
+keys to choose one of the search criteria listed near the bottom of
+the terminal, type in an identifier, and hit @key{Enter}.
+@command{cscope} will then display the matches in the upper part of
+the terminal.  You may use the arrow keys to choose a particular
+match; if you then hit @key{Enter}, @command{cscope} will invoke the
+default system editor@footnote{This is typically @command{vi}.  To
+exit @command{vi}, type @kbd{: q @key{Enter}}.} and position the
+cursor on that match.  To start a new search, type @key{Tab}.  To exit
+@command{cscope}, type @kbd{Ctrl-d}.
+
+Emacs and some versions of @command{vi} have their own interfaces to
+@command{cscope}.  For information on how to use these interface,
+visit @url{http://cscope.sourceforge.net, the @command{cscope} home
+page}.
+

 @node CVS
 @section CVS
 
 @node CVS
 @section CVS
 


@@ -49,6 +77,7 @@ home page}.
 @menu
 * Setting Up CVS::              
 * Using CVS::                   
 @menu
 * Setting Up CVS::              
 * Using CVS::                   

+* CVS Locking::                 

 @end menu
 
 @node Setting Up CVS
 @end menu
 
 @node Setting Up CVS


@@ -76,7 +105,14 @@ members access to it.  We will assume that the repository will be in a
 directory called @file{cvs} in the keeper's home directory.  First
 create this directory with @samp{mkdir $HOME/cvs}, then give group
 members access to it with @samp{fs setacl -dir $HOME/cvs -acl
 directory called @file{cvs} in the keeper's home directory.  First
 create this directory with @samp{mkdir $HOME/cvs}, then give group
 members access to it with @samp{fs setacl -dir $HOME/cvs -acl

-@var{keeper}:pintos-cvs rlidwk}.
+@var{keeper}:pintos-cvs write}.  Group members also need to be able to
+look up the @file{cvs} directory in the keeper's home directory, which
+can be enabled via @samp{fs setacl -dir $HOME -acl
+@var{keeper}:pintos-cvs l} (that's letter ``ell,'' not digit
+``one.'').@footnote{This command will allow group members to list the
+files in your home directory, but not read or write them.  It should not
+create a security risk unless the names of files in your home directory
+are secret.}

 
 Now initialize the repository.
 To initialize the repository, execute @samp{cvs -d $HOME/cvs init}.
 
 Now initialize the repository.
 To initialize the repository, execute @samp{cvs -d $HOME/cvs init}.


@@ -92,6 +128,19 @@ command:
 cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
 @end example
 
 cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
 @end example
 

+Here is a summary of the commands you have now executed:
+
+@example
+pts creategroup @var{keeper}:pintos-cvs
+pts adduser -user @var{username} -group @var{keeper}:pintos-cvs
+mkdir $HOME/cvs
+fs setacl -dir $HOME/cvs -acl @var{keeper}:pintos-cvs write
+fs setacl -dir $HOME -acl @var{keeper}:pintos-cvs l
+cvs -d $HOME/cvs init
+cd /usr/class/cs140/pintos/pintos
+cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
+@end example
+

 The repository is now ready for use by any group member, as described
 below.  Keep in mind that the repository should only be accessed
 using CVS commands---it is not generally useful to examine them by
 The repository is now ready for use by any group member, as described
 below.  Keep in mind that the repository should only be accessed
 using CVS commands---it is not generally useful to examine them by


@@ -101,10 +150,15 @@ hand, and you should definitely not modify them yourself.
 @subsection Using CVS
 
 To use CVS, start by check out a working copy of the contents of the
 @subsection Using CVS
 
 To use CVS, start by check out a working copy of the contents of the

-CVS repository into a directory named @file{@var{dir}}, execute
+CVS repository into a directory named @file{@var{dir}}.  To do so, execute

 @samp{cvs -d ~@var{keeper}/cvs checkout -d @var{dir} pintos}, where
 @var{keeper} is the CVS keeper's Leland username.
 
 @samp{cvs -d ~@var{keeper}/cvs checkout -d @var{dir} pintos}, where
 @var{keeper} is the CVS keeper's Leland username.
 

+(If this fails due to some kind of permission problem, then run
+@command{aklog} and try again.  If it still doesn't work, log out and
+back in.  If that still doesn't fix the problem, the CVS repository may
+not be initialized properly.)
+

 At this point, you can modify any of the files in the working copy.
 You can see the changes you've made with @samp{cvs diff -u}.  If you
 want to commit these changes back to the repository, making them
 At this point, you can modify any of the files in the working copy.
 You can see the changes you've made with @samp{cvs diff -u}.  If you
 want to commit these changes back to the repository, making them


@@ -163,6 +217,28 @@ ago}.
 For more information, visit the @uref{https://www.cvshome.org/, , CVS
 home page}.
 
 For more information, visit the @uref{https://www.cvshome.org/, , CVS
 home page}.
 

+@node CVS Locking
+@subsection CVS Locking
+
+You might occasionally see a message like this while using CVS:
+
+@example
+waiting for blp's lock in /afs/ir/users/b/l/blp/cvs
+@end example
+
+This normally means that more than one user is accessing the repository
+at the same time.  CVS should automatically retry after 30 seconds, at
+which time the operation should normally be able to continue.
+
+If you encounter a long wait for a lock, of more than a minute or so, it
+may indicate that a CVS command did not complete properly and failed to
+remove its locks.  If you think that this is the case, ask the user in
+question about it.  If it appears that an operation did go awry, then
+you (or the named user) can delete files whose names start with
+@file{#cvs.rfl}, @file{#cvs.wfl}, or @file{#cvs.lock} in the directory
+mentioned in the message.  Doing so should allow your operation to
+proceed.  Do not delete or modify other files.
+

 @node SourceForge
 @section SourceForge
 
 @node SourceForge
 @section SourceForge