Compiling Install Guide
Raspberry Pi 4B Update:
Q3lite currently runs on the Raspberry Pi’s legacy Broadcom video driver only. The Pi 4B doesn't support the Broadcom video driver (or the SDL2 RPI driver), so the code will have to be modified to support the Raspberry Pi 4B. This will take some time to implement, so your patience and understanding are appreciated.
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. Q3lite requires a minimum version of SDL2 2.0.9. There's an incompatibility with Q3lite and SDL2 versions 2.0.8 and older.
Although Q3lite currently supports the Broadcom GLES video driver, you can help add support for the open source Mesa driver. Please see the Contributing Guide for details.
Q3lite needs to be compiled/installed with the English language as default. The process will probably fail if attempted under a different language.
- Please make sure that you have all Raspbian updates installed. The compile or installation will fail if you don't have all of the updates. Your Pi will need to be connected to the Internet to install these. Enter the following in a terminal:
sudo apt-get update && sudo apt-get upgrade && sudo apt-get dist-upgrade
- Update the Raspberry Pi's firmware. This step is important; enter the following in a terminal:
sudo rpi-update
- It's time to reboot the Pi.
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 libcurl4-openssl-dev \
fcitx-libs-dev libgbm-dev libsamplerate0-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 to that directory.
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
- Once the compile process is complete you can proceed to the Installation section below to finish the install.
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
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_CURL - use libcurl for http/ftp download support
USE_CURL_DLOPEN - link with libcurl at runtime
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
-
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 forums have information on the modifications necessary to get it to work: https://discourse.ioquake.org/t/what-does-pak0-contain/1097/5
The demo version of Quake3 can be downloaded from ModDB:
http://www.moddb.com/games/quake-iii-arena/downloads/quake-3-demo
I haven't tried this so I don't know if it works. -
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. -
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 Q3lite doesn't start up when launched, 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 get the error message WARNING: could not set the given mode (-2) then you probably need to update the Pi's firmware (step 2 in the Compiling Q3lite section above). Thanks to Raspberry Pi forum user jpwhit for reporting this solution.
There are known incompatibilities with PulseAudio, so if you're having sound crackling or distortion issues try removing the PulseAudio package with sudo apt-get remove pulseaudio. For additional sound fixes and issues see section 2.7 of the Q3lite FAQ.
If you're still having issues make sure that you're using the latest development version of Q3lite by compiling the "dev" branch (the default). 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.
- Which model of Raspberry Pi you're using.
- 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.
It's important to point out that the compile/install script won't work in every possible OS installation. If you've made major changes to the OS then you'll likely need to make manual changes to the installation to get things running. In these cases I would recommend testing on a different SD card with a fresh Raspbian image first, so that you can see where all of the files are installed and how things are set up. If Q3lite is installed under a user other than the "pi" user, then the user needs to be a member of the sudo group. If you're running a desktop environment then the user will also need the ability to call sudo without requiring a password to be typed in, like the "pi" user. See the /etc/sudoers.d/010_pi-nopasswd file for an example of how to set that up.
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 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. Note that these are the same prerequisites as Q3lite, so if you've already installed them then you can skip this step. 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 libcurl4-openssl-dev \
fcitx-libs-dev libgbm-dev libsamplerate0-dev xinput
-
Q3lite requires a minimum version of SDL2 2.0.9 compiled with the configure options shown below. Note that there's an incompatibility with Q3lite and SDL2 versions 2.0.8 and older.
-
Change to the directory you wish to compile in such as
/usr/src.
cd /usr/src
- Download the SDL2 2.0.9 source code and save the file to
/usr/src. Uncompress the SDL2-2.0.9.tar.gz archive so that you have a subdirectory such as/usr/src/SDL2-2.0.9.
sudo tar -xvf SDL2-2.0.9.tar.gz
Change the ownership/group of SDL2 source files to root:root.
sudo chown -R root:root SDL2-2.0.9
Change to that subdirectory.
cd /usr/src/SDL2-2.0.9
- Enter the configure options in a terminal to create settings for the compile. The configure options below pertain to SDL2-2.0.9 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:
sudo ./configure --host=arm-raspberry-linux-gnueabihf \
--enable-alsa \
--disable-alsa-shared \
--disable-pulseaudio \
--disable-esd \
--disable-dummyaudio \
--disable-diskaudio \
--disable-oss \
--disable-video-kmsdrm \
--enable-video-rpi \
--disable-video-x11 \
--disable-video-dummy \
--disable-video-mir \
--disable-video-wayland \
--disable-video-vivante \
--disable-video-vulkan \
--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.9 libraries again.
sudo mv /usr/local/lib/q3lite_bak /usr/local/lib/q3lite