Installation - ArunPrakashG/native-launcher GitHub Wiki

Installation Guide

This guide covers all methods for installing Native Launcher on your Linux system.

Table of Contents

Prerequisites

Runtime Requirements

Native Launcher requires the following to run:

  • Wayland compositor with layer shell support
    • Sway, Hyprland, River (wlroots-based)
    • KDE Plasma (Wayland session)
    • GNOME (Mutter)
  • GTK4 (>= 4.8)
  • gtk4-layer-shell
  • wl-clipboard (for clipboard functionality in advanced calculator)

Build Dependencies

Arch Linux

# Build dependencies
sudo pacman -S rust gtk4 gtk4-layer-shell pkg-config git

# Runtime dependencies (optional, for full functionality)
sudo pacman -S wl-clipboard

Ubuntu/Debian

# Build dependencies
sudo apt install cargo libgtk-4-dev libgtk4-layer-shell-dev pkg-config git build-essential

# Runtime dependencies (optional, for full functionality)
sudo apt install wl-clipboard

Fedora

# Build dependencies
sudo dnf install rust cargo gtk4-devel gtk4-layer-shell-devel pkg-config git

# Runtime dependencies (optional, for full functionality)
sudo dnf install wl-clipboard

openSUSE

# Build dependencies
sudo zypper install rust cargo gtk4-devel gtk4-layer-shell-devel pkg-config git

# Runtime dependencies (optional, for full functionality)
sudo zypper install wl-clipboard

Build from Source

1. Clone the Repository

git clone https://github.com/ArunPrakashG/native-launcher.git
cd native-launcher

2. Build in Release Mode

cargo build --release

This will create an optimized binary at target/release/native-launcher.

Build time: ~2-5 minutes (first build compiles dependencies)

3. Install System-Wide (Optional)

# Install binary
sudo install -Dm755 target/release/native-launcher /usr/local/bin/native-launcher

# Install desktop file (optional, for app menus)
sudo install -Dm644 native-launcher.desktop /usr/share/applications/native-launcher.desktop

4. Verify Installation

native-launcher --version

Distribution Packages

Arch Linux (AUR)

Coming soon

yay -S native-launcher-git

Debian/Ubuntu (.deb)

Coming soon

sudo dpkg -i native-launcher_1.0.0_amd64.deb

Fedora (.rpm)

Coming soon

sudo dnf install native-launcher-1.0.0.rpm

Nixpkgs

Coming soon

environment.systemPackages = with pkgs; [
  native-launcher
];

Post-Installation

1. Set Up Keyboard Shortcut

Native Launcher doesn't have a built-in global hotkey. You need to configure your compositor to launch it.

See Compositor Integration for detailed setup for each compositor.

Quick examples:

Sway (~/.config/sway/config):

bindsym $mod+Space exec native-launcher

Hyprland (~/.config/hypr/hyprland.conf):

bind = SUPER, SPACE, exec, native-launcher

2. First Run

native-launcher

On first run, Native Launcher will:

  • Scan your /usr/share/applications and ~/.local/share/applications
  • Build an icon cache
  • Create default configuration at ~/.config/native-launcher/config.toml

3. Configuration (Optional)

Generate default configuration:

native-launcher --generate-config

Edit the configuration:

$EDITOR ~/.config/native-launcher/config.toml

See Configuration for all available options.

Troubleshooting

Issue: Command not found

Cause: Binary not in PATH

Solution:

# If installed to /usr/local/bin, ensure it's in PATH
echo $PATH | grep /usr/local/bin

# Add to ~/.bashrc or ~/.zshrc if missing:
export PATH="/usr/local/bin:$PATH"

Issue: Launcher doesn't show up

Cause: Compositor doesn't support layer shell

Solution:

# Check if wlr-layer-shell is available
wayland-info | grep layer_shell

# Expected output:
# wlr_layer_shell_v1 (version 4)

If not found, your compositor doesn't support layer shell. Native Launcher requires this protocol.

Issue: Build fails with "could not find gtk4"

Cause: GTK4 development files not installed

Solution:

# Install GTK4 dev packages (see Prerequisites section above)
# Arch:
sudo pacman -S gtk4

# Ubuntu/Debian:
sudo apt install libgtk-4-dev

Issue: No applications showing

Cause: Desktop files not found

Solution:

# Verify desktop files exist
ls /usr/share/applications/
ls ~/.local/share/applications/

# If empty, install some applications first
# Then run:
native-launcher --rescan

Issue: Icons not displaying

Cause: Icon theme not installed or cache not built

Solution:

# Install an icon theme
sudo pacman -S papirus-icon-theme  # Arch
sudo apt install papirus-icon-theme  # Ubuntu

# Rebuild icon cache
native-launcher --rebuild-icons

Issue: Slow startup

Cause: Large number of desktop files or icon cache not built

Solution:

# Check number of desktop files
find /usr/share/applications -name "*.desktop" | wc -l

# Build icon cache in background (happens automatically on first run)
# Or clear cache if corrupted:
rm -rf ~/.cache/native-launcher/icons
native-launcher

Issue: Keyboard shortcut not working

Cause: Compositor keybinding not configured

Solution: Configure the hotkey in your compositor's config file, not in native-launcher. See Compositor Integration.

Uninstallation

If installed from source

sudo rm /usr/local/bin/native-launcher
sudo rm /usr/share/applications/native-launcher.desktop
rm -rf ~/.config/native-launcher
rm -rf ~/.cache/native-launcher

If installed via package manager

# AUR
yay -R native-launcher-git

# Debian/Ubuntu
sudo apt remove native-launcher

# Fedora
sudo dnf remove native-launcher

Development Build

For development and testing:

# Clone repository
git clone https://github.com/ArunPrakashG/native-launcher.git
cd native-launcher

# Build and run in debug mode
cargo run

# Run with logging
RUST_LOG=debug cargo run

# Run tests
cargo test

# Format code
cargo fmt

# Lint
cargo clippy

See Contributing for more development setup details.

Next Steps