This is a short guide (how-to) to help you in building the minimalistic Quake III Arena clone called Q3MIN from its C source files. This is not a tutorial on program building and we assume that you have some experience in compiling programs using the command line and Makefiles. If you do not know what a Makefile is then you should read a couple of tutorials on this matter or ask someone experienced in programming to explain it. This is a vast and intricate topic, so you will probably need some help. :( If you get hopelessly stuck and cannot get local help, you can try to send me a message at the following address:
But please, do not ask how to use the Microsoft Visual C++ and its integrated development environment. We do not use it for building Q3MIN, are not interested in using it and will not answer questions about it.
For each Q3MIN package released (starting with version 0.6.8-1) there is a correspondig ZIP archive that contains the source code of the engine used in that particular release. These archives can be found here. If the release is called 'q3min-vNNN.zip' then the corresponding source archive is called 'q3m-src-vNNN.zip'.
The current development version of the source tree is kept in an SVN repository at the WEB
hosting site 'tuxfamily.org'. You may browse the source code using either
WebSVN or
ViewVC. If you want to check
out (grab a copy of) the current code, under Linux you may do so simply by using its SVN client as
follows: where [path] is the location where you want the SVN client to create the 'q3m' folder. Under Windows
installing, configuring and using an SVN client is a bit more complicated. Sorry, but we cannot deal with
this topic in the present document. You are referred to the relevant tutorials. This section will explain to you how to set up the required development system
and how to build the Q3MIN engine under the Windows operating system. Under Windows the game engine of the 'official' Q3MIN release is built using Msys
and MinGW. Msys is a simulated Unix environment for Windows, it provides a command
shell and several utilities used by the Unix-style software building process. The
compiler is provided by MinGW which is a port of the freely distributable GCC compiler
suit to the Windows environment. While it is possible to build Q3MIN using the Microsoft Visual C++ package, we do
not wish to use such a commercial package in our free project. For this reason we
do not accept contributions that have been developed and tested solely under MSVC.
You are free to use MSVC for development if you wish, but you must test your final
patch under the Msys/MinGW system before submitting. Compiling is done in the 'traditional' Unix way, i.e. from the command line using
the 'make' utility and a 'Makefile' to control the build process. It is also possible
to use some kind of integrated development system (e.g. Dev C++). You can set up such
a system for your own use if you wish but we cannot provide assistance in this. Go to this link and download the
modules you will need. These are: Next install Msys. It is not advisable to install it to the system drive C:. Use another
disk or partition e.g. D: so that in case of a system reinstall Msys/MinGW is not lost.
The installation is quite straightforward, you only have to specify the install path.
There is a post-install script that will run right after installation. Here you have to
answer yes/no to a few simple question. Answer 'yes' to all except when Msys asks if
you have MinGW installed, to that say 'no'. There are three simple changes you should make in the folder structure and configuration
files of Msys before you can use the system. In the following discussion I will use the string
'MSYS' to refer to the install folder of Msys (which could be e.g. 'd:\msys' or whatever). 1. In 'MSYS\home' there will be a folder which have your Windows user name as its name. Change
this name to something simple that does not contain spaces (e.g. your last name). In the
discussion below I will use the string 'YOUR-NAME' to stand for the name of this folder. 2. Copy the text between the horizontal lines below and save it to a file with the name 'fstab'
in the folder 'MSYS\etc'. 3. In the folder 'MSYS\etc' there should be a file called 'profile'. Open it using
a simple text editor (e.g. Notepad, but NOT Word). Somewhere in the middle of this file
there should be a line like this: Replace this line using the text between the two horizontal lines below. Don't forget to replace all occurrences of 'YOUR-NAME' with the correct folder name! Now you can install the MinGW compiler system. There should be a folder called 'mingw' within the
MSYS folder. Install (uncompress, really) the MinGW packages there. At this point you should have a
usable Msys/MinGW system. Note: The MinGW archives are in 'xxx.tar.gz' format (i.e. they were created using
the TAR and GZIP Unix utilities). If you don't have these programs under Windows, the easiest
way to handle these archives is to get the Total Commander file manager which can extract and
copy the files w/o problem. (TC is a very good file manager. It is worth trying anyway IMO.) Compiling Q3MIN requires a few additional files that are not present in the standard
MinGW packages. You have to add these files manually after the installation. This is
the list of required files, they should all go to 'MSYS\mingw\include': We have made a ZIP archive containing the needed files, you can download it
here. Just unzip this
archive in the folder 'MSYS\mingw' and you will have all the needed files at the correct
location. This is fairly simple. If you got the source as a ZIP archive, just unzip it in your
Msys home directory (i.e. 'MSYS\home\YOUR_NAME'). If you got it by SVN checkout, then
you should move the directory tree created by the SVN client to your home directory
(unless it is already there; the recommended procedure is to check out the code
directly to your Msys home directory). In the following discussion I shall refer to
the folder where the Q3MIN source tre is located as 'Q3M-HOME'. Please, first check the file 'config.local' in the root folder of the Q3MIN source code tree.
You may have to set the values of several variables in this file according to your setup and
preferences. See the section on local configuration for
details. Start Msys (it should have an icon on the desktop). A console window opens with a
prompt and a cursor. This is the command line interface for the simulated
Unix shell. If you are unfamiliar with the Unix command line, you should read a
tutorial or the relevant chapter in a Linux book. Anyway, here it goes: 1. Navigate to the folder 'Q3M-HOME' using the 'cd' (change directory) command. 2. Start the build process by using the command 'make'. That's it! If the archive was not corrupted and your Msys/MinGW system is correctly set up,
then within a minute or two you should have your brand new Q3MIN client and dedicated server
programs as well as a new 'pak1.pk3' containing the VM modules. They can be found in the folder
called 'home/YOUR-NAME/q3m/build/release-mingw32-x86'. The names of the client and server are
'q3m.exe' and 'q3mded.exe', respectively. Msys can be shut down by clicking its close button at the upper right corner or typing
the command 'exit'. It is not necessary to shut down Msys when you want to do something
else (editing source files, etc.). Msys is a well-behaved Windows program and will
just sit in the background while you do your other stuff. A typical scenario is that
you edit & save a source file, go to the Msys window, try to compile, get an error, go to
edit the source again, and so on. Building under Linux is somewhat easier than doing it under Win32. If you have a major Linux
installation like Fedora, Debian, Suse or Ubuntu, then there is a good chance that you have
every component necessary for building Q3MIN from the sources. I use a recent installation of
VectorLinux and I can compile Q3MIN 'out of box' without problems. Just 'unzip' the source package to some place (e.g. '/home/YOUR-NAME/src') to which you have
RW access. Of course, if you habitually work as root (like I do) then you can laugh at the silly
concept of file and folder permissions: at least until you wipe your HD clean by accident. ;) But
until then you can use something cool like '/usr/local/src' for development. If you checked out the
source by SVN then move it to the appropriate place (but it is best to check it out directly to the
desired location). That's it, no other preparation is needed. In the following discussion I shall
refer to the folder in which the source tree is located as 'Q3M-HOME'.p>
Please, first check the file 'config.local' in the root folder of the Q3MIN source code tree.
You may have to set the values of several variables in this file according to your setup and
preferences. See the section on local configuration for
details. Navigate to the folder 'Q3M-HOME' and issue the command 'make' from the console (or from a terminal
if you work in a graphical environment like KDE or Gnome). If the source tree is not corrupted, in about
one to two minutes you should have your brand new Q3MIN modules. They can be found in the folder called
'Q3M-HOME/build/release-linux-XXX' where 'XXX' is the architecture string ('i386', 'x86_64' or 'ppc',
depending on your machine). The client and server EXE modules are called 'q3m.XXX' and 'q3mded.XXX' where
'XXX' is the architecture string as described above. You will also find the module 'pak1.pk3' in the same
folder, it contains the VM modules. In the root folder of the installation tree there is a file called 'config.local'. The purpose of this
file is to provide customized local configuration for the build process. The content of the default
version of this file (as distributed in the source archive) is the following: These options control whether the system builds new VM modules ('1') or not ('0') when the engine is compiled.
People who compile the game for their own use (playing or testing) should set the appropriate variable (depending
on whether they build for Windows or Linux) to '1'. When a full release is built, one of the variables should be
'1' depending on which OS is used to build the VM modules. The variable for the other OS should be set to zero. The reason for this arrangement is that the binaries and the VM modules are tied together. When the game runs,
the binaries check the identity of the VM modules (by using a CRC checksum), and the VM modules check if they
are called by the appropriate client or server (i.e. one that was built together with the module). If any of
this checks fail, the game aborts with an error message. These checks depend on using the correct CRC checksum
of the PAK1.PK3 archive that contains the VM modules. For this reason PAK1.PK3 with the VM modules is built first,
then its CRC is computed and is used as data when building the binaries. The binaries also receive a new 8-digit
random number as a unique ID every time the engine is built. In a full release the Win32 and the Linux binaries
both must use the same CRC chekcsum, that's why there are variables to prevent rebuilding the VM modules.
Note: This checking mechanism was added to prevent the idiotic practice of mixing binaries and VM modules
randomly from different game versions or even from different games (like Q3A and Q3MIN). This variable is used by the Win32 build system and should be set to the location of your Msys/MinGW installation.
(For example 'd:\Msys'). It is needed by the 'update.sh' script. These variables can be used to override the default install location of the game which are the following: These variables are used by the 'update' and 'update.sh' scripts. This variable controls whether the OpenAL library is used for sound output. It is set to '1' by default, because
we believe that OpenAL is a better sound system than SDL (DirectSound). There is no harm in setting this to '1'.
If the OpenAL shared library cannot be found on the system where the game is run, the engine automatically reverts
to using the SDL sound module. This variable controls whether the CURL module is included in the engine or not. CURL is a library that provides
functions to access file servers on the net and download material. It is used by the engine when automatic downloads
are enabled and the download is redirected to a separate URL. Best not to disable this. This variable controls whether an in-game voice chat system based on the SPEEX library is built into the engine or
not. In my opinion it is not terribly useful, as identical functionality can be obtained by using a free TeamSpeak
or Ventrilo server. So it is off by default. This variable controls whether the MUMBLE voice chat system is used or not. To be honest, I am not familiar with
this library/module, its relation to SPEEX and the extra functionality it provides. My advice is that you omit this
module (together with the VOIP module above). In the root folder of the install tree of the Q3MIN source there are update scripts for both Linux and Win32. They
are called 'update' (Linux version) and 'update.sh' (Win32/Msys/MinGW version). You should not use these scripts
as stand-alone programs, they will not work (they are intended to be used from within the Makefile). You should use the
command 'make update'. This will copy the new game modules (PAK1.PK3, client, server) to their appropriate locations.
If you don't want to use the default locations for installing new game modules, you can specify another one in
'config.local' as described above.
svn co svn://svn.tuxfamily.org/svnroot/q3min/source/trunk [path]/q3m
Building Q3MIN under Windows
Software requirements
Getting Msys and MinGW
--------------------------------------------------
MSYS\mingw /mingw
MSYS\usr /usr
MSYS\usr\bin /usr/bin
MSYS\usr\lib /usr/lib
MSYS\usr\include /usr/include
MSYS\usr\local /usr/local
MSYS\usr\local\bin /usr/local/bin
MSYS\usr\local\include /usr/local/include
MSYS\usr\local\lib /usr/local/lib
MSYS\usr\local\share /usr/local/share
MSYS\usr\local\man /usr/local/man
MSYS\usr\local\man\man1 /usr/local/man/man1
---------------------------------------------------
export HOME LOGNAME MSYSTEM HISTFILE
----------------------------------------------------
export MSYSTEM HISTFILE
export LOGNAME="YOUR-NAME"
export HOME="/home/YOUR-NAME"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"
export MINGDIR="/mingw"
-----------------------------------------------------
ddraw.h
dinput.h
dls1.h
dmdls.h
dmerror.h
dmksctrl.h
dmplugin.h
dmusbuff.h
dmusicc.h
dmusicf.h
dmusici.h
dmusics.h
dsound.h
Preparing the source tree
Bulding Q3MIN
Building Q3MIN under Linux
Preparing the source tree
Building Q3MIN
Custom configuration of the build process
# PAK creation flag for Windows builds
BUILD_WIN32_VM = 1
# PAK creation flag for Linux builds
BUILD_LINUX_VM = 1
# Path of Msys install folder (for Win32/MinGW)
MSYS_HOME =
# Windows install directory (overrides default)
WIN32_INSTALL_DIR =
# Linux install directory (overrides default)
LINUX_INSTALL_DIR =
# Add OpenAL support
USE_OPENAL = 1
# Add Vorbis support
USE_CODEC_VORBIS = 1
# Use VOIP
USE_CURL = 1
# Use VOIP
USE_VOIP = 0
# Use the Mumble voice chat system
USE_MUMBLE = 0
BUILD_WIN32_VM
BUILD_LINUX_VM
LINUX_INSTALL_DIR
Win32: c:\Program Files\q3min
Linux: /usr/local/games/q3min
Updating the game modules after a build