X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fdevel.texi;h=d5439ed7e926f0ba6300ae39b4c234ef02f62ae9;hb=41c6d30ad899676a4362bc1a18fca3d7c3eb3c49;hp=3491a3606e171fc28225e534cf92c97a7150b46c;hpb=699944803572c46c550a39027c0ebd935b0d61bc;p=pintos-anon diff --git a/doc/devel.texi b/doc/devel.texi index 3491a36..d5439ed 100644 --- a/doc/devel.texi +++ b/doc/devel.texi @@ -1,3 +1,262 @@ @node Development Tools @appendix Development Tools +Here are some tools that you might find useful while developing code. + +@menu +* Tags:: +* cscope:: +* CVS:: +* SourceForge:: +* VNC:: +@end menu + +@node Tags +@section Tags + +Tags are an index to the functions and global variables declared in a +program. Many editors, including Emacs and @command{vi}, can use +them. The @file{Makefile} in @file{pintos/src} produces Emacs-style +tags with the command @code{make TAGS} or @command{vi}-style tags with +@code{make tags}. + +In Emacs, use @kbd{M-.} to follow a tag in the current window, +@kbd{C-x 4 .} in a new window, or @kbd{C-x 5 .} in a new frame. If +your cursor is on a symbol name for any of those commands, it becomes +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-*}. + +@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 + +CVS is a version-control system. That is, you can use it to keep +track of multiple versions of files. The idea is that you do some +work on your code and test it, then check it into the version-control +system. If you decide that the work you've done since your last +check-in is no good, you can easily revert to the last checked-in +version. Furthermore, you can retrieve any old version of your code +as of some given day and time. The version control logs tell you who +made changes and when. + +CVS is not the best version control system out there, but it's +free, it's fairly easy to use, and +it's already available on the Leland machines you're using for +the projects. + +For more information, visit the @uref{https://www.cvshome.org/, , CVS +home page}. + +@menu +* Setting Up CVS:: +* Using CVS:: +* CVS Locking:: +@end menu + +@node Setting Up CVS +@subsection Setting Up CVS + +To set up CVS for use with Pintos on the Leland machines, start by +choosing one group member as the keeper of the CVS repository. +Everyone in the group will be able to use the CVS repository, but the +keeper will actually create the repository, keep its files in his or +her home directory, and maintain permissions for its contents. + +The keeper has to perform several steps to set up the repository. +First, create a new AFS group for the repository by executing +@samp{pts creategroup @var{keeper}:pintos-cvs}, where @var{keeper} is +the keeper's Leland username. Then, add each group member to the new +group by repeatedly using the command @samp{pts adduser -user +@var{username} -group @var{keeper}:pintos-cvs}, where @var{username} +is the name of a group member. After the group is created and its +members added, @samp{pts membership @var{keeper}:pintos-cvs} should +report that each group member is a member of the +@samp{@var{keeper}:pintos-cvs} group. + +The keeper now creates the repository directory and gives the group +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 +@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}. + +Finally, import the Pintos sources into the newly initialized +repository. If you have an existing set of Pintos sources you want to +add to the repository, @samp{cd} to its @samp{pintos} directory now. +Otherwise, to import the base Pintos source tree, @samp{cd} to +@file{/usr/class/cs140/pintos/pintos} (note the doubled +@samp{pintos}). After changing the current directory, execute this +command: +@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 +hand, and you should definitely not modify them yourself. + +@node Using CVS +@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}}. 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. + +(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 +visible to the other group members, you can use the CVS commit +command. Within the @file{pintos} directory, execute @samp{cvs +commit}. This will figure out the files that have been changed and +fire up a text editor for you to describe the changes. By default, +this editor is @file{vi}, but you can select a different editor by +setting the @env{CVSEDITOR} environment variable, e.g.@: with +@samp{setenv CVSEDITOR emacs} (add this line to your @file{.cvsrc} to +make it permanent). + +Suppose another group member has committed changes. You can see the +changes committed to the repository since the time you checked it out +(or updated from it) with @samp{cvs diff -u -r BASE -r HEAD}. You can +merge those change into your working copy using @samp{cvs update}. If +any of your local changes conflict with the committed changes, the CVS +command output should tell you. In that case, edit the files that +contain conflicts, looking for @samp{<<<} and @samp{>>>} that denote +the conflicts, and fix the problem. + +You can view the history of @var{file} in your working directory, +including the log messages, with @samp{cvs log @var{file}}. + +You can give a particular set of file versions a name called a +@dfn{tag}. First @samp{cd} to the root of the working copy, then +execute @samp{cvs tag @var{name}}. It's best to have no local changes +in the working copy when you do this, because the tag will not include +uncommitted changes. To recover the tagged repository later, use the +@samp{checkout} command in the form @samp{cvs -d ~@var{keeper}/cvs +checkout -r @var{tag} -d @var{dir} pintos}, where @var{keeper} is the +username of the CVS keeper and @var{dir} is the directory to put the +tagged repository into. + +If you add a new file to the source tree, you'll need to add it to the +repository with @samp{cvs add @var{file}}. This command does not have +lasting effect until the file is committed later with @samp{cvs +commit}. + +To remove a file from the source tree, first remove it from the file +system with @command{rm}, then tell CVS with @samp{cvs remove +@var{file}}. Again, only @samp{cvs commit} will make the change +permanent. + +To discard your local changes for a given file, without committing +them, use @samp{cvs update -C @var{file}}. + +To check out a version of your repository as of a particular date, use +the command @samp{cvs -d ~@var{keeper}/cvs checkout -D '@var{date}' -d +@var{dir} pintos}, where @var{keeper} is the username of the CVS +keeper and @var{dir} is the directory to put the tagged repository +into.. A typical format for @var{date} is @samp{YYYY-MM-DD HH:MM}, +but CVS accepts several formats, even something like @samp{1 hour +ago}. + +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 + +SourceForge is a web-based system for facilitating software +development. It provides you with a version-control system (typically +CVS, as described above) and other tools for tracking your software. +You can use it to store files, track bugs, and post notes about +development progress. You can set up your own +project in SourceForge at @uref{http://sourceforge.net, , +sourceforge.net}. + +@node VNC +@section VNC + +VNC stands for Virtual Network Computing. It is, in essence, a remote +display system which allows you to view a computing ``desktop'' +environment not only on the machine where it is running, but from +anywhere on the Internet and from a wide variety of machine +architectures. It is already installed on the Leland machines. For +more information, look at the @uref{http://www.realvnc.com/, , VNC +Home Page}.