X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?p=pintos-anon;a=blobdiff_plain;f=doc%2Fdevel.texi;h=eae54d163956de002a61f1d78424326704c31509;hp=1aff0655940c6293c7d2adb41205eec7bf41eef7;hb=5af653aea4f817d41de3d2ab3a9eeaec44016234;hpb=8e5950ea4890a031454309cb4a5428ea73266078 diff --git a/doc/devel.texi b/doc/devel.texi index 1aff065..eae54d1 100644 --- a/doc/devel.texi +++ b/doc/devel.texi @@ -1,13 +1,21 @@ -@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:: -* CVS:: -* SourceForge:: -* VNC:: +* Tags:: +* cscope:: +* CVS:: +@ifset recommendsourceforge +* SourceForge:: +@end ifset +@ifset recommendvnc +* VNC:: +@end ifset +@ifset recommendcygwin +* Cygwin:: +@end ifset @end menu @node Tags @@ -26,6 +34,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-*}. +@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 @@ -39,155 +74,15 @@ 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. +free, it's fairly easy to use, and it's already installed in most +Unix-like environments. For more information, visit the @uref{https://www.cvshome.org/, , CVS home page}. -@menu -* Setting Up CVS:: -* Using CVS:: -@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}. +@include localcvsinstructions.texi +@ifset recommendsourceforge @node SourceForge @section SourceForge @@ -198,7 +93,9 @@ 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}. +@end ifset +@ifset recommendvnc @node VNC @section VNC @@ -206,6 +103,22 @@ 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 +architectures. It is already installed on the lab machines. +For more information, look at the @uref{http://www.realvnc.com/, , VNC Home Page}. +@end ifset + +@ifset recommendcygwin +@node Cygwin +@section Cygwin + +@uref{http://cygwin.com/, ,Cygwin} provides a Linux-compatible environment +for Windows. It includes ssh client and an X11 server, Cygwin/X. If your +primary work environment is Windows, you will find Cygwin/X extremely +useful for these projects. Install Cygwin/X, then start the X server +and open a new xterm. The X11 server also allows you to run pintos while +displaying the bochs- or qemu-emulated console on your Windows desktop. +@end ifset + +@localdevelopmenttools{} +