| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are some tools that you might find useful while developing code.
Tags are an index to the functions and global variables declared in a
program. Many editors, including Emacs and vi, can use
them. The Makefile
in pintos/src
produces Emacs-style
tags with the command make TAGS or vi-style tags with
make tags.
In Emacs, use M-. to follow a tag in the current window, C-x 4 . in a new window, or 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, M-0 M-. jumps to the next one. To jump back to where you were before you followed the last tag, use M-*.
The 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 Makefile
in pintos/src
produces cscope
indexes when it is invoked as make cscope. Once the index has
been generated, run 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 Enter.
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 Enter, cscope will invoke the
default system editor(9) and position the
cursor on that match. To start a new search, type Tab. To exit
cscope, type Ctrl-d.
Emacs and some versions of vi have their own interfaces to
cscope. For information on how to use these interface,
visit http://cscope.sourceforge.net, the cscope home
page.
The Pintos codebase is rather substantial, and you will be working in teams to develop some complex features on the project. In situations like this, a version control system is absolutely essential so that you can coordinate your interactions with the codebase, and so you can record checkpoints of your work as you go. Additionally, you will submit your work using the version-control system so that we can retrieve and grade what you have done.
We will be using the Git distributed version control system for
CS124. You may already have Git installed on your computer;
you can find out by opening a command prompt and typing git to
see what happens. If you don't already have Git installed, you can install
it onto your local machine from the following website:
http://git-scm.com/. There are installers for all major operating
systems.
Once you have installed Git on your computer, configure it with your user information. This information will be included with every commit you make to your repository. The double-quotes in these commands are necessary if you have spaces in the values you specify.
git config --global user.name "Your Name"
git config --global user.email "your@email.tld"
You will probably also find it helpful to turn on colorful output:
git config --global color.ui true
We will be using GitHub Classroom this term to manage team repositories. If you don't have a GitHub account, you can visit https://www.github.com to create one.
You should configure your GitHub account with an SSH key to access your repository. This is the typical way that developers access shared Git servers.
ssh-agent, which allows you
to type a given SSH key's passphrase once, and then will automatically
authenticate on your behalf when negotiating SSH connections. This is
a very helpful thing to become familiar with. (The corollary is that
you should basically never generate SSH keys that don't require
a passphrase. It's usually a disastrously bad idea.)
Once you have gotten SSH access configured, you can clone your team's repository to your local working environment with a command like this:
git clone git@github.com:caltech-cs124-2021sp/cs124-2021sp-yourteam.git
This will create a local directory named cs124-2021sp-yourteam
in which you can do your software development. The best part is, all of your
local changes will be isolated from everyone else, and even the most recent
code in the codebase, until the point you decide to commit your work back to
the repository.
You should be aware that your local repository actually contains two
components in one. First, you will see directories and files like src
,
etc. (For the first two projects, you will only have a src
directory,
but other directories will be added as the course progresses.) These are
actually not part of the Git repository itself; they are a working copy that
you can edit separately. If you decide you don't like the changes you have
made in your working copy, you can always revert back to the repository
version with no problems.
When you are completely satisfied with your changes, then you can commit these
changes to your own local repository. The repository itself is stored in a
subdirectory named .git
, which you can see if you type
"ls -al". (Feel free to look in this directory, but don't muck
with anything in there unless you absolutely know what you are doing.)
As you work on your projects, you may want to commit your changes as you get
various parts of the project working. In fact, you are encouraged to do this!
Nothing is more frustrating than completing a complicated feature, and then
immediately mangling it as you start working on the next task. Commit
your work every time you complete anything that you don't feel like doing
again. At any point in your work, you can run the command
"git status" to see what files have been modified in your working
directory.
The command you use to commit changes to your local repository is
"git commit". However, it is important to understand Git's
workflow for committing changes to the repository. Changes you make in your
working directory will not immediately be included when you commit to your
repository; rather, Git maintains a "staging area" of changes that will be
included in the next commit. In other words, you can make some changes that
will be included in the commit, and other changes that will not be included
in the commit. A file whose changes will be included in the next commit is
described as being "staged" (i.e. its changes are included in the staging
area). A file whose changes will not be included in the next commit is
"unstaged," or "modified but not staged."
To complicate this somewhat, files also fall into two categories: "tracked" files, which have been added to the repository and Git is managing them; and "untracked" files, which have not yet been added to the repository.
The upshot of all this is that if you want to add a new file to your
repository, or you want to include changes of an existing file into your
repository, you must run "git add filename" to include the file
in the staging area. Then, these changes will be included in the next commit.
There is a simplification for when you haven't added any new files: you can
run "git commit -a", which will perform the staging step as well as
the commit step. However, if you create a brand new file, you still need to
run "git add filename" on that new file before it will be committed.
When you are ready to share your local work with the rest of your team, you can run this command to push all of your changes back to the team's Git repository:
git push
That's really all it takes! Of course, the rest of the team must then pull
your changes into their local repositories by running "git pull".
This will bring all changes in the team repository down to the local
repository.
There are two important rules that you must always follow:
The corrolary is that if you are going to break the code in the team repository, make sure your team knows first. That way they can avoid pulling the changes if they are in the middle of other work.
When your team has completed a project to the team's satisfaction, these are the steps to submit it for grading:
git tag projectn-version"
For example, after completing the command shell, one teammate could do the following:
git tag project1-1
This tag will only be in the local repository, so once it is tagged, the tag also needs to be pushed to the team repository:
git push --tags
If you discover a bug in your work and you want to fix it, feel free to
do so and then retag your work, but increment the version, e.g.
"project1-2". If you try to reuse the same tag you will run
into some trouble with Git, so make sure each tag is unique.
Also, if multiple teammates create the same tag name on different commits in their local repositories, and then try to push them to the team repository, this will cause some serious problems.
To ensure uniformity of development platforms, it is strongly recommended that students develop Pintos on a 32-bit Linux platform. For students that don't have access to such a platform (probably most if not all students), a virtual machine image is provided for use with Oracle Virtual Box. VirtualBox is freely available at http://www.virtualbox.org.
Instructions for how to acquire, setup and use the virtual machine image are available on the course Canvas website.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |