Skip to content

Linux

Linux Developer Environment Setup

Pull Submodules

git submodule update --init --recursive

For Debian/Ubuntu based distros:

sudo apt install g++ make libx11-dev libasound2-dev libpulse-dev libcurl4 cmake pkg-config libssl-dev

For the VideoPlayer addon (FFmpeg-backed video playback):

sudo apt install libavformat-dev libavcodec-dev libavutil-dev libswscale-dev libswresample-dev

For Arch-based distributions:

sudo pacman -S gcc make libx11 alsa-lib libpulse curl cmake pkgconf openssl

For the VideoPlayer addon (FFmpeg-backed video playback):

sudo pacman -S ffmpeg

Note: arch users may get a dependency error when attempting to install alsa-lib, in this case try to install lib32-alsa-lib. Note: libcurl4/curl is optional but required for the auto-update feature in the editor. Note: libpulse/libpulse-dev is required for streaming audio (used by the engine's AUD_*Stream* API and the VideoPlayer addon). Without it, video plays silently. Note: FFmpeg dev packages are only required if you build a project that uses the VideoPlayer addon. The engine itself does not depend on them. Note: On Ubuntu 24.04+, the ALSA runtime library was renamed from libasound2 to libasound2t64 as part of the time_t 64-bit transition. The -dev package above (libasound2-dev) still works for building — apt resolves it transparently — but if you ship a built binary, end-user install lines that named libasound2 directly will fail with "Package 'libasound2' has no installation candidate". Use libasound2t64 in runtime install instructions on 24.04+.

Installing Dependencies

Install Vulkan SDK version 1.4.350.0:

  • Download the 1.4.350.0 tar file from https://vulkan.lunarg.com/sdk/home#linux
  • Extract the tar file somewhere (e.g. ~/VulkanSDK/)
  • Add these to your ~/.bashrc file (replace ~/VulkanSDK with the directory where you extracted the files to).

export VULKAN_SDK=~/VulkanSDK/1.4.350.0/x86_64 export PATH=$VULKAN_SDK/bin:$PATH export LD_LIBRARY_PATH=$VULKAN_SDK/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} export VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d - Close and reopen your terminal to apply the .bashrc (or run source ~/.bashrc) - Run this command in a terminal

sudo apt install libvulkan-dev

Install devkitPro

  1. Install devkitPro Pacman
wget [https://apt.devkitpro.org/install-devkitpro-pacman](https://apt.devkitpro.org/install-devkitpro-pacman) (May 403 fail, if so just download the file manually)
chmod +x ./install-devkitpro-pacman
sudo ./install-devkitpro-pacman
  1. Install Wii/3DS development libraries (Optional) (https://devkitpro.org/wiki/Getting_Started)
  sudo dkp-pacman -S wii-dev 3ds-dev

sudo dkp-pacman-key --recv-keys C8A2759C315CFBC3429CC2E422B803BA8AA3D7CE --keyserver keyserver.ubuntu.com
sudo dkp-pacman-key --lsign-key C8A2759C315CFBC3429CC2E422B803BA8AA3D7CE

  • Put this entry in /opt/devkitpro/pacman/etc/pacman.conf above the [dkp-libs] entry:

    [libogc2-devkitpro] Server = https://packages.libogc2.org/devkitpro/linux/$arch Server = https://packages.extremscorner.org/devkitpro/linux/$arch - Run these sudo dkp-pacman -Syuu sudo dkp-pacman -S gamecube-tools-git libogc2 libogc2-libdvm - Accept overwriting if asked.

Compile Shaders, libgit2, and Standalone embedded-asset stubs

bash Tools/prebuild.sh

This runs three steps: builds libgit2, compiles shaders, and writes minimal stubs for Standalone/Generated/EmbeddedAssets.{h,cpp}, EmbeddedScripts.{h,cpp}, and AddonPlugins.cpp. The stub step only writes files that are missing — these are gitignored and normally regenerated by the Editor's "Build Data" action, but a fresh clone needs the stubs so the Standalone build succeeds. Requires python3 on PATH.

VSCode / GDB Debugging Issues on Ubuntu 24+

Some Linux users may encounter extremely slow debugger startup times, hangs, or failed launches when using cppdbg in Visual Studio Code on newer Ubuntu releases (22.04+ / 24.04+), especially inside containers, XRDP sessions, or remote development environments.

This is commonly caused by GDB attempting to automatically download external debug symbols from Ubuntu's debuginfod servers.

Symptoms may include:

  • Debugger hangs before launch
  • Failed to set controlling terminal: Operation not permitted
  • Very slow startup times
  • cppdbg timing out or freezing
  • GUI applications never appearing

To resolve this issue, disable automatic debuginfod symbol downloading by setting:

"remoteEnv": {
    "DEBUGINFOD_URLS": ""
}

For non-container environments, you can also export the variable globally:

export DEBUGINFOD_URLS=""

or add it to your shell profile:

echo 'export DEBUGINFOD_URLS=""' >> ~/.bashrc
source ~/.bashrc

Additionally, some users may need to force VSCode automation tasks to use Bash:

"terminal.integrated.automationShell.linux": "/bin/bash"

This issue is related to newer Ubuntu debugging environments and is not specific to Polyphase or FAW itself.