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 contact the ctm-users mailing list for more information and if you wish to use CTM for other things.
CTM will give you a local copy of the FreeBSD source trees. There are a number of “flavors” of the tree available. Whether you wish to track the entire CVS tree or just one of the branches, CTM can provide you the information. If you are an active developer on FreeBSD, but have lousy or non-existent TCP/IP connectivity, or simply wish to have the changes automatically sent to you, CTM was made for you. You will need to obtain up to three deltas per day for the most active branches. However, you should consider having them sent by automatic email. The sizes of the updates are always kept as small as possible. This is typically less than 5K, with an occasional (one in ten) being 10-50K and every now and then a large 100K+ or more coming around.
You will also need to make yourself aware of the various caveats related to working directly from the development sources rather than a pre-packaged release. This is particularly true if you choose the “current” sources. It is recommended that you read Staying current with FreeBSD.
You will need two things: The CTM program, and the initial deltas to feed it (to get up to “current” levels).
The CTM program has been part
of FreeBSD ever since version 2.0 was released, and lives in
/usr/src/usr.sbin/ctm
if you have a copy
of the source available.
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://ftp.FreeBSD.org/pub/FreeBSD/CTM/
or see section mirrors.
FTP the relevant directory and fetch the
README
file, starting from there.
If you wish to get your deltas via email:
Subscribe to one of the CTM distribution lists. ctm-src-cur supports the entire Subversion tree. ctm-src-cur supports the head of the development branch. ctm-src-9 supports the 9.X release branch, etc.. (If you do not know how to subscribe yourself to a list, click on the list name above or go to http://lists.FreeBSD.org/mailman/listinfo and click on the list that you wish to subscribe to. The list page should contain all of the necessary subscription instructions.)
When you begin receiving your
CTM updates in the mail, you may
use the ctm_rmail
program to unpack and
apply them. You can actually use the
ctm_rmail
program directly from a entry in
/etc/aliases
if you want to have the
process run in a fully automated fashion. Check the
ctm_rmail
manual page for more
details.
No matter what method you use to get the CTM deltas, you should subscribe to the ctm-announce mailing list. In the future, this will be the only place where announcements concerning the operations of the CTM system will be posted. Click on the list name above and follow the instructions to subscribe to the list.
Before you can start using CTM deltas, you will need to get to a starting point for the deltas produced subsequently to it.
First you should determine what you already have. Everyone can start from an “empty” directory. You must use an initial “Empty” delta to start off your CTM supported tree. At some point it is intended that one of these “started” deltas be distributed on the CD for your convenience, however, this does not currently happen.
Since the trees are many tens of megabytes, you should prefer to start from something already at hand. If you have a -RELEASE CD, you can copy or extract an initial source from it. This will save a significant transfer of data.
You can recognize these “starter” deltas by
the X
appended to the number
(src-cur.3210XEmpty.gz
for instance).
The designation following the X
corresponds
to the origin of your initial “seed”.
Empty
is an empty directory. As a rule a
base transition from Empty
is produced
every 100 deltas. By the way, they are large! 70 to 80
Megabytes of gzip
'd data is common for the
XEmpty
deltas.
Once you have picked a base delta to start from, you will also need all deltas with higher numbers following it.
To apply the deltas, simply say:
#
cd /where/ever/you/want/the/stuff
#
ctm -v -v /where/you/store/your/deltas/src-xxx.*
CTM understands deltas which
have been put through gzip
, so you do not
need to gunzip
them first, this saves disk
space.
Unless it feels very secure about the entire process,
CTM will not touch your tree. To
verify a delta you can also use the -c
flag
and CTM will not actually touch
your tree; it will merely verify the integrity of the delta
and see if it would apply cleanly to your current tree.
There are other options to CTM as well, see the manual pages or look in the sources for more information.
That is really all there is to it. Every time you get a new delta, just run it through CTM to keep your sources up to date.
Do not 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.
As a developer one would like to experiment with and
change files in the source tree.
CTM supports local modifications in
a limited way: before checking for the presence of a file
foo
, it first looks for
foo.ctm
. If this file exists,
CTM will operate on it instead of
foo
.
This behavior gives us a simple way to maintain local
changes: simply copy the files you plan to modify to the
corresponding file names with a .ctm
suffix. Then you can freely hack the code, while
CTM keeps the
.ctm
file up-to-date.
You can determine the list of changes that
CTM will make on your source
repository using the -l
option to
CTM.
This is useful if you would like to keep logs of the changes, pre- or post- process the modified files in any manner, or just are feeling a tad paranoid.
Sometimes you may want to backup all the files that would be changed by a CTM update.
Specifying the -B backup-file
option
causes CTM to backup all files
that would be touched by a given
CTM delta to
backup-file
.
Sometimes you would be interested in restricting the scope of a given CTM update, or may be interested in extracting just a few files from a sequence of deltas.
You can control the list of files that
CTM would operate on by
specifying filtering regular expressions using the
-e
and -x
options.
For example, to extract an up-to-date copy of
lib/libc/Makefile
from your collection
of saved CTM deltas, run the
commands:
#
cd /where/ever/you/want/to/extract/it/
#
ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*
For every file specified in a
CTM delta, the
-e
and -x
options are
applied in the order given on the command line. The file is
processed by CTM only if it is
marked as eligible after all the -e
and
-x
options are applied to it.
Tons of them:
Use some kind of authentication into the CTM system, so as to allow detection of spoofed CTM updates.
Clean up the options to CTM, they became confusing and counter intuitive.
There is a sequence of deltas for the
ports
collection too, but interest has not
been all that high yet.
CTM/FreeBSD is available via anonymous FTP from the following mirror sites. If you choose to obtain CTM via anonymous FTP, please try to use a site near you.
In case of problems, please contact the ctm-users mailing list.
If you did not find a mirror near to you or the mirror is incomplete, try to use a search engine such as alltheweb.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.