Compiling Install Guide
Q3lite can install SDL2 dynamic libraries during installation, so there's no need to compile or preinstall SDL2. You can also choose to compile SDL2 yourself and tell Q3lite to use the installed libraries. See the section below entitled "Compiling SDL2 From Source Code" for details. Please keep in mind that Q3lite is currently compatible with SDL2-2.0.4 only. Newer versions of SDL2 will have subtle issues due to incompatibilities with the Q3lite OpenGL ES 1.1 renderer.
Although Q3lite currently supports the Broadcom video driver, you can help add support for the open source Mesa driver. Please see the Contributing Guide for details.
- Make sure that you have all Raspbian updates installed. The compile may fail if you don't have all of the updates. Your Pi will need to be connected to the Internet to install these. Enter in a terminal, one line at a time:
sudo apt-get update && sudo apt-get upgrade && sudo apt-get dist-upgrade
sudo rpi-update
sudo reboot
- Verify that you have these prerequisites installed before compiling. Copy and paste all of the text below into a terminal:
sudo apt-get update && sudo apt-get install git libasound2-dev \
libudev-dev libibus-1.0-dev libevdev-dev libdbus-1-dev \
fcitx-libs-dev xinput
- Another reboot is required.
sudo reboot
- Change to the directory you wish to compile in such as
/usr/src.
cd /usr/src
- Clone the Q3lite repository to your local drive with git.
sudo git clone https://github.com/cdev-tux/q3lite.git
- You'll now have a subdirectory
/usr/src/q3lite, change directory to that.
cd /usr/src/q3lite
- The default code branch is the latest code branch
dev. If you wish to compile that branch then proceed to the next step. If you want to compile the stable code branchmaster, then you'll need to change to that branch:
sudo git checkout master
- Run the make-raspberrypi.sh script as root.
sudo ./make-raspberrypi.sh
- When the compile process completes it's time for a little dance. You can proceed to the Installation section below.
The following variables may be set in the make-raspberrypi.sh script to change compile options:
CFLAGS - use this for custom CFLAGS
V - set to show cc command line when building
DEFAULT_BASEDIR - extra path to search for baseq3 and such
BUILD_SERVER - build the 'q3ded' server binary
BUILD_CLIENT - build the 'quake3' client binary
BUILD_BASEGAME - build the 'baseq3' binaries
BUILD_MISSIONPACK - build the 'missionpack' binaries
BUILD_GAME_SO - build the game shared libraries
BUILD_GAME_QVM - build the game qvms
BUILD_STANDALONE - build binaries suited for stand-alone games
BUILD_AUTOUPDATER - build the autoupdater binaries
SERVERBIN - rename 'q3ded' server binary
CLIENTBIN - rename 'quake3' client binary
USE_RENDERER_DLOPEN - build and use the renderer in a library
USE_YACC - use yacc to update code/tools/lcc/lburg/gram.c
BASEGAME - rename 'baseq3'
BASEGAME_CFLAGS - custom CFLAGS for basegame
MISSIONPACK - rename 'missionpack'
MISSIONPACK_CFLAGS - custom CFLAGS for missionpack (default
'-DMISSIONPACK')
USE_OPENAL - use OpenAL where available
USE_OPENAL_DLOPEN - link with OpenAL at runtime
USE_CURL - use libcurl for http/ftp download support
USE_CURL_DLOPEN - link with libcurl at runtime
USE_CODEC_VORBIS - enable Ogg Vorbis support
USE_CODEC_OPUS - enable Ogg Opus support
USE_MUMBLE - enable Mumble support
USE_VOIP - enable built-in VoIP support
USE_INTERNAL_LIBS - build internal libraries instead of dynamically
linking against system libraries; this just sets
the default for USE_INTERNAL_SPEEX etc.
and USE_LOCAL_HEADERS
USE_INTERNAL_SPEEX - build internal speex library instead of dynamically
linking against system libspeex
USE_FREETYPE - enable FreeType support for rendering fonts
USE_INTERNAL_ZLIB - build and link against internal zlib
USE_INTERNAL_JPEG - build and link against internal JPEG library
USE_INTERNAL_OGG - build and link against internal ogg library
USE_INTERNAL_OPUS - build and link against internal opus/opusfile
libraries
USE_LOCAL_HEADERS - use headers local to ioq3 instead of system ones
DEBUG_CFLAGS - C compiler flags to use for building debug version
COPYDIR - the target installation directory
TEMPDIR - specify user defined directory for temp files
Q3LITE_INSTALL_SDL - Have Q3lite install SDL2 dynamic libraries,
eliminating the need to compile or preinstall SDL2
Q3lite uses an interactive installer to automate the installation. The script has been tested with Raspbian Jessie Desktop/Lite as well as Raspbian Stretch Desktop/Lite, and may work with other Linux distributions. The make-raspberrypi.sh script is well commented so it should be straightforward to adapt it to a different OS.
-
Make sure that all of your data is backed up before installing.
-
Q3lite needs 128MB of graphics memory on the Raspberry Pi, so you'll need to set the memory split on that platform. See the Q3lite FAQ for details.
-
Change to the Q3lite source directory, which is
/usr/src/q3litefrom the previous example. In a terminal enter:
cd /usr/src/q3lite
- Run the make-raspberrypi.sh script as root with the install argument.
sudo ./make-raspberrypi.sh install
-
Follow the interactive install script prompts. Your Pi will need to be connected to the Internet if you want the installer to download and install the updated pak files from the Quake3 Point Release. You'll need to agree to the id Software EULA before the updated pak files will be installed.
-
After the install completes it's time for a reboot.
sudo reboot
-
You can launch Q3lite from the applications menu located in the Games section or by right-clicking on the applications menu icon for Q3lite and choosing "Add to desktop" to create a desktop launch icon.
If using Raspbian Lite you can enter at the command prompt:sudo q3lite. To run a timedemo, enter at the command prompt:sudo q3lite timedemo. To run a dedicated server, you can enter:sudo q3lite-ded. -
Don't forget to copy the pak0.pk3 file from your full version of Quake3 (or Steam/GOG version) to:
/usr/local/games/quake3/baseq3.
The pak0.pk3 file from the demo version of Quake3 may or may not work with ioquake3. The ioquake3 wiki has information on the modifications necessary to get it to work: http://wiki.ioquake3.org/Players_Guide#Using_Demo_Data_Files
I haven't tried this so I don't know if it will work. -
If you chose not to download and install the updated pak files during installation, then you'll need to download them and install manually. The pak files can be downloaded from http://ioquake3.org/extras/patch-data/. Place the downloaded files in:
/usr/local/games/quake3/baseq3. -
For additional information such as how to run a background server, see the Q3lite FAQ.
If you experience trouble during the compiling or installation steps that you can't work around, try testing on a different SD card with a fresh Raspbian image. It's possible that other installed packages, drivers or settings are interfering with the compiling/installation. These steps have been tested many times without issues on fresh Raspbian Desktop/Lite installs on Jessie and Stretch. If deviations to the above steps are made then it's likely that issues will arise.
If you launch Q3lite and it doesn't start up, check ~/.q3a/baseq3/crashlog.txt for error messages. A common cause of Q3lite not starting is that the pak0.pk3 file from the original full version of Quake III Arena is missing or corrupt. You can also launch Q3lite from a terminal with sudo q3lite to see additional error messages after the game runs. If you get to a black screen during the game or after it closes, you can return to the desktop by pressing Ctrl+Alt+F1 then Ctrl+Alt+F7. If running Raspbian Lite you can press Ctrl+Alt+F2 then Ctrl+Alt+F1 to get back to tty1. If your keyboard and mouse don't function, simply unplug them for a few seconds and plug them back in. You can then close any error windows on the desktop if it's running. If you have any other issues always check the ~/.q3a/baseq3/crashlog.txt for error messages.
If you're still having issues you may want to try the latest development version of Q3lite. You can check your current Q3lite version number by pulling down the in-game console and verifying the version number in the lower right corner. You can also verify the latest Git commit number by changing to the Q3lite source code directory and entering in a terminal: git log. Also see the Q3lite FAQ to find tips on solving common issues.
If the above steps don't solve your issue please feel free to ask for help in the Q3lite thread on the Raspberry Pi forums. Additionally, you can use the Issues tracker to report the problem. Try to provide as much information about your installation and issue as possible, such as:
- Operating System, Raspbian Desktop or Raspbian Lite, and OS image release date.
- Q3lite version or latest Git commit number (the first seven digits or so are enough to identify the Git commit).
- Whether this is a fresh Raspbian install or not.
- Any major software changes or additions to the OS.
- Try to describe the issue in detail.
- Any other information that you feel is relevant to the problem.
It's difficult to troubleshoot problems remotely, so your patience is greatly appreciated.
Compiling and installing SDL2 isn't necessary unless you wish to try a different version. By default Q3lite installs dynamic SDL2 libraries in /usr/local/lib/q3lite. The Quake3 game binary will look there first to find the SDL2 libraries it requires. If SDL2 libraries are missing or the directory doesn't exist then the Quake3 binary will look in the default system directory /usr/local/lib. This is where SDL2 libraries get installed when you compile them from source code. So if you want Q3lite to use SDL2 libraries that you compile then you can simply rename the /usr/local/lib/q3lite directory to something like /usr/local/lib/q3lite_bak.
sudo mv /usr/local/lib/q3lite /usr/local/lib/q3lite_bak
If you rename or delete the /usr/local/lib/q3lite directory and you haven't compiled SDL2 yet then Q3lite won't run, so be aware of that. Q3lite can reinstall the SDL2 dynamic libraries at any time by running the make-raspberrypi.sh script with the install argument. Change directory to the Q3lite source code directory, which from the previous example is:
cd /usr/src/q3lite
sudo ./make-raspberrypi.sh install
This will recopy the SDL2 dynamic libraries from the source code directory to /usr/local/lib/q3lite if Q3LITE_INSTALL_SDL=1 in the make-raspberrypi.sh script, which is the default. The Q3lite game binary will use these SDL2 libraries instead of the ones in the system directory /usr/local/lib. This comes in handy when you want to run Q3lite with it's compatible SDL2 libraries while having a different SDL2 version installed for other games to use.
Let's Start Compiling
- If you already installed SDL2 by typing
sudo apt-get install libsdl2-devpreviously you'll need to remove it. The SDL2 libraries in the Raspbian repositories won't work with Q3lite. Enter in a terminal, one line at a time:
sudo apt-get remove -y --force-yes libsdl2-dev
sudo apt-get autoremove -y
- Install SDL2 build dependencies if you haven't already. Note that these are the same prerequisites as Q3lite requires with the addition of the "debhelper" package at the end of the list. Copy and paste all of the text below into a terminal:
sudo apt-get update && sudo apt-get install git libasound2-dev \
libudev-dev libibus-1.0-dev libevdev-dev libdbus-1-dev \
fcitx-libs-dev xinput debhelper
-
Q3lite requires SDL2 2.0.4 compiled with the configure options shown below. At this time there's an incompatibility issue with Q3lite and SDL2 version 2.0.5 and newer. You can experiment with other versions of SDL2, however with some versions such as 2.0.5 you won't be able to type text into the Quake3 player console after a single player skirmish, so exercise caution. Some of the compatibility issues are very subtle, so for the time being we'll use 2.0.4 until a solution is found.
-
Change to the directory you wish to compile in such as
/usr/src.
cd /usr/src
- Download the SDL2 2.0.4 source code and save the file to
/usr/src. Uncompress the SDL2-2.0.4.tar.gz archive so that you have a subdirectory such as/usr/src/SDL2-2.0.4.
sudo tar -xvf SDL2-2.0.4.tar.gz
Change the ownership/group of SDL2 source files to root:root.
sudo chown -R root:root SDL2-2.0.4
Change to that subdirectory.
cd /usr/src/SDL2-2.0.4
- Enter the configure options in a terminal to create settings for the compile. The configure options below pertain to SDL2-2.0.4 only, newer versions of SDL2 may require different options to compile correctly. Copy and paste all of the text below into a terminal, then press Enter:
./configure --host=arm-raspberry-linux-gnueabihf \
--enable-alsa \
--disable-alsa-shared \
--disable-pulseaudio \
--disable-esd \
--disable-video-mir \
--disable-video-wayland \
--disable-video-x11 \
--disable-video-vivante \
--disable-video-opengl
- Compile SDL2 using all four processor cores. Omit the -j4 flag if using a processor with one core (Pi 1, Zero or Zero W).
sudo make -j4
- Install SDL2.
sudo make install
- Verify the installed version of SDL2 with:
sdl2-config --version
- You're ready to test your newly compiled version of SDL2. When your done testing you can rename the
/usr/local/lib/q3lite_bakdirectory to it's original name so that Q3lite uses the compatible SDL2-2.0.4 libraries again.
sudo mv /usr/local/lib/q3lite_bak /usr/local/lib/q3lite