I have granted SVN write access to a select few trusted individuals and wish to post the ground rules here so there is no confusion about what is to be expected.

First we have standardized our commenting and format of files per Jeremy's post so please follow them:
http://www.tbamud.com/content/source-code-documentation-project

To checkout the SVN:
svn checkout http://tbamud.com/svn/circlemud/circlemud tbamud

When ready to make a change to the codebase always do an "svn update" prior to your modifications and to decrease the possibilities of conflicts run an "svn commit """ or "svn commit --file " as soon after as possible. Now any change you make in game be sure to test and then comment the details in the changelog via the in game command "changelog " then copy and paste the same text into a commit or a file to commit. All changes must be described in detail to prevent confusion. I will be checking all changes by looking at the different revisions. i.e. "svn diff -96:97" to see what was done.

If there are any questions don't hesitate to ask. The great part about SVN is we can easily track all changes and revert them if necessary.

If you have already contributed heavily to tbaMUD and desire SVN access please contact me on TBA.

Thanks to Dan Blix for submitting this, it will be in the /doc directory next release. Here until then.

Compiling tbaMUD under BSD
based on UNIX readme for circlemud
by Jeremy Elson
For help, visit http://www.tbamud.com

Compiling tbaMUD is easy using FreeBSD. If you plan on compiling on a
FreeBSD machine, these instructions are for you. If not, check the main
README file to get a list of other operating systems that can be used to
compile and run tbaMUD.

Current versions of tbaMUD use the GNU 'autoconf' package to
automatically determine most of the important characteristics of your
system, so chances are good that tbaMUD will compile correctly on any
UNIX system -- even one that we have never seen before. However, if you
do have problems, please visit http://www.tbamud.com so that we
can try to make tbaMUD work with your system.

1) Download the latest version of tbaMUD. You can always find the
latest version at the following site:

http://www.tbamud.com

2) Unpack the archive. If you have the .tar.gz version, uncompress it
using gzip (GNU unzip) and the tar archiver. (Both of these utilities
can be downloaded from ftp.gnu.ai.mit.edu:/pub/gnu if you don't have
them.) To unpack the archive on a UNIX system, type:

gzip -dc tbaMUD-xxxx.tgz | tar xvf -

3) Configure tbaMUD for your system. tbaMUD must be configured using
the 'configure' program which attempts to guess correct values for
various system-dependent variables used during compilation. It uses
those values to create a 'Makefile' and a header file called 'conf.h'.

From tbaMUD's root directory, type

./configure

If you're using 'csh' on an old version of System V, csh might try to
execute 'configure' itself, giving you a message like "Permission denied"
when you try to run "./configure". If so, type "sh ./configure" instead.

'configure' can take several minutes if you're using a slow computer.

'configure' will attempt to use the 'gcc' compiler if it exists; if not,
it will try 'cc'. If you want to use a different compiler, set the
'CC' environment variable to the name of the compiler you wish to use.

For example, if you want to use the 'xlc' compiler, and your shell is
csh or tcsh:

setenv CC xlc
./configure

Or, if you want to use the 'xlc' compiler, and your shell is sh or bash:

CC=xlc ./configure

This will tell 'configure' to use the 'xlc' compiler instead of 'gcc'.

4) Build the tbaMUD server. This must be done from the 'src' directory.
Type:

cd src; gmake all

This will build tbaMUD proper as well as its 10 or so ancillary
utilities, which can take anywhere from 5 minutes to an hour depending
on the speed of your computer.

Note that in the future, when you need to recompile tbaMUD as you make
changes to the code, it is NOT necessary to run 'configure' again (it
should only be run once, after the first time you unpack tbaMUD from
its .tar file). If you move the source code to a different computer,
you should reconfigure it by deleting the file 'config.cache' and
running 'configure' again.

The first time you try to compile tbaMUD, you will be asked to read the
tbaMUD license. Please read it!

5) Go back to tbaMUD's root directory (by typing "cd ..") and run the
tbaMUD server. The easiest way to do this the first time is
to use the 'autorun' script, which can be run in the background by
typing:

./autorun &

Make sure to do this in tbaMUD's root directory, not the src directory
that you used for the previous step. A file called 'syslog' will start
growing in the same directory that contains tbaMUD's log messages.

If you're using 'csh' on an old version of System V, csh might try to
execute 'autorun' itself, giving you a message like "Permission denied"
when you try to run "./autorun". If so, type "sh ./autorun &" instead.

6) Wait until the line 'No connections. Going to sleep.' appears in the
syslog. This indicates that the server is ready and waiting for
connections. It shouldn't take more than about 30 seconds for the MUD
to reach this state, though performance will vary depending on how fast
your computer is.

If a file appears called 'syslog.CRASH', the MUD has terminated
(probably abnormally). Check the contents of syslog.CRASH to see
what error was encountered.

7) Type 'telnet localhost 4000' to connect. The first person to log in
will be made an implementor (level 34) with all powers.

(write to help@tbamud.com for help)

TBA's sixth release of the codebase formerly known as CircleMUD. Special thanks this release to Jeremy Osborne for his major contributions.

Download here: http://tbamud.com/filebrowser/patches/releases

Full changelog here: http://tbamud.com/files/changelog.txt

As of 3/23/2008 the tbaMUD SVN repository has moved: http://tbamud.com/websvn/

svn checkout http://tbamud.com/svn/circlemud/circlemud tbamud

This will checkout the latest codebase repository to the tbamud directory on your machine. cd tbamud and start making whatever changes you want.

After the initial checkout your codebase will be up to date. But in the future before making any changes you should always update to the latest version by typing:

svn update

This will automatically update your tbamud directory with any changes that have been comitted to the repository (only developers can comitt changes).

Developers: To commit your changes back to the repository:

svn commit -m "comments about what changes you have made."

Other useful stuff:
svn diff - current diff of the repository and your changes
svn diff -r 59:60 - diff between version 59 and 60
svn commit --file tmp - for really verbose changes you can send a file.
svn log - view the comitt changes (what was submitted during comitt).
svn log -r 3:HEAD - view the last 3 comitt comments.

The SVN bible can be found:
http://svnbook.red-bean.com/en/1.4/svn-book.html

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.

If you have any additions, corrections, ideas, or bug reports please stop by the Builder Academy at telnet://tbamud.com:9091 or contact Rumble.

http://www.tbamud.com/files/circlemud_license_faq.txt