doc/devel.texi

   1 @node Development Tools
   2 @appendix Development Tools
   3
   4 Here are some tools that you might find useful while developing code.
   5
   6 @menu
   7 * Tags::
   8 * CVS::
   9 * SourceForge::
  10 * VNC::
  11 @end menu
  12
  13 @node Tags
  14 @section Tags
  15
  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
  20 @code{make tags}.
  21
  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-*}.
  28
  29 @node CVS
  30 @section CVS
  31
  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.
  40
  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
  44 the projects.
  45
  46 For more information, visit the @uref{https://www.cvshome.org/, , CVS
  47 home page}.
  48
  49 @menu
  50 * Setting Up CVS::
  51 * Using CVS::
  52 * CVS Locking::
  53 @end menu
  54
  55 @node Setting Up CVS
  56 @subsection Setting Up CVS
  57
  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.
  63
  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.
  74
  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
  87 are secret.}
  88
  89 Now initialize the repository.
  90 To initialize the repository, execute @samp{cvs -d $HOME/cvs init}.
  91
  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
  98 command:
  99 @example
 100 cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start
 101 @end example
 102
 103 Here is a summary of the commands you have now executed:
 104
 105 @example
 106 pts creategroup @var{keeper}:pintos-cvs
 107 pts adduser -user @var{username} -group @var{keeper}:pintos-cvs
 108 mkdir $HOME/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
 114 @end example
 115
 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.
 120
 121 @node Using CVS
 122 @subsection Using CVS
 123
 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.
 128
 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.)
 133
 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
 144 make it permanent).
 145
 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.
 154
 155 You can view the history of @var{file} in your working directory,
 156 including the log messages, with @samp{cvs log @var{file}}.
 157
 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.
 167
 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
 171 commit}.
 172
 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
 176 permanent.
 177
 178 To discard your local changes for a given file, without committing
 179 them, use @samp{cvs update -C @var{file}}.
 180
 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
 187 ago}.
 188
 189 For more information, visit the @uref{https://www.cvshome.org/, , CVS
 190 home page}.
 191
 192 @node CVS Locking
 193 @subsection CVS Locking
 194
 195 You might occasionally see a message like this while using CVS:
 196
 197 @example
 198 waiting for blp's lock in /afs/ir/users/b/l/blp/cvs
 199 @end example
 200
 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.
 204
 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.
 213
 214 @node SourceForge
 215 @section SourceForge
 216
 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, ,
 223 sourceforge.net}.
 224
 225 @node VNC
 226 @section VNC
 227
 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
 234 Home Page}.