Skip to content

Installation Troubleshooting Guide

This guide helps resolve common issues encountered when building and installing Movian on various platforms.

Quick Diagnosis

Build Issues Checklist

Before diving into specific problems, run through this quick checklist:

  • [ ] Dependencies installed: All required libraries and development packages
  • [ ] Compiler version: GCC 4.8+ or Clang 3.4+ with C99/C++11 support
  • [ ] Disk space: At least 2GB free space for build
  • [ ] Network access: Required for downloading dependencies
  • [ ] Permissions: Write access to build directory

Common Error Patterns

Error Pattern Likely Cause Quick Fix
Package 'X' not found Missing development package Install libX-dev package
undefined reference to 'symbol' Missing library Add library to linker flags
No such file or directory Missing header Install development headers
Permission denied Insufficient permissions Use sudo or fix ownership
configure: error: Configuration failure Check dependencies and flags

Platform-Specific Issues

Linux Issues

Ubuntu/Debian Package Problems

Problem: Package not found errors 

# Error examples:
# Package 'freetype2' not found
# Package 'fontconfig' not found
# Package 'x11' not found

Solution: Install development packages 

# Update package database first
sudo apt-get update

# Install missing packages
sudo apt-get install libfreetype6-dev    # for freetype2
sudo apt-get install libfontconfig1-dev  # for fontconfig
sudo apt-get install libx11-dev          # for x11
sudo apt-get install libxext-dev         # for xext

# Install all common dependencies at once
sudo apt-get install -y \
    libfreetype6-dev libfontconfig1-dev libxext-dev \
    libgl1-mesa-dev libasound2-dev libgtk2.0-dev \
    libxss-dev libxxf86vm-dev libxv-dev libvdpau-dev \
    yasm libpulse-dev libssl-dev curl \
    libwebkitgtk-dev libsqlite3-dev libavahi-client-dev

Problem: WebKit version conflicts 

# Error: Package 'webkit2gtk-4.0' not found
# Or: WebKit version too old

Solution: Use alternative WebKit package or disable 

# Try different WebKit packages
sudo apt-get install libwebkit2gtk-4.0-dev  # Ubuntu 18.04+
sudo apt-get install libwebkitgtk-3.0-dev   # Ubuntu 16.04

# Or disable WebKit entirely
./configure --disable-webkit

Fedora/CentOS/RHEL Issues

Problem: Development tools not available 

# Error: gcc: command not found
# Error: make: command not found

Solution: Install development group 

# Fedora
sudo dnf groupinstall "Development Tools"
sudo dnf install gcc gcc-c++ make

# CentOS/RHEL 8
sudo dnf groupinstall "Development Tools"

# CentOS/RHEL 7
sudo yum groupinstall "Development Tools"

Problem: EPEL repository needed 

# Error: No package yasm available

Solution: Enable EPEL repository 

# CentOS/RHEL 8
sudo dnf install epel-release
sudo dnf config-manager --set-enabled powertools

# CentOS/RHEL 7
sudo yum install epel-release

Problem: GCC version too old (CentOS 7) 

# Error: C99 support required

Solution: Install newer GCC from SCL 

sudo yum install centos-release-scl
sudo yum install devtoolset-8-gcc devtoolset-8-gcc-c++

# Enable for current session
scl enable devtoolset-8 bash

# Or configure with specific compiler
./configure --cc=/opt/rh/devtoolset-8/root/usr/bin/gcc

macOS Issues

Xcode Command Line Tools Problems

Problem: Xcode license not accepted 

# Error: Xcode license agreement not accepted

Solution: Accept license 

sudo xcodebuild -license accept

Problem: Command Line Tools not installed 

# Error: xcrun: error: invalid active developer path

Solution: Install Command Line Tools 

xcode-select --install

# If that fails, reset and try again
sudo xcode-select --reset
xcode-select --install

Homebrew Issues

Problem: Homebrew not found 

# Error: brew: command not found

Solution: Install Homebrew 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add to PATH (Apple Silicon)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

# Add to PATH (Intel)
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Problem: OpenSSL not found 

# Error: openssl/ssl.h: No such file or directory

Solution: Install and configure OpenSSL 

# Install OpenSSL
brew install openssl

# Configure build (Intel Mac)
./configure --extra-cflags="-I/usr/local/opt/openssl/include" \
           --extra-ldflags="-L/usr/local/opt/openssl/lib"

# Configure build (Apple Silicon)
./configure --extra-cflags="-I/opt/homebrew/opt/openssl/include" \
           --extra-ldflags="-L/opt/homebrew/opt/openssl/lib"

Apple Silicon (M1/M2) Issues

Problem: Architecture mismatch 

# Error: building for wrong architecture

Solution: Specify correct architecture 

# Check current architecture
uname -m

# Configure for native architecture
./configure --arch=$(uname -m)

# Or force specific architecture
./configure --arch=arm64    # Apple Silicon
./configure --arch=x86_64   # Intel/Rosetta

Windows Issues (MinGW/MSYS2)

MSYS2 Setup Problems

Problem: MSYS2 packages not found 

# Error: Package not found in repositories

Solution: Update package database 

# Update MSYS2
pacman -Syu

# Install base development tools
pacman -S base-devel mingw-w64-x86_64-toolchain

# Install Movian dependencies
pacman -S mingw-w64-x86_64-freetype \
          mingw-w64-x86_64-fontconfig \
          mingw-w64-x86_64-openssl

Build Configuration Issues

Configure Script Failures

Missing pkg-config

Problem: pkg-config not found 

# Error: pkg-config not found

Solution: Install pkg-config 

# Ubuntu/Debian
sudo apt-get install pkg-config

# Fedora/CentOS
sudo dnf install pkgconf-devel  # Fedora
sudo yum install pkgconfig      # CentOS 7

# macOS
brew install pkg-config

Library Detection Issues

Problem: Libraries installed but not detected 

# Error: Package 'library' not found
# But library is installed

Solution: Check and fix pkg-config paths 

# Check current pkg-config paths
pkg-config --variable pc_path pkg-config

# Add custom paths
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"

# For 64-bit systems, also check lib64
export PKG_CONFIG_PATH="/usr/local/lib64/pkgconfig:$PKG_CONFIG_PATH"

# Verify library is found
pkg-config --exists freetype2 && echo "Found" || echo "Not found"

Custom Library Locations

Problem: Libraries in non-standard locations 

# Error: Library not found in standard paths

Solution: Specify custom paths 

# Configure with custom paths
./configure \
    --extra-cflags="-I/opt/local/include -I/usr/local/include" \
    --extra-ldflags="-L/opt/local/lib -L/usr/local/lib"

# Or set environment variables
export CPPFLAGS="-I/opt/local/include"
export LDFLAGS="-L/opt/local/lib"
./configure

Compilation Issues

Compiler Errors

C99/C++11 Support

Problem: Compiler doesn't support required standards 

# Error: C99 features not supported
# Error: C++11 features not supported

Solution: Use newer compiler or specify standards 

# Install newer GCC
sudo apt-get install gcc-8 g++-8

# Configure with specific compiler
./configure --cc=gcc-8 --cxx=g++-8

# Or add standard flags
./configure --extra-cflags="-std=c99" --extra-cxxflags="-std=c++11"

Missing Headers

Problem: System headers not found 

# Error: sys/types.h: No such file or directory
# Error: pthread.h: No such file or directory

Solution: Install system development packages 

# Ubuntu/Debian
sudo apt-get install libc6-dev build-essential

# Fedora/CentOS
sudo dnf install glibc-devel kernel-headers

# Check compiler installation
gcc --version
which gcc

Symbol Resolution Issues

Problem: Undefined references during linking 

# Error: undefined reference to `pthread_create'
# Error: undefined reference to `dlopen'

Solution: Add missing libraries 

# Common missing libraries and their flags
# pthread: -lpthread
# dl: -ldl
# math: -lm
# rt: -lrt

# Configure with additional libraries
./configure --extra-ldflags="-lpthread -ldl -lm -lrt"

Memory and Resource Issues

Out of Memory During Compilation

Problem: Compilation fails due to insufficient memory 

# Error: virtual memory exhausted
# Error: cc1: out of memory allocating X bytes

Solution: Reduce parallel jobs or add swap 

# Reduce parallel compilation
make -j1  # Use single thread
make -j2  # Use 2 threads instead of all cores

# Add swap space (Linux)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Check available memory
free -h

Disk Space Issues

Problem: No space left on device 

# Error: No space left on device

Solution: Clean up and free space 

# Check disk usage
df -h

# Clean build directory
make clean
make distclean

# Remove temporary files
rm -rf /tmp/*

# Clean package cache (Ubuntu/Debian)
sudo apt-get clean
sudo apt-get autoremove

Runtime Issues

Library Loading Problems

Missing Shared Libraries

Problem: Shared library not found at runtime 

# Error: error while loading shared libraries: libssl.so.1.1

Solution: Install runtime libraries or fix paths 

# Check missing libraries
ldd build.linux/movian

# Install missing runtime packages
sudo apt-get install libssl1.1  # for libssl.so.1.1
sudo apt-get install libpulse0   # for libpulse.so.0

# Or add library path
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"

Version Conflicts

Problem: Library version mismatch 

# Error: version `GLIBC_2.29' not found

Solution: Check compatibility or rebuild 

# Check glibc version
ldd --version

# Check required versions
objdump -T build.linux/movian | grep GLIBC

# If incompatible, rebuild on target system
# Or use static linking
./configure --enable-static

Permission Issues

Audio/Video Device Access

Problem: Cannot access audio or video devices 

# Error: Permission denied: /dev/dsp
# Error: Permission denied: /dev/video0

Solution: Add user to appropriate groups 

# Add to audio group
sudo usermod -a -G audio $USER

# Add to video group
sudo usermod -a -G video $USER

# Log out and back in for changes to take effect
# Or use newgrp to activate groups immediately
newgrp audio
newgrp video

File System Permissions

Problem: Cannot read media files 

# Error: Permission denied accessing file

Solution: Fix file permissions or run with appropriate privileges 

# Check file permissions
ls -la /path/to/media/file

# Fix permissions if needed
chmod 644 /path/to/media/file

# Or run with sudo (not recommended for regular use)
sudo ./build.linux/movian

Display and Graphics Issues

X11 Connection Problems

Problem: Cannot connect to X server 

# Error: cannot connect to X server :0

Solution: Fix X11 configuration 

# Set DISPLAY variable
export DISPLAY=:0

# Allow X11 connections (temporary, security risk)
xhost +local:

# Better: use proper authentication
xauth list
# Copy .Xauthority to user's home directory if needed

OpenGL Issues

Problem: OpenGL not available 

# Error: GLX extension not available
# Error: OpenGL context creation failed

Solution: Install proper graphics drivers 

# Check OpenGL support
glxinfo | grep "direct rendering"

# Install Mesa drivers (open source)
sudo apt-get install mesa-utils libgl1-mesa-dri

# For NVIDIA proprietary drivers
sudo apt-get install nvidia-driver-XXX  # Replace XXX with version

# For AMD proprietary drivers
sudo apt-get install amdgpu-pro

Advanced Troubleshooting

Debug Builds

Create debug builds for better error information:

# Configure for debugging
./configure --optlevel=g --enable-bughunt

# Build with debug symbols
make -j$(nproc)

# Run with debugger
gdb ./build.linux/movian
(gdb) run
(gdb) bt  # Get backtrace on crash

Verbose Output

Enable verbose output for detailed information:

# Verbose configure
./configure --verbose

# Verbose make
make V=1

# Verbose runtime (if supported)
./build.linux/movian --verbose --debug

Sanitizers

Use sanitizers to detect memory and threading issues:

# Address Sanitizer (memory errors)
./configure --extra-cflags="-fsanitize=address -fno-omit-frame-pointer" \
           --extra-ldflags="-fsanitize=address"

# Thread Sanitizer (threading issues)
./configure --extra-cflags="-fsanitize=thread" \
           --extra-ldflags="-fsanitize=thread"

# Undefined Behavior Sanitizer
./configure --extra-cflags="-fsanitize=undefined" \
           --extra-ldflags="-fsanitize=undefined"

System Information Collection

Collect system information for bug reports:

#!/bin/bash
# System information script

echo "=== System Information ==="
uname -a
echo

echo "=== Distribution ==="
if [ -f /etc/os-release ]; then
    cat /etc/os-release
elif [ -f /etc/redhat-release ]; then
    cat /etc/redhat-release
fi
echo

echo "=== Compiler Information ==="
gcc --version 2>/dev/null || echo "GCC not found"
clang --version 2>/dev/null || echo "Clang not found"
echo

echo "=== Library Versions ==="
pkg-config --modversion freetype2 2>/dev/null || echo "freetype2 not found"
pkg-config --modversion fontconfig 2>/dev/null || echo "fontconfig not found"
pkg-config --modversion openssl 2>/dev/null || echo "openssl not found"
echo

echo "=== Build Configuration ==="
if [ -f build.linux/config.mak ]; then
    grep "^CONFIG_" build.linux/config.mak
fi

Getting Help

Before Asking for Help

  1. Search existing issues: Check GitHub issues for similar problems
  2. Collect information: Run the system information script above
  3. Minimal reproduction: Create minimal steps to reproduce the issue
  4. Try workarounds: Attempt suggested solutions in this guide

Where to Get Help

Information to Include

When reporting issues, include:

  • Platform: OS, version, architecture
  • Build configuration: Configure command and flags used
  • Error messages: Complete error output, not just summaries
  • System info: Output from system information script
  • Steps to reproduce: Exact commands that cause the issue

Source References: - configure.linux, configure.osx - Platform-specific configuration - support/configure.inc - Common configuration functions - Community forum posts and GitHub issues

Accuracy Status: 🟢 Verified solutions from real user reports
Last Updated: November 2025
Covers: Linux, macOS, Windows build issues