By Jeremy Osborne,
PREAMBLE
This article is geared towards coders of tbaMUD. It is specifically directed towards three main classes of coders:
The tbaMUD staff
Experimental coders and tbaMUD administrators who want unofficial, developmental updates to their codebase
Anyone else who might be interested
TOPICS COVERED HERE
What is a revision control system?
What do I need to get started?
How do I download the tbaMUD source code from the Subversion repository?
How do I merge development updates from the tbaMUD code repository into my local copy of the source code?
How do I merge the changes I make on my local tbaMUD source code into the repository?
WHAT IS A REVISION CONTROL SYSTEM?
tbaMUD source code is stored in a
Revision Control System
called
Subversion
.
If you do not know what a revision control system is,
this presentation (in pdf format)
provides a decent intro, plus it talks a bit about Subversion, which is the revision control system that tbaMUD uses. The Wikipedia article (linked in the previous paragraph) is also a good introduction. For those that just want a quick example, think of it like this: (good) revision control systems allow a team of people to make changes to a master copy of a document, all at the same time, on their own systems, without screwing up the master copy, allowing everyone to store their own changes if necessary, allowing people to fix any mistakes that happen, and it doesn't eat up a lot of disk space to keep all these changes around.
Subversion is (arguably) the leading, open source revision control system available today. The video below does a decent job walking through using Subversion on a Windows system:
Also a more useful,
extensive, online user manual
should be bookmarked if you use subversion regularly. The examples are very easy to understand, and are geared towards real world situations.
WHAT DO I NEED TO GET STARTED?
Subversion works as a client/server system. The main code is stored in a (server) Subversion Repository. To effectively access this code, you need a Subversion client on your system.
Windows Users
The Recommended Client is <a href="
tortoisesvn.tigris.org/
">Tortoise SVN.
Cygwin
users who want command line access should download the Subversion package.
Linux and UNIX Users
If you are using Linux or UNIX as your workstation, you most likely already have the Subversion client installed. Just type 'svn --version' to find out. If not, look
here
for a list of Subversion distributions and the source code.
Once you have a Subversion client, you are ready to go.
HOW DO I DOWNLOAD THE tbaMUD SOURCE CODE FROM THE SUBVERSION REPOSITORY?
A brief warning is necessary about using subversion. We will always try to make sure the tbaMUD code compiles and runs, however, be warned that this is our working development copy of the tbaMUD source code. It may contain bugs and be unstable. If you want to ensure a stable, tested release only update your SVN when we complete a numbered release.
That being said....
The link to our source code repository is
tbamud.com/websvn/
If you are new to downloading the source code in this way, make sure you know the following:
~40 MB of diskspace available to download and compile the mainline code (see below for a way to reduce this somewhat). Our code tree contains not just the source code but the 180+ areas (mob, world, shop, trigger, obj and zone files) that we deliver, too. Currently we do not offer a tbaMUD-mini for download, and while this is a good idea, we do not currently have plans to offer one in the future.
Choose whether or not you want to be able to be able to retrieve ongoing updates to your copy of our development code (see 'Standard Checkout Instructions' below) or if you just want a one-off (see 'Export Instructions' below).
Standard Checkout Instructions
In Subversion terminology, a code 'checkout' is simply a method to retrieve a copy of some revision of code within a Subversion repository and retrieve enough additional information to be able to track changes made to the local copy of your code as well as receive code updates if you want them. The term 'checkout' is just standard vocabulary for revision control systems. Don't worry, if you check something out, we don't know that what you checked out nor any changes that you make to the local copies of the files. Anything you do with your local copy, up to and including deleting them, will do nothing to the files in the repository. (A later section will be geared towards tbaMUD developers wishing to 'check in' source code and patches which do change the repository.)
Checking out the source code from the command line
To checkout a local copy of the source code, run the following command:
svn checkout
tbamud.com/svn/circlemud
tbamud
This will retrieve the current version of the tbaMUD source code into a directory on your local system called 'tbamud'. Once the files are downloaded, you are ready to roll with a configure and a compile.
Checking out the source code with Tortoise SVN
If you are using Tortoise SVN on windows, things are just about as easy as the command line.
Create a new directory somewhere on your system. Name it whatever you would like to name it, although we'll assume you call it 'tbamud'.
Right click on the directory. You should see an entry in the context menu called 'SVN Checkout'. Click on it.
A window will pop up. In the text box below 'URL of Repository' type in 'svn://link.to.tbamudsrc/' without the single quotes.
The 'Checkout Directory' should be the folder you clicked on.
Click the 'OK' button.
In a matter of moments (depending on your connection speed), you will have a local copy of the tbaMUD development source.
Export Instructions
If you do (or have ever done) a standard code checkout from a Subversion repository, you probably noticed that every directory contains a folder named '.svn'. This .svn folder contains administrative information about the files that you downloaded, which includes an untouched copy of each file (should you ever need to 'revert' changes that you have made even when not connected to the internet). The information in the .svn directories is really only useful if:
You already know you wish to download updates from the repository as other coders make them.
You are a developer and will be checking in changes to your source code.
If you really do just want a one off copy of the source code, you should 'export' a copy.
Exporting a copy of the source code from the command line
To export a local copy of the source code from the repository to your computer, run the following command:
svn export
tbamud.com/svn/circlemud
tbamud
This will retrieve the current version of the tbaMUD source code into a directory on your local system called 'tbamud'. This will be a clean copy of the development code, without any Subversion administrative files. Once the files are downloaded, you are ready to roll with a configure and a compile.
Exporting a copy of the source code with Tortoise SVN
If you are using Tortoise SVN on windows, things are just about as easy as the command line.
Create a new directory somewhere on your system. Name it whatever you would like to name it, although we'll assume you call it 'tbamud'.
Right click on the directory. You should see an entry in the context menu called 'Tortoise SVN'. Highlight it.
A sub-context menu will appear. 'Export' should be available. Click on it.
A window will pop up. In the text box below 'URL of Repository' type in 'svn://link.to.tbamudsrc/' without the single quotes.
The 'Export Directory' should be the folder you clicked on.
Click the 'OK' button.
In a matter of moments (depending on your connection speed), you will have a local copy of the tbaMUD development source sans any administrative '.svn' folders.
HOW DO I MERGE DEVELOPMENT UPDATES FROM THE tbaMUD CODE REPOSITORY INTO MY LOCAL COPY OF THE SOURCE CODE?
NOTE: This section is a bit simplified. In Wikipedia terms, it would be considered a 'stub.'
The reason most people are willing to pull down development code is for the opportunity to continually merge changes into their local as they are made by the tbaMUD developers. To do this, you must 'checkout' a copy of the tbaMUD source code. Please see the above section if you need help in checking out the source code.
Once you have a working copy of the source code, go ahead and run it like you would any mud. Every now and then when you want to update your local source code, do one of the following.
Checking if it is time to get an update to the source code from the command line
Move into the root directory of your source code. From there, run the following command:
svn update
Any file that receives an update will be listed. All files will be preceded by a letter. If a 'C' precedes any file, than there is a file conflict and the merge was unsuccessful. You will have to perform the merge yourself.
NOTE: This is a very simplified version of how to update your local files. In reality, you will probably want to make use of the 'svn diff' and 'svn log' functionality.
Checking if it is time to get an update to the source code from Tortoise SVN
Find the root folder of the local copy of your mud.
Right click on the folder.
In the context menu, click 'SVN Update'.
Any file that receives an update will be listed. All files will be preceded by a letter. If a 'C' precedes any file, than there is a file conflict and the merge was unsuccessful. You will have to perform the merge yourself.
NOTE: This is a very simplified version of how to update your local files. In reality, you will probably want to make use of the Diff and Log functionality.
HOW DO I MERGE THE CHANGES I MAKE ON MY LOCAL tbaMUD SOURCE CODE INTO THE REPOSITORY?
The people who most need access to the code repository are the developers on the tbaMUD team. Subversion is really designed to help multi-person teams work on the same codebase and provide each person a way to merge their changes back in.
Prerequisites to gaining full access to developing the tbaMUD source code
The first thing to do would be to contact the tbaMUD team. The best way to do this is to log into The Builder Academy mud (find the current link at
www.tbamud.com
), and speak to the immortals. We will tell you there what is needed to move on.
Check out the source code as discussed previously.
Develop and have fun!
Checking in the changes
Run an 'update' on your code. This will merge any changes someone else made into your code. It will also spot any potential conflicts and allow you to resolve them.
Run a 'commit' on your code.
Please leave a detailed log message about why you made this commit. It doesn't have to be long, but should sum up why you made the commit. The log message is not for you, it is for others who might need to review the commit at a later date.
It's that simple and is not (usually) very complicated.
A few practices to keep in mind:
Always do a 'make clean; make' on your source code before committing to make sure nothing is obviously broken.
Do not commit binary files (.o, .exe, .pdf, etc.) unless requested to do so by the administrators of tbaMUD. Binary files will bloat the repository.
Always write a descriptive log message when committing files and update tbaMUD's changelog.
Fewer, more modular commits are better (aka. easier to manage and review) than one big, giant commit. Smaller commits are easier to back out if necessary, and they do not require much more disk space than a large commit. If your concern is making a patch file, do not worry. Many different revisions can be rolled into one patch file.
An example of the above: if you are fixing a bug that exists in one file, check in that one file as one commit. If the bug fix spans multiple files, check all of the files in one commit. If the bug fix is large, feel free to check in intermediate, working copies as separate revisions.
For *very* large projects it is probably better to branch the code, work on the branch, and merge the branch back into the mainline code. Branching and merging is a separate topic.
If something gets screwed up, do not panic. Given the way Subversion has been designed, it is virtually impossible to break the repository. For example, subversion never actually deletes a previously committed file. If you do have problems, just ask one of the developers to help you and learn how to use the svn revert to back out mistakes.
Also See: Subversion tutorial by Xiu
