1 @node Development Tools
2 @appendix Development Tools
4 Here are some tools that you might find useful while developing code.
16 Tags are an index to the functions and global variables declared in a
17 program. Many editors, including Emacs and @command{vi}, can use
18 them. The @file{Makefile} in @file{pintos/src} produces Emacs-style
19 tags with the command @code{make TAGS} or @command{vi}-style tags with
22 In Emacs, use @kbd{M-.} to follow a tag in the current window,
23 @kbd{C-x 4 .} in a new window, or @kbd{C-x 5 .} in a new frame. If
24 your cursor is on a symbol name for any of those commands, it becomes
25 the default target. If a tag name has multiple definitions, @kbd{M-0
26 M-.} jumps to the next one. To jump back to where you were before
27 you followed the last tag, use @kbd{M-*}.
32 CVS is a version-control system. That is, you can use it to keep
33 track of multiple versions of files. The idea is that you do some
34 work on your code and test it, then check it into the version-control
35 system. If you decide that the work you've done since your last
36 check-in is no good, you can easily revert to the last checked-in
37 version. Furthermore, you can retrieve any old version of your code
38 as of some given day and time. The version control logs tell you who
39 made changes and when.
41 CVS is not the best version control system out there, but it's
42 free, it's fairly easy to use, and
43 it's already available on the Leland machines you're using for
46 For more information, visit the @uref{https://www.cvshome.org/, , CVS
56 @subsection Setting Up CVS
58 To set up CVS for use with Pintos on the Leland machines, start by
59 choosing one group member as the keeper of the CVS repository.
60 Everyone in the group will be able to use the CVS repository, but the
61 keeper will actually create the repository, keep its files in his or
62 her home directory, and maintain permissions for its contents.
64 The keeper has to perform several steps to set up the repository.
65 First, create a new AFS group for the repository by executing
66 @samp{pts creategroup @var{keeper}:pintos-cvs}, where @var{keeper} is
67 the keeper's Leland username. Then, add each group member to the new
68 group by repeatedly using the command @samp{pts adduser -user
69 @var{username} -group @var{keeper}:pintos-cvs}, where @var{username}
70 is the name of a group member. After the group is created and its
71 members added, @samp{pts membership @var{keeper}:pintos-cvs} should
72 report that each group member is a member of the
73 @samp{@var{keeper}:pintos-cvs} group.
75 The keeper now creates the repository directory and gives the group
76 members access to it. We will assume that the repository will be in a
77 directory called @file{cvs} in the keeper's home directory. First
78 create this directory with @samp{mkdir $HOME/cvs}, then give group
79 members access to it with @samp{fs setacl -dir $HOME/cvs -acl
80 @var{keeper}:pintos-cvs write}. Group members also need to be able to
81 look up the @file{cvs} directory in the keeper's home directory, which
82 can be enabled via @samp{fs setacl -dir $HOME -acl
83 @var{keeper}:pintos-cvs l} (that's letter ``ell,'' not digit
84 ``one.'').@footnote{This command will allow group members to list the
85 files in your home directory, but not read or write them. It should not
86 create a security risk unless the names of files in your home directory
89 Now initialize the repository.
90 To initialize the repository, execute @samp{cvs -d $HOME/cvs init}.
92 Finally, import the Pintos sources into the newly initialized
93 repository. If you have an existing set of Pintos sources you want to
94 add to the repository, @samp{cd} to its @samp{pintos} directory now.
95 Otherwise, to import the base Pintos source tree, @samp{cd} to
96 @file{/usr/class/cs140/pintos/pintos} (note the doubled
97 @samp{pintos}). After changing the current directory, execute this
100 cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
103 Here is a summary of the commands you have now executed:
106 pts creategroup @var{keeper}:pintos-cvs
107 pts adduser -user @var{username} -group @var{keeper}:pintos-cvs
109 fs setacl -dir $HOME/cvs -acl @var{keeper}:pintos-cvs write
110 fs setacl -dir $HOME -acl @var{keeper}:pintos-cvs l
111 cvs -d $HOME/cvs init
112 cd /usr/class/cs140/pintos/pintos
113 cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
116 The repository is now ready for use by any group member, as described
117 below. Keep in mind that the repository should only be accessed
118 using CVS commands---it is not generally useful to examine them by
119 hand, and you should definitely not modify them yourself.
122 @subsection Using CVS
124 To use CVS, start by check out a working copy of the contents of the
125 CVS repository into a directory named @file{@var{dir}}. To do so, execute
126 @samp{cvs -d ~@var{keeper}/cvs checkout -d @var{dir} pintos}, where
127 @var{keeper} is the CVS keeper's Leland username.
129 (If this fails due to some kind of permission problem, then run
130 @command{aklog} and try again. If it still doesn't work, log out and
131 back in. If that still doesn't fix the problem, the CVS repository may
132 not be initialized properly.)
134 At this point, you can modify any of the files in the working copy.
135 You can see the changes you've made with @samp{cvs diff -u}. If you
136 want to commit these changes back to the repository, making them
137 visible to the other group members, you can use the CVS commit
138 command. Within the @file{pintos} directory, execute @samp{cvs
139 commit}. This will figure out the files that have been changed and
140 fire up a text editor for you to describe the changes. By default,
141 this editor is @file{vi}, but you can select a different editor by
142 setting the @env{CVSEDITOR} environment variable, e.g.@: with
143 @samp{setenv CVSEDITOR emacs} (add this line to your @file{.cvsrc} to
146 Suppose another group member has committed changes. You can see the
147 changes committed to the repository since the time you checked it out
148 (or updated from it) with @samp{cvs diff -u -r BASE -r HEAD}. You can
149 merge those change into your working copy using @samp{cvs update}. If
150 any of your local changes conflict with the committed changes, the CVS
151 command output should tell you. In that case, edit the files that
152 contain conflicts, looking for @samp{<<<} and @samp{>>>} that denote
153 the conflicts, and fix the problem.
155 You can view the history of @var{file} in your working directory,
156 including the log messages, with @samp{cvs log @var{file}}.
158 You can give a particular set of file versions a name called a
159 @dfn{tag}. First @samp{cd} to the root of the working copy, then
160 execute @samp{cvs tag @var{name}}. It's best to have no local changes
161 in the working copy when you do this, because the tag will not include
162 uncommitted changes. To recover the tagged repository later, use the
163 @samp{checkout} command in the form @samp{cvs -d ~@var{keeper}/cvs
164 checkout -r @var{tag} -d @var{dir} pintos}, where @var{keeper} is the
165 username of the CVS keeper and @var{dir} is the directory to put the
166 tagged repository into.
168 If you add a new file to the source tree, you'll need to add it to the
169 repository with @samp{cvs add @var{file}}. This command does not have
170 lasting effect until the file is committed later with @samp{cvs
173 To remove a file from the source tree, first remove it from the file
174 system with @command{rm}, then tell CVS with @samp{cvs remove
175 @var{file}}. Again, only @samp{cvs commit} will make the change
178 To discard your local changes for a given file, without committing
179 them, use @samp{cvs update -C @var{file}}.
181 To check out a version of your repository as of a particular date, use
182 the command @samp{cvs -d ~@var{keeper}/cvs checkout -D '@var{date}' -d
183 @var{dir} pintos}, where @var{keeper} is the username of the CVS
184 keeper and @var{dir} is the directory to put the tagged repository
185 into.. A typical format for @var{date} is @samp{YYYY-MM-DD HH:MM},
186 but CVS accepts several formats, even something like @samp{1 hour
189 For more information, visit the @uref{https://www.cvshome.org/, , CVS
193 @subsection CVS Locking
195 You might occasionally see a message like this while using CVS:
198 waiting for blp's lock in /afs/ir/users/b/l/blp/cvs
201 This normally means that more than one user is accessing the repository
202 at the same time. CVS should automatically retry after 30 seconds, at
203 which time the operation should normally be able to continue.
205 If you encounter a long wait for a lock, of more than a minute or so, it
206 may indicate that a CVS command did not complete properly and failed to
207 remove its locks. If you think that this is the case, ask the user in
208 question about it. If it appears that an operation did go awry, then
209 you (or the named user) can delete files whose names start with
210 @file{#cvs.rfl}, @file{#cvs.wfl}, or @file{#cvs.lock} in the directory
211 mentioned in the message. Doing so should allow your operation to
212 proceed. Do not delete or modify other files.
217 SourceForge is a web-based system for facilitating software
218 development. It provides you with a version-control system (typically
219 CVS, as described above) and other tools for tracking your software.
220 You can use it to store files, track bugs, and post notes about
221 development progress. You can set up your own
222 project in SourceForge at @uref{http://sourceforge.net, ,
228 VNC stands for Virtual Network Computing. It is, in essence, a remote
229 display system which allows you to view a computing ``desktop''
230 environment not only on the machine where it is running, but from
231 anywhere on the Internet and from a wide variety of machine
232 architectures. It is already installed on the Leland machines. For
233 more information, look at the @uref{http://www.realvnc.com/, , VNC
projects / pintos-anon / blob