tbaMUD Continued development of the CircleMUD core

In upcoming releases of tbaMUD you might notice an increase in source code documentation. If you have Doxygen installed on your system, you will also be able to create a hyper linked, cross referenced manual anytime you wish.

If you haven't used it before, Doxygen is a free, open source program that will read through specially formatted comments in source code, cross link functions, data structures and global variables, and even create intricate call graphs with the Graphviz package (also free and open source).

The Doxygen site explains everything you would need to know about running the program. As a developer of tbaMUD, you don't ever have to install Doxygen or Graphviz, let alone use them, if you don't want to. If you do wish to use them, we have included configuration files that have been altered to work with the function macros found in the source code. All you'll need to do is download and install Doxygen, and Graphviz if you want to create the call graphs.

The source code itself will only look slightly different. The following is a fictitious example showing the formatted comments and keywords you're likely to find in the source.


/**
* @file test.c
* Any comment that begins with a slash-star-star followed by white space
* is the beginning of a comment that can be cross referenced. No other
* special formatting is needed to get the comment recognized. Internal to
* any comment, special keywords can be used. Since this is the file header
* we use the 'at'file keyword followed by the name of the file, in this case
* test.c. Any notes and annotations made inside of the comments are
* included in the generated documentation.
*/


/** Most things can be marked for cross reference */
#include "conf.h"


/** When a comment begins with /** doxygen usually uses it to comment
* whatever immediately follows, in this case the test structure. */
struct test
{
/** Internal elements can be commented either above */
int i; /**< Or immediately following, with the addition of a '<' */
};


/** Functions will use more special keywords, on average, than any other
* piece of code.
* @pre This tag will only be used sometimes. It marks any pre-condition that
* should be met before using this function that is not obvious.
* @post This tag marks any post-condition caused by this function. Often
* the description of the parameters and return value will suffice for the
* post condition.
* @todo This tag may sometimes be included to mark things that should be
* done. The advantage of using this tag is that doxygen will associate this
* tag with the associated function, variable, etc. All todo tags
* will be indexed in a single location in the final documentation.
* @deprecated This tag marks a function or variable that is still in use but is
* currently being phased out. Like the todo tag, the deprecated tag gets
* associated with whatever it is attached to and indexed in its own page.
* @param arg1 There is one param tag for each function parameter. The
* tag is immediately followed by the parameter name, followed by information
* about this parameter.
* @param[in] arg2 If a parameter is specifically designed to pass in a value,
* the param tag might be affixed with [in].
* @param[out] arg3 If a parameter is specifically designed to hold the results
* of a function, it can be be affixed with [out].
* @retval int Used if the function has a return value, the type returned
* follows the tag, and a description of the return value follows that.
*/
int do_nothing(int arg1, int *arg2, int *arg3)
{
return 1;
}


(geared towards coders, new and old)
PREAMBLE
This article will be updated over time. Please check back periodically, or subscribe to the main blog (which is the suggested method) to receive updates.

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 we use here. 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. If you have never heard of Subversion, this blurry youtube video actually does a decent job walking through using Subversion on a Windows system. More useful, this 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 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 WARNING FOR ANYONE RUNNING A NON-EXPERIMENTAL MUD: We will always try to make sure the mainline code compiles and runs, however, be warned that this is our working development copy of the tbaMUD source code. WE TRY TO BE GOOD PEOPLE BUT WE ARE NOT PERFECT AND WE REALLY MEAN THIS AS A WARNING FOR YOUR BENEFIT! IF YOU DOWNLOAD OUR DEVELOPMENTAL, NON-RELEASED CODE AND IT EATS YOUR ENTIRE PLAYER BASE, CAUSES YOUR MUDWORLD TO GO INTO NUCLEAR WINTER, AND PERMANENTLY SETS YOUR IMMORTAL ADMINISTRATORS TO A DRUNKEN STATUS DO NOT EXPECT US TO HELP YOU FIX IT! Yes, that was a bit harsh, but really, please be careful.

That being said....

The link to our source code repository is now located in another article. Look for Rumble's article on where our repository is kept. Sorry for the confusion, but I wanted to cut down on the number of locations where the revision control link was referenced.

If you already know what you are doing, you know what to do from here.

If you are new to downloading the source code in this way, make sure you know the following:

• How to configure and compile the code for your environment. There are numerous documents on this site about how to do this for the many different operating systems that tbaMUD is supported on. We will assume you understand how to do that in this article.
• That you have ~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 svn://link.to.tbamudsrc/ 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 svn://link.to.tbamudsrc/ 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' and will be upgraded as needed.

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?

NOTE: This section is a bit simplified. In Wikipedia terms, it would be considered a 'stub' and will be upgraded as needed.

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

At this point in time, we'll assume you are familiar with the Subversion interface you are using. Checking in changes is quite easy:

• 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 (see here for an explanation).
• Always write a descriptive log message when committing files.
• 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. Chances are if you need to do this, you already know what you are doing. If a general discussion is needed, we will add a how-to branch and merge section.
• 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.