Skip to content

Linux

Linux Developer Environment Setup

What to install

Everything not marked optional is required. Polyphase always packages for GameCube, Wii and 3DS, so the devkitPro toolchains are part of the baseline setup, not an extra.

Install Needed for Verify with
Compiler and libraries: g++, make, cmake, pkg-config, X11, ALSA, PulseAudio, curl and OpenSSL dev packages (exact package names per distro below) Everything g++ --version, cmake --version
Vulkan SDK 1.4.350.0 (LunarG) plus the distro libvulkan-dev Editor and every game build, glslc for shaders vulkaninfo --summary prints a device
FFmpeg dev packages (optional) Projects that use the VideoPlayer addon pkg-config --modversion libavformat
devkitPro pacman with wii-dev and 3ds-dev Packaging for Wii, GameCube and 3DS (the devkitPPC and devkitARM compilers) $DEVKITPPC/bin/powerpc-eabi-g++ --version, $DEVKITARM/bin/arm-none-eabi-g++ --version
libogc2, libogc2-libdvm, gamecube-tools-git Packaging for GameCube (its libraries come from libogc2, not the stock libogc) ls /opt/devkitpro/libogc2/lib/cube
rpm / appimagetool (optional) The Linux RPM and AppImage installer targets rpmbuild --version, appimagetool --version
makerom, bannertool, cwavtool, pycgfx The Nintendo 3DS (CIA) installable target Packaging a 3DS installable
Docker (optional) Building Linux and console targets in the maintained container instead of installing the toolchains above; see Compiling.md docker --version

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 (https://devkitpro.org/wiki/devkitPro_pacman)

bash wget https://apt.devkitpro.org/install-devkitpro-pacman chmod +x ./install-devkitpro-pacman sudo ./install-devkitpro-pacman

The wget may fail with a 403 — if so, just download the file manually in a browser from https://apt.devkitpro.org/install-devkitpro-pacman and continue from chmod.

  1. Install the Wii/3DS toolchains (https://devkitpro.org/wiki/Getting_Started). This is required (Polyphase always packages for the consoles), and it is required for GameCube too: wii-dev provides devkitPPC (powerpc-eabi-g++), which the GameCube build compiles with even though its libraries come from libogc2 in step 3.

bash sudo dkp-pacman -S wii-dev 3ds-dev

bash sudo dkp-pacman-key --recv-keys C8A2759C315CFBC3429CC2E422B803BA8AA3D7CE --keyserver keyserver.ubuntu.com sudo dkp-pacman-key --lsign-key C8A2759C315CFBC3429CC2E422B803BA8AA3D7CE - Add this entry to /opt/devkitpro/pacman/etc/pacman.conf above the existing [dkp-libs] entry. This is file content, not commands — the two Server lines are mirrors of the same repository (pacman falls back to the second if the first is unreachable), and both lines belong in the file:

 ```ini
 [libogc2-devkitpro]
 Server = https://packages.libogc2.org/devkitpro/linux/$arch
 Server = https://packages.extremscorner.org/devkitpro/linux/$arch
 ```

  • Then sync and install (accept overwriting if asked):

    bash sudo dkp-pacman -Syuu sudo dkp-pacman -S gamecube-tools-git libogc2 libogc2-libdvm

  • Check that ls /opt/devkitpro/libogc2/lib/cube lists libogc.a.

Note: the libogc2 packages are only the GameCube/Wii libraries. wii-dev and 3ds-dev are the meta-packages that pull in the actual compilers, devkitPPC (powerpc-eabi-g++) and devkitARM (arm-none-eabi-g++). Without them the editor works, but GameCube/Wii/3DS packaging fails partway through make with a missing-compiler error.

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.

Packaging Linux Installers (RPM / AppImage)

The Linux installer build targets shell out to host tools that are not installed by default. If a tool is missing, packaging fails with Exit code: 127 and Failed to start: bash '...build_rpm.sh' (or build_appimage.sh) in the log.

On Windows hosts, these targets run their scripts through WSL2 — install the tools inside your WSL distro, not on Windows.

RPM target (polyphase.linux.rpm)

Requires rpmbuild on PATH:

  • Debian/Ubuntu: sudo apt install rpm
  • Fedora: sudo dnf install rpm-build
  • Arch: sudo pacman -S rpm-tools

AppImage target (polyphase.linux.appimage)

Requires appimagetool on PATH. It is not in the distro repos — download the release binary:

sudo wget -O /usr/local/bin/appimagetool \
  https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage
sudo chmod +x /usr/local/bin/appimagetool

FUSE is not required — the packager runs appimagetool with APPIMAGE_EXTRACT_AND_RUN=1.

Offline/CI alternative: install squashfs-tools (sudo apt install squashfs-tools) and set an AppImage runtime binary as the Runtime File option in the build profile. The packager then assembles the image with mksquashfs + cat instead of appimagetool.

Packaging a 3DS installable (.cia)

The plain Nintendo 3DS build target needs nothing beyond 3ds-dev above. The Nintendo 3DS (CIA) target, which produces an installable HOME Menu title, shells out to tools that devkitPro does not ship. None of them are needed unless you use that target.

Tool Needed for Where it comes from
makerom the .cia (required) 3DSGuy/Project_CTR releases, makerom-v0.19.0-ubuntu_x86_64.zip
bannertool HOME Menu banner and tune (optional) carstene1ns/3ds-bannertool releases, bannertool-1.2.3-linux.tar.gz
cwavtool DSP-ADPCM tune encoding (optional, experimental) PabloMK7/cwavtool releases, cwavtool.zip, use linux-x86_64/cwavtool
Python 3.12 + pycgfx 3D scene banners (optional) distro python3 and python3-pip, plus skyfloogle/pycgfx

Easiest: in the editor open Preferences > External > Launchers, scroll to 3DS CIA Tools, and click Download makerom + bannertool + cwavtool. The archives are fetched from the release pages above into ~/.config/PolyphaseEditor/Tools/3DS, made executable, and picked up immediately. This needs curl or libcurl and unzip/tar on the host.

Manual: extract the binaries, chmod +x makerom bannertool cwavtool, and either copy them into /opt/devkitpro/tools/bin, put them somewhere on PATH such as ~/.local/bin, or set the path fields in the same Preferences page.

3D banners additionally need Python 3 with pip (sudo apt install python3 python3-pip or sudo pacman -S python python-pip). Then click Install pycgfx in the same Preferences page (it downloads pycgfx, pinned to a fixed commit, and runs python3 -m pip install --user gltflib pillow). pycgfx has no license file, which is why the editor only fetches it on request and never bundles it. Selecting a 3D banner in a build profile without these installed shows what is missing and falls back to the image banner.

Details on the target, its options and the HOME Menu limits are in Platforms/3DS/Overview.md.

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.