From: "Erwin S. Andreasen" <erwin@pip.dknet.dk>
To: MERC/Envy Mailing List <merc-l@webnexus.com>
Subject: Using RCS for MUD development
Here's a small introduction to using RCS in mud development I've written.
You can include it in your server's doc/ directory if you want. Comments?
Using RCS for MUD development
==========================================
By Erwin S. Andreasen <erwin@pip.dknet.dk>
RCS, Revision Control System, is a very handy tool that can help you track
all changes you have made to your MUD - and make development by several
people much easier.
RCS is available for almost all UNIX systems. See near end of this document
for information about availability.
The setup I describe assumes following: you have a MUD server running
somewhere else in the world, possibly far away. You, and each of your
developers posses a machine at home running Linux or other flavor of Unix:
developing on this machine is much faster than developing on the machine
that runs the actual MUD.
To ease things, I have added entries to my Makefile that run the RCS
commands; these entries are shown and explained at the end of this document.
To start using RCS, you have to check in the source files. Create an RCS
directory (named just that, RCS) in the directory with your source files,
then run 'make checkin'. For each file, describe it shortly: press . on an
empty line to move to the next file.
The current version of your source files is now saved by RCS. You should now
go on and change things, compiling and testing as necessary. You can go back
to the checked in version of any file and review changes made since the
check in.
After you finished, you are ready to upload a diff file to you main server.
This file consists of changes only and is not very large. Run 'make diff' to
create this patch: the file created is named 'diff.new' and is then
compressed with gzip to 'diff.new.gz' to make it even smaller, saving
transfer time.
You should then check in the changes you have made into the RCS repository,
by running 'make checkin' again. Next time you type 'make diff', the diff
file will be created containing differences from the source file as they
were at the time you typed 'make checkin'.
Now you can upload the rather small patch to your main server. This too can
be automated, just run 'make ftp'. This assumes you have the ncftp program.
On the remote server, run 'make patch'. This uncompresses the patch and
applies it, using the program 'patch'. Make sure there are no .rej files: if
there are, something went wrong, and you probably need to upload the files
that were patched incorrectly manually. This happens if you edited the file
directly on the remote site.
When the patch has been applied, recompile. If you changed any global
structures, make a clean recompile ('make clean'): if you are unsure, do it
anyway.
If you find it you have to add a new file, you will have to upload the first
version yourself. After you do a 'make checkin', future changes will appear
in the diff file.
OTHER DEVELOPERS
================
You can use RCS to easily coordinate several coders working on the same
source. Simply, make them take the same steps as you: create a patch, but
then mail it to you. You'll have to apply the patch, and then make sure that
there were no .rej files: If there were, you will have to apply the changes
by hand. The 'patch' / 'diff' programs are however smart enough so that even
though you changed one part of the file that your other developer was
changing as well, the changes can be merged.
The .rej files contain a number of "chunks". For each chunk there are lines
marked with -, which means the line has been deleted, +, which means it has
been added, and !, which means it has been changed. Lines not marked with
those symbols are included for reference: this is how 'patch' finds out
where the changes belong, even though the line numbers are not correct.
After you have merged the changes into your source, continue as if you have
made the changes yourself: test everything then when you are secure all
things are in order, 'make diff' to create a new diff file, 'make checkin'
then ftp the file to your main site and apply it.
A setting like this lets you retain full control over the code and lets
several people work on it easily: almost everyone has access to a PC and can
install Linux on it.
You should from time send your coders the master copy of your MUD, this
ensure everyone has the same version. How often this needs to be done
depends: I usually do that every 2-3 weeks, with perhaps 500 new lines of
code going in each week.
PREVIOUS VERSIONS
=================
If you in the middle of working on a new version accidentally delete your
current version of a file or find that you must for some reason start over,
you can retrieve a previous version of a file. Simply, 'co -l file.c' to
retrieve the version of file.c as it was when you last time did a 'make
checkin'.
You can also check out an older version, if you find that some changes you
did and checked in were wrong. Using 'rlog file.c' will show you the current
revision, and which previous revisions are stored. Using 'co -l r1.1 file.c'
will check out version 1.1 of the file.
To see what changes you have made since the last check in on a single file
use rcsdiff: 'rcsdiff -p file.c' will show them. As you will see, this is
what 'make diff' does on all the files. As with 'co', you can use the -r
parameter to specify that you want to compare to an earlier revision.
For more information, see the man pages for rcsintro, ci, co, rcsdiff and
rlog.
MAKEFILE
========
Add the following entries to your Makefile (this assumes you are using GNU
make). Lines starting with # are comments. Leading spaces on a line are TABS
not spaces.
SRC = *.c
# I like to keep my include files in a directory named 'h'
INC = *.h h/*.h
# Check in all files
checkin:
ci -l $(SRC) $(INC)
# Make a unified diff of all files.
diff:
rcsdiff -u $(SRC) $(INC) > diff.new
gzip diff.new
ftp:
scripts/ftp-diff
The scripts/ftp-diff file looks like this:
ncftp ns1 << END
cd ~/mud/src
put ../diff.new.gz
quit
END
You'll have to set up ncftp with an 'ns1' entry that has the correct
username and password. Alternatively, you could use normal ftp and then
create a ~/.netrc file containing something like:
machine ns1.somehost.com
login joe
password bob
Note that the above script only creates a diff of *.c and *.h files. You
could extend it to work on the Makefile and help files as well.
AVAILABILITY
============
RCS, revision control system
source: ftp://sunsite.unc.edu/pub/Linux/devel/ver_cont/rcs-5.7.src.tgz
binary: ftp://sunsite.unc.edu/pub/Linux/devel/ver_cont/rcs-5.7.ELF.tgz
ncftp, an enhanced ftp client
source:
ftp://sunsite.unc.edu/pub/Linux/system/Network/file-transfer/ncftp-2.3.0.tgz
binary:
ftp://sunsite.unc.edu/pub/Linux/system/Network/file-transfer/ncftp-2.3.0-ELF-bin.tar.gz
patch, a program to apply patches created with diff with
source: ftp://sunsite.unc.edu/pub/Linux/devel/patch-2.1.tar.gz
binary: ftp://sunsite.unc.edu/pub/Linux/devel/patch-2.1-bin.tar.gz
OTHER VERSION CONTROL SYSTEMS
=============================
cvs is a version control system that uses RCS for storing the data, but
offers many more possibilities. It is useful if you are actually sharing the
development machine (I think the FreeBSD team uses it for their
development).
Aegis - ?