Building from Source

Build and install Mango Wayland Compositor from source

Prerequisites

Building Mango from source requires specific versions of wlroots and scenefx, along with development tools.

Build Tools

Install the required build tools:

Arch Linux

sudo pacman -S git meson ninja pkg-config

Build Dependencies

Mango requires these dependencies (from meson.build):

Required Dependencies

• wayland (>=1.23.1) - Wayland compositor library
• wayland-protocols - Wayland protocol definitions
• libinput (>=1.27.1) - Input device management
• libxkbcommon - Keyboard handling
• pcre2 - Regular expression library
• pixman - Pixel manipulation library
• wlroots (0.19.x) - Wayland compositor library
• scenefx (>=0.4.1) - Scene graph and effects library

Optional Dependencies

• xorg-xwayland - X11 application support
• libxcb - X protocol C bindings
• xcb-icccm - X window manager utilities

Install Dependencies

Arch Linux

sudo pacman -S wayland wayland-protocols libinput libxkbcommon \
  pcre2 pixman xorg-xwayland libxcb xcb-util-wm

Installation Steps

1. Build and install wlroots

   Mango requires wlroots 0.19.2:

   git clone -b 0.19.2 https://gitlab.freedesktop.org/wlroots/wlroots.git
   cd wlroots
   meson build -Dprefix=/usr
   sudo ninja -C build install
   cd ..
   

   Make sure to use version 0.19.2 specifically, as Mango depends on this version.

2. Build and install scenefx

   Mango requires scenefx 0.4.1 or later:

   git clone -b 0.4.1 https://github.com/wlrfx/scenefx.git
   cd scenefx
   meson build -Dprefix=/usr
   sudo ninja -C build install
   cd ..
   
3. Clone Mango repository

   Get the latest Mango source code:

   git clone https://github.com/mangowm/mango.git
   cd mango
   
4. Configure build

   Configure the build with meson:

   Standard Build

   meson build -Dprefix=/usr
   

   Without XWayland

   meson build -Dprefix=/usr -Dxwayland=disabled
   

   Debug Build

   meson build -Dprefix=/usr -Dasan=true
   

   Debug builds enable AddressSanitizer for development.

5. Build and install

   Compile and install Mango:

   sudo ninja -C build install
   

   This installs:

   • mango - The compositor binary
   • mmsg - IPC message tool
   • Desktop files and configuration
6. Verify installation

   Check that Mango is installed correctly:

   mango --version
   

   You should see the version information with commit hash.

Build Options

Mango supports these meson build options:

prefix · string · default: "/usr/local"

Installation prefix

xwayland · feature · default: "enabled"

Enable XWayland support for X11 applications

asan · boolean · default: "false"

Enable AddressSanitizer for debugging

Installed Files

The installation creates these files:

/usr/bin/mango                              # Main compositor
/usr/bin/mmsg                               # IPC tool
/usr/share/wayland-sessions/mango.desktop   # Session file
/usr/share/xdg-desktop-portal/mango-portals.conf
/etc/mango/config.conf                      # Default config

Configuration

After installation, copy the default configuration to your user directory:

mkdir -p ~/.config/mango
cp /etc/mango/config.conf ~/.config/mango/config.conf

Edit ~/.config/mango/config.conf to customize your setup.

Updating

To update to the latest version:

cd mango
git pull
meson build -Dprefix=/usr --reconfigure
sudo ninja -C build install

Uninstalling

To remove Mango:

cd mango/build
sudo ninja uninstall

Troubleshooting

pkg-config cannot find wlroots

Make sure you installed wlroots 0.19.2 with the correct prefix:

pkg-config --modversion wlroots-0.19

If not found, ensure /usr/lib/pkgconfig is in your PKG_CONFIG_PATH:

export PKG_CONFIG_PATH=/usr/lib/pkgconfig:$PKG_CONFIG_PATH

scenefx not found

Verify scenefx installation:

pkg-config --modversion scenefx-0.4

If missing, rebuild scenefx with the correct prefix.

Build fails with version mismatch

Mango requires specific versions:

• wlroots: 0.19.0 or later (0.19.2 recommended)
• scenefx: 0.4.1 or later
• wayland: 1.23.1 or later
• libinput: 1.27.1 or later

Check installed versions and rebuild dependencies if needed.

Permission denied during install

Use sudo for installation:

sudo ninja -C build install

Or configure with a user-writable prefix:

meson build -Dprefix=$HOME/.local
ninja -C build install

Next Steps

Configuration

Configure Mango to your preferences

Keybindings

Learn default keybindings and create custom ones