Created 07 02 2004 Updated 07 05 04

1.  Why did you create this page?
CVSup can be a bit tricky for newbies so I made this page for you
It's also a place to hang my notes


2.  What is CVSup?
CVS is an acronym for Concurrent Version System, an open-source, network-transparent program that allows developers to keep track of different development versions of source code.
CVSup is a software package for distributing and updating collections of files across a network.
CVSup was conceived and developed by John Polstra,
CVSup is a great way to synchronize files over a network
In this page, I'll be outlining the basic mechanisms of CVSup in synchonizing a FreeBSD box


3.  What do I need to do first?
I strongly recommend reading the FreeBSD handbooks CVSup pages and John Polstra CVSup pages
This will give you some good technical background


4.  How can I install the FreeBSD ports and or sources?
You can install the ports and sources files using several methods

I prefer using either CDROM or over the network

FreeBSD has 3 CDROM iso's

version-mini.iso	Everything you need to install FreeBSD.  Packages not on disk but rather you get them over the internet If you have bandwidth, this is a good choice.
version-disc1.iso	Everything you need to install FreeBSD, and as many additional third party packages as would fit on the disc.
version-disc2.iso	A ``live filesystem'', which is used in conjunction with the ``Repair'' facility in sysinstall. A copy of the FreeBSD CVS tree. As many additional third party packages as would fit on the disc.

If you are bandwidth challenged, you can use Disk1 and install the ports and sources from CDROM
Then you can use CVSup to update your ports and source tree

If bandwidth is not an issue, you can use with Disk1 or the mini.iso and choose a minimum install.
Then you can use CVSup to get the ports and source tree

Using the minimum install method has the added benefit of tailoring the ports, source and documentation you get using a refuse file

I'll talk about a refuse file later


5.  How do I install CVSup?
I know of at least 2 CVSup related applications
CVSup-without-gui -   A CVSup command line application
CVSup                     - A CVSup GUI and command line application

You can install these CVSup applications by either compiling them yourself, (source) or a pre-compiled version
I like to download a precompiled version rather than compile at this stage of the game.
This is because your source and ports tree isn't up to date yet
Go to FreeBSD ports and search for CVSup on another machine for simplicity
Download the package you want and SCP it to your FreeBSD box
Now use pkg_add *.tgz
Boom, CVSup is now installed


6.  I've installed CVSup now what?
Now you will need to tell CVSup what you want, where to get it from, where to put it ...
This is all done with a special file called a supfile
This can be a bit tricky

Here is an example of my supfile

*default host=cvsup.ca.FreeBSD.org
*default base=/usr
*default prefix=/usr
*default release=cvs
*default tag=RELENG_4_9
*default delete use-rel-suffix
ports-all tag=.
src-all
doc-all

Supfile entry	What is does
*default host=cvsup.ca.FreeBSD.org	The CVSup server location
*default base=/usr	Specifies the root where CVSup will store information about the collections you have transferred to your system.  A setting of "usr" will generate this information in /usr/sup
*default prefix=/usr	This specifies where to place the requested files
*default release=cvs	Indicates that the server should get its information out of the main FreeBSD CVS repository.
*default tag=RELENG_4_9	The tag= field names a symbolic tag in the repository. There are two kinds of tags, revision tags and branch tags. (The RELENG_4_9 branch will become tag=RELENG_4_9).
*default delete use-rel-suffix	delete gives CVSup permission to delete files. You should always specify this, so that CVSup can keep your source tree fully up-to-date. CVSup is careful to delete only those files for which it is responsible. Any extra files you happen to have will be left strictly alone. use-rel-suffix is ... arcane. If you really want to know about it, see the cvsup(1) manual page. Otherwise, just specify it and do not worry about it.
ports-all tag=.	All the ports.  Usage of only tag=. is required and applies only to the ports collections.
src-all	All the sources
doc-all	All the docs

7.  Ok I've got CVSup installed, my supfile is done, now what?
You can optionally create a file called a refuse file
This file is read by CVSup.
Its purpose is to tell CVSup to refuse cetain parts of the source and ports tree

Here is an example of a refuse file

doc/fr
doc/fr_*
doc/ja
doc/ja_*
ports/chinese
ports/french
ports/german
ports/hebrew
ports/games
ports/math

This will tell CVSup to refuse;
French and Japanese documentation
Chinese, German, German and Hebrew ports
Games and Math ports

The refuse file goes in /base/sup/ where /base was specified in your supfile
In the supfile above, base=/usr
So your refuse file should go into /usr/sup


8.  Ok, I've got CVSup installed, my supfile configured and my optional refuse file ready, now what?
Ok, here we go, I'm assuming your FreeBSD box is connected to the internet
CD to the directory containing your supfile
As root, type this
# cvsup -g -L 2 ./supfile

The -g tells CVSup not to use its GUI. This is automatic if you are not running X11, but otherwise you have to specify it.
The -L 2 tells CVSup to print out the details of all the file updates it is doing.
There are three levels of verbosity, from -L 0 to -L 2.
The default is 0, which means total silence except for error messages.
You may now want to do a coffee/alternate beverage/activity, it will take some time

Configuring CVSup is 99% of the work isnt it !


9.  I'd like to do some advanced CVSup related stuff
Good for you
Akinori MUSHA has written a really amazing FreeBSD port called portupgrade

"Portupgrade is a tool to upgrade installed packages via ports or
packages.  You can upgrade installed packages without having to
reinstall depending or dependent packages.  It can automatically trace
dependency chains up and down upgrading packages recursively."

I'll leave it to you to read, read, read
Have fun

---

If you find an error or wish to comment please let me know.