CVS - What is it and How do I use it?
=====================================


Updated
=======

2005-Jul-17  Added Firewall Information
             No longer need to retrieve fonts seperately

2005-Mar-08  Added note about the iRiver 'bootloader' in Summary.
             Added note about the outdated Package List.


Intro
=====

This is an edited transciption of an IRC chat held between myself [BlueChip]
and Linus on IRC on 18/06/2004 at about 06:00.

It is a complete walk through on how to use CVS.

The original log can be found here:
    http://rockbox.haxx.se/irc/rockbox-20040618.txt



Key
===

BlueChip:  Speaks

LinusN:    Speaks

[BlueChip] ** Performs an action on his computer



The Edited Transciption
========================

           --- INTRO ---

BlueChip:  JUST finished getting the new DevKit version 3 going :)
LinusN:    Already? :-)
BlueChip:  :)
BlueChip:  Thanks for all your help
LinusN:    You're welcome

BlueChip:  Now to try CVS ...again - lol
LinusN:    Want me to walk you through it?
BlueChip:  That'd be great if you have the time - Please go slowly for me ;)
LinusN:    Whenever you're ready
BlueChip:  ...awaiting your words of wisdom :)

           --- WHAT IS CVS ---

LinusN:    I presume you know what CVS stands for?
BlueChip:  That much I do know, Concurrent Version System :)

LinusN:    Do you know the basic concepts behind CVS?
           Have you worked with other Version Control Systems?
BlueChip:  Sadly the thing I used at my last company was a weird in-house thing
           ...knocked up one lunchtime - judging by the interface.

LinusN:    OK - The CVS server keeps a Repository, where all the Rockbox source
           files reside
BlueChip:  OK

           --- SOURCE CODE DIVISION ---

LinusN:    These source files are divided into groups, called Modules
           In Rockbox, "apps" is one module, "firmware" is another, etc.
BlueChip:  OK - I read about those on the Rockbox homepage
           http://rockbox.haxx.se/twiki/bin/view/Main/UsingCVS

LinusN:    We have also grouped several modules together in larger, virtual
           modules rockbox, rockbox-all etc
BlueChip:  OK - I can see those on the web page too :)

LinusN:    When you check out a module, all files are copied to your hard drive,
           along with some CVS special stuff.
BlueChip:  OK

LinusN:    Each directory also has it's own private CVS directory
           You will see this in a minute after we do our first download.
BlueChip:  OK - Are they important?
LinusN:    Yes, very important.  But you will never need to look inside them.
           They are only there so the CVS program can keep track of your edits
           for you.

           --- DIFF'S ---

LinusN:    While you do this little exercise, remember: Everything in CVS is
           about diffs
BlueChip:  What are "diffs"?
LinusN:    A diff is file which lists all the differences between your source
           code and the source code in the respoitory.
           It means that when you get the latest Rockbox code, all of you edits
           will be _automatically_ Merged (applied) into the latest code as it
           downloads.
BlueChip:  That'll save me a few hours :)

           --- HANDS ON EXPERIENCE ---

LinusN:    Let's get some hands-on experience...
BlueChip:  Go

[BlueChip] ** Starts Devkit 3.0

LinusN:    What is in your home directory?

[BlueChip] ** ~>ls

BlueChip:  One daily tarball, one patch, and a single dir of that tarball with
           the patch applied.
LinusN:    OK - Let's start with Checking Out the "rockbox" module
           This will create a directory with the same name as the module,
           in this case "rockbox"
BlueChip:  OK - Where is it standard to keep this directory?  (on my machine)
LinusN:    It's OK to have it anywhere; I have it in my home directory

[Bluechip] ** Continues to sit contently in his home directory

BlueChip:  Will the directory name ALWAYS be the same as the package?
LinusN:    Yes

           --- DOWNLOADING YOUR FIRST CODE ---

LinusN:
    Type: cvs -d:pserver:anonymous@rockbox.haxx.se:/cvsroot/rockbox co rockbox

[Bluechip]
    ** ~>cvs -d:pserver:anonymous@rockbox.haxx.se:/cvsroot/rockbox co rockbox
    ** Sits and waits for the source code to finish downloading...

BlueChip:  Done

           --- MAKING YOUR FIRST EDIT ---

LinusN:    OK - Open apps/main.c in your favourite editor

[BlueChip] ** Opnes DEVKIT/home/guest/rockbox/apps/main.c  with  UltraEdit

BlueChip:  Done
LinusN:    Remove the line  "sleep(HZ/2);"  from the  init()  function
           ...and save the file
BlueChip:  Done

LinusN:    OK - Now Type: cd rockbox
           And Then: cvs diff -u apps/main.c

[BlueChip] ** ~>cd rockbox
           ** ~/rockbox>cvs diff -u apps/main.c
           ** Lots and lots of edits shoot up the screen :(

           --- CLEANING UP MISTAKES ---

BlueChip:  Whoops - My editor has trimmed all the Trailing Spaces from the
           lines of code in  main.c  and I have got a list with lots of
           apparently "null" changes
LinusN:    Naughty editor
BlueChip:  LOL - They'll add "ignore trailing whitespace" to diff one day :D

BlueChip:  Should I redo the edit, or continue with a _big_ diff
LinusN:    Let's continue...
BlueChip:  OK - I presume it is easy to replace that file from CVS?
LinusN:    Let's do that...
BlueChip:  Cool

LinusN:    Delete the file

[BlueChip] ** ~/rockbox>cd apps
           ** ~/rockbox/apps>rm main.c

BlueChip:  Done

           --- UPDATING FROM CVS ---

LinusN:    Type: cvs up -dP
           "up" is short for "update"
BlueChip:  Which directory should I be in when I do the update?
LinusN:    As long as you are in or above the  apps/  dir,
           and in or below the  rockbox/  directory, you're fine.

[BlueChip] ** ~/rockbox/apps>cvs up -dP
           ** Waits for update to finish...

           --- CVSPASS ---

BlueChip:  Great, except I see and error about "missing file: .cvspass"
LinusN:    That's easy :)
           Type: touch ~/.cvspass
           ...to create a blank file

[BlueChip] ** ~/rockbox/apps>touch ~/.cvspass
           ** ~/rockbox/apps>ls ~
           ** Notes the new .cvspass file

[BlueChip] ** Repeats the last exercise to see if the error is now gone:

           ** ~/rockbox/apps>rm main.c
           ** ~/rockbox/apps>cvs up -dP
           ** Update finishes with no errors

BlueChip:  Great - Error gone :)

           --- UPDATE NOTIFICATION ---

LinusN:    OK - Did you notice the "U" before the file name in the CVS output?
BlueChip:  Yes.  Does that have a specific meaning?
LinusN:    "U" == "Updated"
BlueChip:  Right.  I must say the output seemed quite clear that it had noticed
           the missing main.c and replaced it for me.

LinusN:    OK.  Now you have a replacement copy of the original main.c back.
           Edit the file again (remove "sleep(HZ/2);")
           And remember to disable "Strip Trailing Spaces" before you save ;)

[BlueChip] ** Edits the file again.

BlueChip:  Done

           --- MERGING FROM CVS ---

LinusN:    Now do the update again

[BlueChip] ** ~/rockbox/apps>cvs up -dP

LinusN:    Notice the "M" in front of the file name
BlueChip:  Yes
LinusN:    "M" == "Merged"
           And this is the beauty of CVS
           The Update procedure Merges your files with the Rockbox.haxx.se
           Repository  ...or "patches" if you like
           Your changes are always intact

           --- HOW DOES UPDATE WORK ---

BlueChip:  How does CVS know that MY file is lacking a line, rather than the
           Repository having gained a line recently.
LinusN:    You've probably noticed all those CVS directories everywhere by now?
BlueChip:  Yes, one in every directory.
LinusN:    They track which version of the file was last downloaded to your
           hard drive.  In this case, apps/CVS/Entries 1.86

[BlueChip] ** Opens DEVKIT/home/guest/rockbox/apps/CVS/Entries.
           ** and observes the line: /main.c/1.86/Fri May 21 21:49:04 2004//

BlueChip:  Right, that makes sense

BlueChip:  So it sees that my file is different from the Respository
LinusN:    Yes, and your edits have precedence :)

LinusN:    What it does is that it creates a "patch" based on the differences
           between the file version you have edited on your machine, and the
           version of the same file in the Rockbox CVS Repository
           ...Then it applies that patch on your file

           --- UPDATE CONFLICTS ---

LinusN:    Now if someone has changed exactly that line and committed that
           change, there will be a Conflict.
           If there is a Conflict during an update it will warn you by
           displaying:
           "C" == "Conflict"  next to the file as it downloads.

BlueChip:  Ok - U=Updated, M=Merged, C=Conflict

BlueChip:  If there is a Conflict, will my code still compile?
LinusN:    No.  The CVS Update procedure puts markers in the file, to highlight
           the prcise location of the Conflict.  It's something like:
             <<<< 1.86
             bla bla
             ---- main.c
             blo blo
             >>>>>
           ...and you have to manually select which part you want.
BlueChip:  Cool - So it will throw nice compiler errors if I miss the conflict
           during the Update procedure?
LinusN:    Yes.

           --- OVERVIEW / RECAP ---

LinusN:    And that is basically it. The "Update" procedure patches your
           local Repository with the latest changes from the Repository on the
           Rockbox.haxx.se server.
           So you can happily edit your files, and do an "Update" every once in
           a while to keep up with the latest core updates.

           --- YOUR SECOND EDIT ---

LinusN:    Let's edit another file, apps/tree.c
BlueChip:  OK
LinusN:    Remove line 76 with the ".mpa" file type on it.

[BlueChip] ** Opens DEVKIT/home/guest/rockbox/apps/tree.c
           ** and removes line 76.

BlueChip:  Done
LinusN:    Go to the "rockbox" dir

[BlueChip] ** ~/rockbox/apps>cd ..
           ** ~/rockbox>

BlueChip:  Yep

           --- CREATING A PATCH ---

LinusN:    Let's create a patch...
LinusN:    Type: cvs diff -u
BlueChip:  (aha.  This is the stuff - A standardised patch :) )

[BlueChip] ** ~/rockbox>cvs diff -u

LinusN:    You should see both changes (main.c and tree.c)
BlueChip:  Yes

LinusN:    This time Type: cvs diff -u > mypatch.pat

[BlueChip] ** ~/rockbox>cvs diff -u > mypatch.pat

LinusN:    *bing*
           There you have it, an up to date patch for your changes :)

           --- PATCH FILE FORMAT ---

[BlueChip] ** Opens DEVKIT/home/guest/rockbox/mypatch.pat
           ** and glances through it

BlueChip:  Unusual looking patch - Will that apply okay with patch.exe ?
LinusN:    Yes, it will work with the standard "patch" util
           In what way is the file "unusual"?
BlueChip:  It is just different from those I have made in the past.
           This one has all the filenames underlined with "="s
           and also has "? mypatch.pat" as the first line
           It just makes the file look quite different ...more readable :)
LinusN:    It actually ignores lots of that info.
           There are a few different formats for patches
           This is the "Unified" patch format

           --- REVERTING BACK TO CVS SOURCE CODE ---

LinusN:    OK - Remove main.c and tree.c and update again

[BlueChip] ** ~/rockbox>rm apps/main.c
           ** ~/rockbox>rm apps/tree.c
           ** ~/rockbox>cvs up -dP
           ** Notices the following on the screen:
           **   ? mypatch.pat
           **   U main.c
           **   U tree.c

BlueChip:  Well, that all seems pretty straight forward :)
           ...Is that it, or are there more surprises in store?

           --- APPLYING YOUR PATCH ---

LinusN:    The last thing to try is applying your patch.
           We JUST Updated  main.c  and  tree.c  back to their CVS state.
BlueChip:  Yes
LinusN:    And you still have your patch file in the  rockbox/  directory?
BlueChip:  Yes

LinusN:    Type: patch -p0 < mypatch.pat
           ...and your two changes are back!

[BlueChip] ** ~/rockbox>patch -p0 < mypatch.pat
           ** Checks  main.c  and  tree.c  and notes the edits are back again

BlueChip:  Fantastic! :)

           --- DOWNLOADING EXTRA PACKAGES ---

LinusN:    You may have noticed, the "uisimulator" module is NOT part of the
           "rockbox" module  ...So, in the "rockbox" dir:
           Type: cvs co uisimulator

[BlueChip] ** ~/rockbox>cvs co uisimulator
           ** Waits for it to finish

BlueChip:  Great! :)
LinusN:    And That's basically it

           --- THAT'S ALL FOLKS ---

BlueChip:  Cool.
           Linus, I owe you a large beer for that help
           I have wasted hours trying to suss that in the past
           I will play for a bit and write up our conversation as an edited
           transcript.
LinusN:    Glad to help
BlueChip:  Thank You
LinusN:    [IDC]Dragon: you're next :-)
BlueChip:  *Goes off to play with his new knowledge...



rockbox.haxx.se Package List
============================

NOTE: This package list is now outdated, but no corrected list has been posted
      anywhere that I know of.

Here is a complete list of the available modules:

    apps          - Source code for the applications
    firmware      - Source code for the firmware library
    fonts         - Rockbox fonts
    gdb           - The gdb stub to use for remote debugging
    tools         - Tools for building the firmware
    uisimulator   - A user interface simulator for X11 & Win32
    docs          - Project documentation
    www           - Rockbox web page

The following are aliases that get several modules at once:

    rockbox       - Everything you need to compile and build Rockbox for target
    rockbox-devel - Like 'Rockbox' and also includes simulators and gdb code
    rockbox-all   - Everything there is in CVS, all modules
    website       - The www and docs modules


Summary
=======


1. Get all the source code you need
   """"""""""""""""""""""""""""""""

   ~>cvs -d:pserver:anonymous@rockbox.haxx.se:/cvsroot/rockbox co rockbox-devel

   iRiver developers may also require the bootloader files:

   ~/rockbox-devel>cvs co bootloader


2. Update periodically
   """""""""""""""""""

   ~/rockbox-devel>cvs up -dP


3. Make Patches of Your Work For Others
   """"""""""""""""""""""""""""""""""""

   ~/rockbox-devel>cvs diff -u > mypatch.pat


4. Apply A Standard Patch
   """"""""""""""""""""""

   ~/rockbox-devel>patch -p0 < mypatch.pat

   NOTE: There a dozens of ways to make a "legal" patch.

         The patch command here is correct if the patch was made using the
         method outlined in the previous section.

         If your attempt to patch fails with file-not-found errors, try
         changing the -p value to -p1, -p2 or -p3

         If you still cannot patch, email the patch author who should reply
         with something like:
         "Place my patch file in {this} directory and use patch -p{X}"


Firewall Information
====================

CVS retrieves source code from the Rockbox central server.  As such it needs
internet access.

If you are running a firewall you may need to add some new rules to allow CVS
to access the internet.  I have listed two rules here, depending on the setup
of your machine you may not need to explicitly add the second one.

# For  /DEVKIT/usr/bin/cvs.exe  Allow:
  # Outgoing TCP on port 2401
  # Outgoing UDP to localhost [127.0.0.1]