Breaking Changes: ioquake3 Switching to CMake; Makefile Deprecated

Here’s the quick summary:

Thanks to Tim Angus, ioquake3 now supports CMake! If you want to compile from source for Windows, macOS, or Linux, and you’re already familiar with CMake you can try it out now. We will update our documentation as we can.

If you just wanna play ioquake3 and not compile anything:

You’re good! You can keep reading if you want to hear our reasoning about why we’re making this technical change. Downloads will still be on ioquake3.org and itch.io.

If you develop a mod or game that uses ioquake3:

This is your heads-up!

A proposed timeline to phase out the old Makefile and platform specific build files in favor of CMake.

Our current timeline:

August 12 2025: Warn developers of the deprecation of the Makefile via this post and a warning in the Makefile. Start updating documentation to reflect these changes.

September 6. 2025: delete project files for MSVC/Xcode and assess any feedback we’ve been given on these plans. Make changes.

November 6. 2025: When we’ve met our goals, remove the Makefile from git.

Compiling ioquake3 for your target platform will be easier with CMake and it can even generate a Makefile. You’ll just need to add CMake to your build system and you may want to pay special attention to /cmake/identity.cmake where you can now more easily brand your game. If you run into trouble with migrating your project, please work together to resolve issues on our forums.

There are more technical details you will need to read in this issue here until we have updated our documentation. If you currently depend on the Makefile working please respond in that issue or in the forum thread for this post to let us know what’s up. This is a plan, but it can be flexible if there is a significant barrier to your success.

If you already use CMake, it’ll be up to you to decide if you want to stick with the one you’ve got, or start over from ours.

git clone https://github.com/ioquake/ioq3.git
cd ioq3

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

cmake -S . -B build -G "Visual Studio 17 2022"
cmake --build build --config Release

What’s Make?

Make is a legendary tool that makes up a system to compile software. Since 1976 people have been using Make to assist them with building software that gets more complex over time and mainly for UNIX-based platforms, like Linux. It’s older than I am, but still a durable solution for gathering together the steps for building software into a series of instructions that constitute a Makefile.

What’s CMake?

CMake is a meta-build system from the year 2000. Maybe it’s the new kid compared to Make, but CMake is 25 years old now. This meta-build system can still generate Makefiles, but it can also support creating XCode projects for Apple platforms and Microsoft’s MSVC, and just about any other build system for compiling your code. That’s the benefit of a meta build system, you can write your instructions for the meta-build system once, and it’ll take most of the work out of generating instructions for other build systems.

Why is ioquake3 making this change?

If you’ve ever listened to, or read the Hitchhiker’s Guide to the Galaxy, or watched Star Trek you know all about “universal translators”. Whether it’s the comm badge a character wears on their uniform or a babel fish they stick in their ear, these are tools that let you speak and instantly understand and translate many different languages.

Compiling software for a bunch of different operating systems can be almost as challenging as speaking and understanding a bunch of different languages, unless you’ve got a universal translator.

We’ve been using Make with ioquake3 since the source code to Quake 3 was first released under the GPL in 2005. Originally, the Quake 3 source code’s Makefile (the script that tells the Make system what to do for your project) was only used for UNIX versions of Quake 3.

Every so often someone would generously donate their time to work on Microsoft’s compiler for Windows. Or when someone would help update our XCode project for better macOS support. This would work well for a while.

However, without dedicated experts for these and other platforms, support for XCode and Visual Studio was difficult to maintain. As features got added to ioquake3 and bugs were fixed, these other build systems would break down until someone came along to fix them. To provide pre-compiled downloads we’d internally rely on other tools for adapting our Makefile for compiling builds for Windows and macOS.

Enter CMake, whose developers say the C stands for “cross-platform”. While Make is a build system for UNIX platforms. CMake is a meta-build system for every platform. Instead of writing a Makefile that only works with Make, you create the CMake equivalent of a Makefile; CMakelists.txt. CMake can use CMakeLists.txt to generate a Makefile, or support for almost any other build system including MSVC or XCode and more! Cool! It’s almost like a universal translator, but for build systems!

There are all kinds of challenges when Make is handling more tasks than it was designed for.

You know now that Make wasn’t designed to handle cross-platform support, but when we made modifications to support cross-compiling with Make we ended up adding all kinds of stuff to the Makefile that made it super difficult to work on.

All of the additional work into our Makefile grew it from a cozy organized set of instructions to compile ioquake3 in 2005, into a still pretty organized monster that contains thousands of lines of code. Over three-thousand lines of instructions here in the year 2025! That’s a lot and it was getting more complicated the more people worked on it, if they were even willing to. It’s honestly not fun to work on something as complex as a single Makefile that is this big. How can you be sure you’re not going to break something?

We were asking Make to handle too much within those 3,000 lines. CMake can do a lot more, because it’s built to handle many of our goals for building ioquake3 for multiple platforms. Make doesn’t understand platforms, libraries, and compilers. Every part of dealing with them is handled manually when you’re writing the Makefile. This is fine if you’re not dealing with cross-platform code, but when you add in the esoteric syntax that comes from a build tool from 1976 you’re going to run into trouble once you get to around 3000 lines that are there to handle multiple platforms.

Finally, CMake has been a goal of ours to move to since at least 2014 according to our old TODO/Roadmap. Many of the projects that use ioquake3 as a starting point have already moved to CMake. This is a very important milestone for ioquake3‘s development and will ease development. We still have more to do, the documentation for building ioquake3 needs to be updated for CMake, and there are more things on the TODO list in the issue. Getting CMake into ioquake3 was the biggest first step.

Thanks for reading, if all goes well, we should be following the timeline above. If not, we’ll update you here and in that thread.