I thought I'd write a guide for people who want to get started developing Tremulous and first need to be shown around a little. It would have been helpful to me, perhaps it'll be helpful to someone else. Contributions are welcome.
Note: This guide is for recent SVN. Some experience with software development and the programming language C is also useful.
PrerequisitesThe first thing you need is a development environment, Subversion, and, of course, some source code.
[
Instructions for Mac users]
[
Instructions for Windows users]
(Note to Linux users: Most distros come with the relevant developer tools; if you don't have them installed, utilize your friendly neighborhood package manager. You will need to manually install Subversion from
here.)
The source directoryThe directory with your source code should look something like this:
CC
ChangeLog
configs/
COPYING
cross-make-mingw.sh
GPL
make-macosx-ub.sh
Makefile
misc/
src/
ui/
CC,
COPYING,
GPL: Licensing information. Not useful to newbies.
ChangeLog: A history of Tremulous's evolution from version to version. Again, not useful to newbies.
configs/: Config files required by QVMs and clients built from recent SVN.
cross-make-mingw.sh: A shell script for Mac and Linux users. It builds Windows binaries in addition to the usual ones. (Note: Requires MinGW.)
make-macosx-ub.sh: A shell script for Mac users. This builds the application bundle and a number of binaries.
Makefile: The file that tells the compiler what to compile and where to put the result(s). Don't fiddle around with this unless you know what you're doing.
misc/: Miscellaneous stuff, including the source files for the miniprograms that actually do the QVM compiling. Again, not to be diddled with.
src/: The real meat of the Tremulous code. Juicy! (But not very easy to figure out.)
ui/: Files related to Tremulous's user interface.
The source codesrc/ contains a truckload of source files.
cgame/,
game/, and
ui/ are relevant to their respective QVMs (
cgame.qvm,
game.qvm, and
ui.qvm). I recommend starting with
game/, since almost anyone can write a decent
game.qvm.
BackportingOf course, most of the Tremulous world is still using old code, which is not very compatible with the current code. This is where backporting comes into play. It's what it sounds like: Porting in a backwards direction.
So how do you backport, exactly? Well, the recommend way is to use a premade patch (such as
this one by Avenger; it works like a charm). Which brings us to...
PatchingPatches, put simply, contain the differences between two versions of source code. To patch Tremulous source code,
cd to your source directory and then run
patch -p0 < PATCHFILE (substituting
PATCHFILE for the name of the patch).
So, to backport with Avenger's patch:
1] Download the patch and drop it into your source directory.
2]
cd there.
3]
patch -p0 < compat.patch4] Your code should now be backported.
You can also make your own patches. Run
svn diff > patchname.patch and it should generate one for you.
Mercenaries Guild currently hosts a patch repository. You can browse it
here.
CompilingDrumroll...
If your development environment works properly, you're ready to compile! Just run
make and you should end up with a directory called
build/, containing a subdirectory, containing some build products and a lot of files with extensions like
.d and
.o. Browse around a bit and you'll see some binaries (
.x86,
.ppc, or
.exe) and some QVMs. (Note: Avenger's patch seems to disable all QVMs except
game.qvm).
Using the shell scriptsTo use the shell scripts for more advanced compilation:
1]
cd to your source directory.
2]
./cross-make-mingw.sh or
./make-macosx-ub.shNote to Mac users: For maximum compatibility, install all the SDKs that came with your version of Xcode.
Customizing the build process (This section thanks to Amanieu, benmachine, and David.)Often, you'll want to have the compiler only build a certain item. This is done be creating a text file,
Makefile.local, in your source directory.
BUILD_STANDALONE = 0
BUILD_CLIENT = 0
BUILD_CLIENT_SMP = 0
BUILD_SERVER = 0
BUILD_GAME_SO = 0
BUILD_GAME_QVM = 1
This would configure the build process so only QVMs are compiled. Note:
BUILD_CLIENT_SMP (Symmetric MultiProcessing) only has an effect on Mac OS X.
BUILD_MASTER_SERVER = 0
USE_OPENAL_DLOPEN = 0 # 1 on windows.
USE_CURL = 1
USE_CURL_DLOPEN = 1 # 0 on windows.
USE_CODEC_VORBIS = 0
USE_MUMBLE = 1
USE_VOIP = 1
USE_INTERNAL_SPEEX = 1
USE_LOCAL_HEADERS = 1 # SDL related?
You can also add parameters to
make.
release — The default.
debug — Creates debug builds instead of release builds. This makes debugging with
gdb easier.
clean — Removes all build products.
toolsclean — Removes the mini-compilers that are used to build QVMs. You'll only need to do this if you've been messing around with
src/tools.
distclean — Does
clean, then
toolsclean, then deletes
build/.
dist — Bundles up your source in a
.tar.bz2 archive. Doesn't compile anything.
Where to go from hereTake a look at the source, learn by example. There's plenty of information to be had if you take the time to read through it.
