Pintos (UChicago edition)

h1. Getting the Pintos code into your PhoenixForge repository

Although you could just check out or export the Pintos code, and then commit it to your repository, we prefer that you use an intermediate _external branch_ in your repository. We don't expect that we'll have to make any changes to the provided Pintos code (since it has been pretty thoroughly tested in many other OS courses) but, if we do, using an external branch will make it easier for you to merge those changes into your code. The process for getting the code into your repository, by way of an external branch, is described here. These instructions are based on the "Vendor Branches" section of the SVN book. See http://svnbook.red-bean.com/en/1.5/svn.advanced.vendorbr.html for more details.

h2. Copying the code into your repository

To import the Pintos code into your repository, first do the following in a temporary directory:

<pre>

svn export https://phoenixforge.cs.uchicago.edu/svn/pintos/trunk pintos

</pre> 

This will create a directory called @pintos@, containing the Pintos code. Now, import it into your group's repository like this:

<pre>

svn import pintos https://phoenixforge.cs.uchicago.edu/svn/$CS230_GROUPNAME/external/pintos

</pre>

Notice how, we're not importing the Pintos code into the @trunk@ directory (which is typically used to contain the ``main branch'' of your code). To keep your code synchronized with the Pintos code, we are going to make use of SVN's merge functionality, which requires that we keep this @external@ code in a separate directory (the _external branch_). Of course, you still want to have your own copy where you will actually be writing your own code (the _main branch_). We make this copy like this:

<pre>

svn copy https://phoenixforge.cs.uchicago.edu/svn/$CS230_GROUPNAME/external/pintos \

         https://phoenixforge.cs.uchicago.edu/svn/$CS230_GROUPNAME/trunk/pintos \

         --parents

</pre>

Next, you need to create working copies for each of these two copies. _You need to keep these in separate directories_. So, in an empty directory (we will refer to it as @$BASE_DIR@) run the following to create a working copy of the Pintos code:

<pre>

svn checkout https://phoenixforge.cs.uchicago.edu/svn/$CS230_GROUPNAME/external/pintos

</pre>

And, _in a separate directory_ (we will refer to this one as @$MAIN_DIR@), run the following to create a working copy of your main branch:

<pre>

svn checkout https://phoenixforge.cs.uchicago.edu/svn/$CS230_GROUPNAME/trunk/pintos

</pre>

h2. Propagating changes into your repository

Now, let's say that there have been changes to the Pintos code that we provide. Merging them into your trunk is a two-step process:

# Update the external branch in your repository with the latest Pintos code.

# Merge the new Pintos code into your own, resolving any conflicts if necessary.

The first step is the kludgiest one, but also highly scriptable (SVN includes a script called @svn_load_dirs.pl@ that can help you automate this step. You essentially have to @svn import@ the Pintos code again, and overwrite the code in @$BASE_DIR@ with the newest version. If necessary, you may have to manually run @svn add@ to add new files and @svn delete@ to remove files that are no longer present in the latest version of the Pintos code. Once you have done this, just run @svn commit@ to commit the new version into your external branch.

The second step is handled by @svn merge@ which, in the best case, will automatically merge all the new code into your own but, in the worst case, will require you to resolve conflicts between your code and the latest version of the Pintos code. To merge the code, run the following

<pre>

svn merge https://phoenixforge.cs.uchicago.edu/svn/$CS230_GROUPNAME/external/pintos \

          $MAIN_DIR

</pre>

If you're lucky, and there are no conflicts, you will see something like this:

<pre>

--- Merging r3 through r5 into 'pintos':

U    pintos/tests/main.h

U    pintos/Makefile.kernel

</pre>

If a conflict happens, then you will be given the option to resolve it manually:

<pre>

Conflict discovered in 'pintos/tests/main.h'.

Select: (p) postpone, (df) diff-full, (e) edit,

        (h) help for more options:

</pre> 

@df@ will show a diff between your code and the code you are merging in, and @e@ will allow you to edit your code to resolve the conflicts manually. Once you've edited the file, you will be allowed to select the option @(r) resolve@.

Once the merge is complete, you have to run @svn commit@ to actually commit the merged version into your main branch.