Building SDL3 Static Library for Ubuntu & WSL (GCC, CMake & Ninja) Сборка статической библиотеки SDL3 для Ubuntu и WSL (GCC, CMake и Ninja)

A guide to compiling SDL3 source code into a static library (libSDL3.a) on Ubuntu (native or via Windows WSL2) for Desktop, GUI, or Headless Server setups using CMake and GCC. Руководство по компиляции исходного кода SDL3 в статическую библиотеку (libSDL3.a) в Ubuntu (нативно или через Windows WSL2) для десктопа, GUI или headless-сервера с помощью CMake и GCC.

If you haven't set up C/C++ development tools on your Ubuntu machine or WSL distribution, follow the Если вы еще не настроили инструменты разработки C/C++ на вашей системе Ubuntu или в дистрибутиве WSL, следуйте инструкции: Ubuntu C/C++ Development Environment Setup Guide Руководство по настройке среды разработки C/C++ на Ubuntu
Windows Setup (WSL2 & Ubuntu): Настройка для пользователей Windows (WSL2 и Ubuntu):

1. If WSL is not installed yet, open CMD or PowerShell as Administrator and install Ubuntu: 1. Если WSL еще не установлен, откройте CMD или PowerShell от имени администратора и установите Ubuntu:

wsl --install -d Ubuntu

2. Launch your Ubuntu distribution from CMD or PowerShell: 2. Запустите дистрибутив Ubuntu из CMD или PowerShell:

wsl -d Ubuntu

Step 1: Install Dependencies Шаг 1: Установка зависимостей

Select your target environment to view the required system packages: Выберите вашу целевую среду для просмотра необходимых системных пакетов:

If you are compiling for a desktop environment or Windows WSL2 with display and audio support, install the development headers required for X11, Wayland, OpenGL/EGL, and audio backends: Если вы выполняете сборку для десктопного окружения или Windows WSL2 с поддержкой видео и аудио, установите заголовочные файлы для X11, Wayland, OpenGL/EGL и аудиосистем:

sudo apt update && sudo apt install -y \
  build-essential cmake ninja-build wget nano \
  libasound2-dev libpulse-dev libaudio-dev \
  libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev \
  libxss-dev libxtst-dev libxxf86vm-dev \
  libwayland-dev libxkbcommon-dev libegl1-mesa-dev libgl1-mesa-dev libgbm-dev libdrm-dev

For a headless server or CI build (e.g. running background workers, test runners, or dedicated game servers), graphics and audio headers are not required. Only essential build tools are needed: Для сборки на headless-сервере или в CI (например, для фоновых сервисов, запуска тестов или выделенных игровых серверов) графические и аудио библиотеки не требуются. Нужны только базовые инструменты сборки:

sudo apt update && sudo apt install -y build-essential cmake ninja-build wget nano

Step 2: Download SDL3 Source Code Шаг 2: Скачивание исходного кода SDL3

Check and download the latest release (3.4.20) directly from the official SDL repository on GitHub: Проверьте и скачайте последнюю версию (3.4.20) напрямую со страницы релизов SDL на GitHub:

Open SDL3 Releases (GitHub) Открыть релизы SDL3 (GitHub) Direct Download SDL3-3.4.20 (.tar.gz) Прямое скачивание SDL3-3.4.20 (.tar.gz)

You can download and extract it directly via wget in the terminal (native Ubuntu terminal or WSL bash): Вы можете скачать и распаковать архив напрямую с помощью wget в терминале (в нативном терминале Ubuntu или в консоли WSL):

cd ~
wget https://github.com/libsdl-org/SDL/releases/download/release-3.4.20/SDL3-3.4.20.tar.gz -O SDL3-3.4.20.tar.gz
tar -xzf SDL3-3.4.20.tar.gz
cd SDL3-3.4.20

Step 3: Create the Build Script Шаг 3: Создание скрипта сборки

In the root directory of the extracted SDL3 source folder, open the nano text editor to create a script named build-ubuntu-static.sh: В корневой директории извлеченного исходного кода SDL3 откройте текстовый редактор nano для создания файла build-ubuntu-static.sh:

nano build-ubuntu-static.sh
How to use nano: Copy the code below, right-click in the terminal to paste it, press Ctrl + O (then Enter) to save, and press Ctrl + X to exit. Как пользоваться nano: Скопируйте код ниже, нажмите правую кнопку мыши в терминале для вставки, нажмите Ctrl + O (затем Enter) для сохранения и Ctrl + X для выхода.

Choose your environment and paste the corresponding script: Выберите вашу среду и вставьте соответствующий скрипт:

#!/usr/bin/env bash
set -e

BUILD_DIR="build-ubuntu-static"

rm -rf "$BUILD_DIR"
mkdir -p "$BUILD_DIR"
cd "$BUILD_DIR"

cmake .. \
  -GNinja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$HOME/libs/sdl3-3.4.20-ubuntu" \
  -DBUILD_SHARED_LIBS=OFF \
  -DSDL_SHARED=OFF \
  -DSDL_STATIC=ON \
  -DSDL_TESTS=OFF \
  -DSDL_EXAMPLES=OFF

cmake --build . --config Release --parallel --target install
#!/usr/bin/env bash
set -e

BUILD_DIR="build-ubuntu-static"

rm -rf "$BUILD_DIR"
mkdir -p "$BUILD_DIR"
cd "$BUILD_DIR"

cmake .. \
  -GNinja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$HOME/libs/sdl3-3.4.20-ubuntu" \
  -DBUILD_SHARED_LIBS=OFF \
  -DSDL_SHARED=OFF \
  -DSDL_STATIC=ON \
  -DSDL_TESTS=OFF \
  -DSDL_EXAMPLES=OFF \
  -DSDL_X11=OFF \
  -DSDL_WAYLAND=OFF \
  -DSDL_OFFSCREEN=ON \
  -DSDL_UNIX_CONSOLE_BUILD=ON

cmake --build . --config Release --parallel --target install
Note: Примечание: Ensure that the path variable CMAKE_INSTALL_PREFIX matches your target installation directory. The SDL_UNIX_CONSOLE_BUILD=ON flag tells CMake that a headless setup without X11 or Wayland is intentional. Убедитесь, что переменная пути CMAKE_INSTALL_PREFIX соответствует целевой директории установки. Флаг SDL_UNIX_CONSOLE_BUILD=ON сообщает CMake, что сборка без X11 или Wayland является намеренной.

Step 4: Run, Compile, and Clean Up Шаг 4: Запуск, сборка и очистка

Grant execution permissions to the script and run it in your terminal: Сделайте скрипт исполняемым и запустите его в терминале:

chmod +x build-ubuntu-static.sh
./build-ubuntu-static.sh

Upon completion, your static library (libSDL3.a) along with header files will be installed in your specified CMAKE_INSTALL_PREFIX directory (e.g. ~/libs/sdl3-3.4.20-ubuntu). После успешного завершения собранная статическая библиотека (libSDL3.a) вместе с заголовочными файлами будет установлена по пути, указанному в CMAKE_INSTALL_PREFIX (например, ~/libs/sdl3-3.4.20-ubuntu).

Once installed, you can safely remove the temporary source directory and the downloaded archive: После установки вы можете безопасно удалить временную директорию с исходным кодом и скачанный архив:

cd ~ && rm -rf ~/SDL3-3.4.20 ~/SDL3-3.4.20.tar.gz

Step 5: Next Steps Шаг 5: Следующие шаги

Now that you have compiled and installed the SDL3 static library, you can integrate it into your C++ projects using CMake: Теперь, когда вы собрали и установили статическую библиотеку SDL3, вы можете интегрировать её в свои C++ проекты с помощью CMake:


Support My Work Поддержать проект

If these tutorials helped you, consider buying me a coffee! Если эти туториалы вам помогли, вы можете поддержать автора.

Sberbank (Russia only) Сбербанк (только для РФ)

Sberbank SBP QR Code

Direct transfer via phone number (Russia only) Перевод по номеру телефона (только для РФ)

+7 (917) 212-29-59

USDT TRC20

USDT TRC20 QR Code

Support via Cryptocurrency Поддержка криптовалютой

TMtY1YifNf6FKvgeFmqKGQR4NStKr3csGp