Describe cscope.
[pintos-anon] / doc / devel.texi
index ece70a9a17381fa2d6add1e4affdf4d8bb1adf05..d5439ed7e926f0ba6300ae39b4c234ef02f62ae9 100644 (file)
@@ -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
@@ -121,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
@@ -183,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