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]
|