freebsd-dev/share/FAQ/ctm.FAQ

# ----------------------------------------------------------------------------
# "THE BEER-WARE LICENSE" (Revision 42):
# <phk@login.dknet.dk> wrote this file.  As long as you retain this notice you
# can do whatever you want with this stuff. If we meet some day, and you think
# this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
# ----------------------------------------------------------------------------
#
# $Id: ctm.FAQ,v 1.5 1995/03/05 23:13:08 roberto Exp $
#

		Obtaining FreeBSD-current sources using CTM.
		============================================

CTM is a method for keeping a remote directory tree in sync with a
central one.  It has been developed for usage with FreeBSD's source
trees, though other people may find it useful for other purposes as
time goes by.  Little, if any, documentation currently exists at this
time on the process of creating deltas so talk to phk@FreeBSD.org for
more information should you wish to use CTM for other things.


Why should I use CTM ?
----------------------
CTM will give you a local copy of the "FreeBSD-current" sources.  If
you are an active developer on FreeBSD, but have lousy or non-existent
TCP/IP connectivity, CTM was made for you.  You will need to transfer
up to four deltas per day (or you can have them arrive in email
automatically), the sizes for which are always kept as small as
possible.  This is typically less than 5K, with the occasional (one in
ten) being 10-50K and every now and then a biggie of 100K+ or more
coming around.

You will also need to make yourself aware of the various caveats in
running "current" sources, and for this it is recommended that you
refer to the relevant FAQ: /usr/share/FAQ/current-policy.FAQ


What do I need to use CTM?
--------------------------

You will need two things: The "ctm" program and the initial deltas to
feed it (to get up to "current" levels).

The ctm program is in the FreeBSD-current tree from version 2.0.0 and
forward (/usr/src/usr.sbin/ctm).  If you are running an older version
of FreeBSD, you can fetch the current ctm sources directly from:

	ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/

The "deltas" you feed ctm can be had two ways, ftp or email.  If you
have general ftp access to the Internet, then the following ftp sites
support access to CTM:

	ftp://freefall.cdrom.com/pub/CTM

Ftp the the relevant directory and fetch the README file, starting
from there.

If you only have access to electronic mail or are otherwise blocked
from using ftp, then you may wish to receive your deltas via email:

Send email to majordomo@freebsd.org to subscribe to the list
"ctm-src-cur" (if you do not know how to subscribe yourself using
majordomo, send a message first containing the word `help' - it will
send you back usage instructions).

When you begin receiving your CTM updates in the mail, you may use the
ctm_rmail program to unpack and apply them with.  You can actually use
the ctm_rmail program directly from a entry in /etc/aliases if you
want.  Check the "ctm_rmail" man page for more details.

NOTE:
-----

No matter what method you use to get the CTM deltas, you should subscribe
to the ctm-announce@freebsd.org mailing list.  In the future this will be
the only place where announcements about the operation of the CTM system
will be posted.  Send an email to majordomo@freebsd.org with a single
line of "subscribe ctm-announce" to get added to the list.


Starting off with CTM for the first time:
-----------------------------------------

Before you can start using CTM deltas, you will need to get a special
"base" delta that provides a starting point for all deltas produced
subsequently to it.

You can recognize a base delta by the 'A' appended to the number
(src-cur.0341A.gz for instance).  As a rule a base delta is produced
every 100 deltas, the next one will be src-cur.0400A.gz.
By the way,  they are large!  25 to 30 Megabytes of gzip'ed data is
common for a base delta.

If you do have the 2.0-RELEASE srcdist, you can instead retreive the
src-cur.0372R20.gz file, it's only 4Mb and it will take you to current
from the 2.0-RELEASE sources.

Once you've picked a base delta to start from, you will also need all 
deltas with higher numbers following it.


Using CTM in your daily life:
-----------------------------

To apply the deltas, simply say

	cd /where/ever/you/want/the/stuff
	ctm -v -v /where/you/store/your/deltas/src-cur.*

CTM understands deltas which have been put through gzip, so you don't
need to gunzip them first, this saves diskspace.

Unless it feels very secure about the entire process, ctm will not
touch your tree.  To check out a delta you can also use the "-c" flag
and CTM won't actually touch your tree, but only check the integrity
of the delta, and see if it would apply cleanly to the tree.

There are other options to ctm as well, look in the sources.

I would also be very happy if somebody could help with the "user
interface" portions, as I have realized that I can't make up my mind
on what options should do what, how and when...

That's really all there is to it.  Everytime you get a new delta, you
run it through ctm.

Don't remove the deltas, if they are hard to download again.  You just
might want to keep them around in case something bad happens.  Even if
you only have floppy disks, consider using "fdwrite" to make a copy.


Plans:
------

Tons of them:

 - Make local modifications to the tree possible.  One way to do it
     could be this:
     When CTM wants to edit the file "foo/bar.c", it would first check
     for the existense of "foo/bar.c#ctm"  If this file exists, the
     delta is applied to it instead.  This way the foo/bar.c file can
     be edited to suit local needs.
 - Make a "restore file(s)" option to ctm, something like:
	ctm -r src/sys/i386/wd.c /here/are/my/deltas/src-cur.*
     would restore wd.c to the current status from the files.
 - Clean up the options to ctm, they became confusing and 
     counter intuitive.

The bad news is that I am very busy, so any help in doing this will be
most welcome.  And don't forget to tell me what you want also...


Misc. stuff:
------------

All the "DES infected" (e.g. export controlled) source is not included.
You will get the "international" version only.  If sufficient interest
appears, we will set up a "sec-cur" sequence too.

If you are a frequent or valuable contributor to FreeBSD, I will be
willing to arrange special services, one option is delivery via ftp or
rcp to a machine closer to you.  You need to have earned this, since
it takes time to do, but I'll be all the more happy to do it for you
then.

There is a sequence of deltas for the ports collection too, but interest
has not been all that high yet.  Tell me if you want an email list for
that too and we'll consider setting it up.

If you have commit priviledges or are similary authorized by the
FreeBSD core team, you can also get access to the CVS repository tree
by the same means.  Contact me (phk@FreeBSD.org) for details.


Thanks!
-------

Bruce Evans, for his pointed pen and invaluable comments.
Soren Schmidt, for patience.
Stephen McKay, wrote ctm_[rs]mail, much appreciated.
Jordan Hubbard, for being so stubborn that I had to make it better.
All the users,  I hope you like it...

Comments ?
----------

email phk@FreeBSD.org


Poul-Henning