1 @node Development Tools
2 @appendix Development Tools
4 Here are some tools that you might find useful while developing code.
17 Tags are an index to the functions and global variables declared in a
18 program. Many editors, including Emacs and @command{vi}, can use
19 them. The @file{Makefile} in @file{pintos/src} produces Emacs-style
20 tags with the command @code{make TAGS} or @command{vi}-style tags with
23 In Emacs, use @kbd{M-.} to follow a tag in the current window,
24 @kbd{C-x 4 .} in a new window, or @kbd{C-x 5 .} in a new frame. If
25 your cursor is on a symbol name for any of those commands, it becomes
26 the default target. If a tag name has multiple definitions, @kbd{M-0
27 M-.} jumps to the next one. To jump back to where you were before
28 you followed the last tag, use @kbd{M-*}.
33 The @command{cscope} program also provides an index to functions and
34 variables declared in a program. It has some features that tag
35 facilities lack. Most notably, it can find all the points in a
36 program at which a given function is called.
38 The @file{Makefile} in @file{pintos/src} produces @command{cscope}
39 indexes when it is invoked as @code{make cscope}. Once the index has
40 been generated, run @command{cscope} from a shell command line; no
41 command-line arguments are normally necessary. Then use the arrow
42 keys to choose one of the search criteria listed near the bottom of
43 the terminal, type in an identifier, and hit @key{Enter}.
44 @command{cscope} will then display the matches in the upper part of
45 the terminal. You may use the arrow keys to choose a particular
46 match; if you then hit @key{Enter}, @command{cscope} will invoke the
47 default system editor@footnote{This is typically @command{vi}. To
48 exit @command{vi}, type @kbd{: q @key{Enter}}.} and position the
49 cursor on that match. To start a new search, type @key{Tab}. To exit
50 @command{cscope}, type @kbd{Ctrl-d}.
52 Emacs and some versions of @command{vi} have their own interfaces to
53 @command{cscope}. For information on how to use these interface,
54 visit @url{http://cscope.sourceforge.net, the @command{cscope} home
60 CVS is a version-control system. That is, you can use it to keep
61 track of multiple versions of files. The idea is that you do some
62 work on your code and test it, then check it into the version-control
63 system. If you decide that the work you've done since your last
64 check-in is no good, you can easily revert to the last checked-in
65 version. Furthermore, you can retrieve any old version of your code
66 as of some given day and time. The version control logs tell you who
67 made changes and when.
69 CVS is not the best version control system out there, but it's
70 free, it's fairly easy to use, and
71 it's already available on the Leland machines you're using for
74 For more information, visit the @uref{https://www.cvshome.org/, , CVS
84 @subsection Setting Up CVS
86 To set up CVS for use with Pintos on the Leland machines, start by
87 choosing one group member as the keeper of the CVS repository.
88 Everyone in the group will be able to use the CVS repository, but the
89 keeper will actually create the repository, keep its files in his or
90 her home directory, and maintain permissions for its contents.
92 The keeper has to perform several steps to set up the repository.
93 First, create a new AFS group for the repository by executing
94 @samp{pts creategroup @var{keeper}:pintos-cvs}, where @var{keeper} is
95 the keeper's Leland username. Then, add each group member to the new
96 group by repeatedly using the command @samp{pts adduser -user
97 @var{username} -group @var{keeper}:pintos-cvs}, where @var{username}
98 is the name of a group member. After the group is created and its
99 members added, @samp{pts membership @var{keeper}:pintos-cvs} should
100 report that each group member is a member of the
101 @samp{@var{keeper}:pintos-cvs} group.
103 The keeper now creates the repository directory and gives the group
104 members access to it. We will assume that the repository will be in a
105 directory called @file{cvs} in the keeper's home directory. First
106 create this directory with @samp{mkdir $HOME/cvs}, then give group
107 members access to it with @samp{fs setacl -dir $HOME/cvs -acl
108 @var{keeper}:pintos-cvs write}. Group members also need to be able to
109 look up the @file{cvs} directory in the keeper's home directory, which
110 can be enabled via @samp{fs setacl -dir $HOME -acl
111 @var{keeper}:pintos-cvs l} (that's letter ``ell,'' not digit
112 ``one.'').@footnote{This command will allow group members to list the
113 files in your home directory, but not read or write them. It should not
114 create a security risk unless the names of files in your home directory
117 Now initialize the repository.
118 To initialize the repository, execute @samp{cvs -d $HOME/cvs init}.
120 Finally, import the Pintos sources into the newly initialized
121 repository. If you have an existing set of Pintos sources you want to
122 add to the repository, @samp{cd} to its @samp{pintos} directory now.
123 Otherwise, to import the base Pintos source tree, @samp{cd} to
124 @file{/usr/class/cs140/pintos/pintos} (note the doubled
125 @samp{pintos}). After changing the current directory, execute this
128 cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
131 Here is a summary of the commands you have now executed:
134 pts creategroup @var{keeper}:pintos-cvs
135 pts adduser -user @var{username} -group @var{keeper}:pintos-cvs
137 fs setacl -dir $HOME/cvs -acl @var{keeper}:pintos-cvs write
138 fs setacl -dir $HOME -acl @var{keeper}:pintos-cvs l
139 cvs -d $HOME/cvs init
140 cd /usr/class/cs140/pintos/pintos
141 cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
144 The repository is now ready for use by any group member, as described
145 below. Keep in mind that the repository should only be accessed
146 using CVS commands---it is not generally useful to examine them by
147 hand, and you should definitely not modify them yourself.
150 @subsection Using CVS
152 To use CVS, start by check out a working copy of the contents of the
153 CVS repository into a directory named @file{@var{dir}}. To do so, execute
154 @samp{cvs -d ~@var{keeper}/cvs checkout -d @var{dir} pintos}, where
155 @var{keeper} is the CVS keeper's Leland username.
157 (If this fails due to some kind of permission problem, then run
158 @command{aklog} and try again. If it still doesn't work, log out and
159 back in. If that still doesn't fix the problem, the CVS repository may
160 not be initialized properly.)
162 At this point, you can modify any of the files in the working copy.
163 You can see the changes you've made with @samp{cvs diff -u}. If you
164 want to commit these changes back to the repository, making them
165 visible to the other group members, you can use the CVS commit
166 command. Within the @file{pintos} directory, execute @samp{cvs
167 commit}. This will figure out the files that have been changed and
168 fire up a text editor for you to describe the changes. By default,
169 this editor is @file{vi}, but you can select a different editor by
170 setting the @env{CVSEDITOR} environment variable, e.g.@: with
171 @samp{setenv CVSEDITOR emacs} (add this line to your @file{.cvsrc} to
174 Suppose another group member has committed changes. You can see the
175 changes committed to the repository since the time you checked it out
176 (or updated from it) with @samp{cvs diff -u -r BASE -r HEAD}. You can
177 merge those change into your working copy using @samp{cvs update}. If
178 any of your local changes conflict with the committed changes, the CVS
179 command output should tell you. In that case, edit the files that
180 contain conflicts, looking for @samp{<<<} and @samp{>>>} that denote
181 the conflicts, and fix the problem.
183 You can view the history of @var{file} in your working directory,
184 including the log messages, with @samp{cvs log @var{file}}.
186 You can give a particular set of file versions a name called a
187 @dfn{tag}. First @samp{cd} to the root of the working copy, then
188 execute @samp{cvs tag @var{name}}. It's best to have no local changes
189 in the working copy when you do this, because the tag will not include
190 uncommitted changes. To recover the tagged repository later, use the
191 @samp{checkout} command in the form @samp{cvs -d ~@var{keeper}/cvs
192 checkout -r @var{tag} -d @var{dir} pintos}, where @var{keeper} is the
193 username of the CVS keeper and @var{dir} is the directory to put the
194 tagged repository into.
196 If you add a new file to the source tree, you'll need to add it to the
197 repository with @samp{cvs add @var{file}}. This command does not have
198 lasting effect until the file is committed later with @samp{cvs
201 To remove a file from the source tree, first remove it from the file
202 system with @command{rm}, then tell CVS with @samp{cvs remove
203 @var{file}}. Again, only @samp{cvs commit} will make the change
206 To discard your local changes for a given file, without committing
207 them, use @samp{cvs update -C @var{file}}.
209 To check out a version of your repository as of a particular date, use
210 the command @samp{cvs -d ~@var{keeper}/cvs checkout -D '@var{date}' -d
211 @var{dir} pintos}, where @var{keeper} is the username of the CVS
212 keeper and @var{dir} is the directory to put the tagged repository
213 into.. A typical format for @var{date} is @samp{YYYY-MM-DD HH:MM},
214 but CVS accepts several formats, even something like @samp{1 hour
217 For more information, visit the @uref{https://www.cvshome.org/, , CVS
221 @subsection CVS Locking
223 You might occasionally see a message like this while using CVS:
226 waiting for blp's lock in /afs/ir/users/b/l/blp/cvs
229 This normally means that more than one user is accessing the repository
230 at the same time. CVS should automatically retry after 30 seconds, at
231 which time the operation should normally be able to continue.
233 If you encounter a long wait for a lock, of more than a minute or so, it
234 may indicate that a CVS command did not complete properly and failed to
235 remove its locks. If you think that this is the case, ask the user in
236 question about it. If it appears that an operation did go awry, then
237 you (or the named user) can delete files whose names start with
238 @file{#cvs.rfl}, @file{#cvs.wfl}, or @file{#cvs.lock} in the directory
239 mentioned in the message. Doing so should allow your operation to
240 proceed. Do not delete or modify other files.
245 SourceForge is a web-based system for facilitating software
246 development. It provides you with a version-control system (typically
247 CVS, as described above) and other tools for tracking your software.
248 You can use it to store files, track bugs, and post notes about
249 development progress. You can set up your own
250 project in SourceForge at @uref{http://sourceforge.net, ,
256 VNC stands for Virtual Network Computing. It is, in essence, a remote
257 display system which allows you to view a computing ``desktop''
258 environment not only on the machine where it is running, but from
259 anywhere on the Internet and from a wide variety of machine
260 architectures. It is already installed on the Leland machines. For
261 more information, look at the @uref{http://www.realvnc.com/, , VNC