From: "Erwin S. Andreasen" To: MERC/Envy Mailing List 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 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 - ?