Waydroid Installation and Usage Guide on X11

Introduction
System Requirements
Installation
Usage
- Launching Waydroid
- Stopping Waydroid
Additional Configuration
- Hiding Waydroid Apps from the System Launcher
- Enable Clipboard on Weston
Automation
- Creating Automated Startup Scripts
Troubleshooting
References

Introduction

This guide provides comprehensive instructions for installing and using Waydroid on an X11-based Linux system. Waydroid is a powerful tool that enables you to run Android in a containerized environment on Linux, giving you a full Android system experience directly on your desktop.

System Requirements

Before you proceed, ensure that your system meets the following prerequisites:

A working X11 environment.
Administrative privileges (sudo access).
curl and ca-certificates installed.

Ensure you have these dependencies installed by running:

sudo apt install curl ca-certificates -y

Installation

Install Weston

Weston is a reference Wayland compositor required by Waydroid to render the Android interface. Install Weston with the following command:

sudo apt install weston -y

Install Waydroid

Follow these steps to install Waydroid on your system.

Step 1: Add the Waydroid Repository

Run the following command to add the official Waydroid repository:

curl https://repo.waydro.id | sudo bash

Step 2: Install Waydroid

Once the repository is added, install Waydroid using:

sudo apt install waydroid -y

Initialize Waydroid

Waydroid initialization must be done from within the Weston session. Follow these steps to initialize Waydroid:

Start Weston:

In a terminal, run:
```
weston --socket=mysocket
```
This command starts a Weston session on the specified socket.
Switch to the Weston terminal:

In the Weston terminal window (where Weston is running), perform one of the following initialization commands depending on your preference.

Vanilla Android Initialization

To initialize Waydroid without Google Apps (GAPPS), run:

sudo waydroid init

Android with GAPPS

To initialize Waydroid with Google Apps (GAPPS) support, use:

sudo waydroid init -f -s GAPPS

After initialization, Waydroid is ready to be launched. You can now proceed with launching Waydroid using the instructions below.

Usage

Launching Waydroid

Once initialized, you can launch Waydroid within a Weston session using the following steps:

Start Weston:

In a terminal, run:
```
weston --socket=mysocket
```
This command initializes a Weston session with a specific socket.
Launch Waydroid:

Inside the Weston terminal, start the Waydroid user interface:
```
waydroid show-full-ui
```
This will boot the full Android system within the Wayland environment.

Stopping Waydroid

When you are finished using Waydroid, you can stop the session by running:

waydroid session stop

This will gracefully terminate the Waydroid session.

Additional Configuration

Hiding Waydroid Apps from the System Launcher

By default, Waydroid apps may appear in your system launcher. To prevent this and keep your launcher clean, run the following script:

for a in ~/.local/share/applications/waydroid.*.desktop; do
    grep -q NoDisplay $a || sed '/^Icon=/a NoDisplay=true' -i $a
done

This script adds the NoDisplay=true entry to each Waydroid .desktop file, effectively hiding them from the system launcher.

Enable Clipboard on Weston

To enable clipboard functionality between Weston and X11 environments, follow these steps:

Install pyclip (Python clipboard library):
```
sudo pip install pyclip
```
Install wl-clipboard (Wayland clipboard utility):
```
sudo apt install wl-clipboard
```

With these tools, you can now share clipboard data between your Waydroid session and the X11 environment, making copy-pasting more seamless.

Automation

You can automate Waydroid’s startup and shutdown processes by creating scripts and a desktop entry.

Creating Automated Startup Scripts

1. Create a Weston Configuration File

Create a ~/.config/weston.ini file to configure Weston’s behavior:

[libinput]
enable-tap=true

[shell]
panel-position=none

This configuration improves input handling and removes the panel from Weston.

2. Create a Waydroid Startup Script

Save the following script as /usr/bin/waydroid-session.sh:

#!/bin/bash

# Start Weston
weston --xwayland &
WESTON_PID=$!
export WAYLAND_DISPLAY=wayland-1
sleep 2

# Launch Waydroid
waydroid show-full-ui &
WAYDROID_PID=$!

# Function to stop Waydroid
stop_waydroid() {
    waydroid session stop
    kill $WESTON_PID
    kill $WAYDROID_PID 2>/dev/null
}

# Wait for Weston to finish
wait $WESTON_PID

# Stop Waydroid after Weston exits
stop_waydroid

Make the script executable:

chmod +x /usr/bin/waydroid-session.sh

3. Create a Desktop Entry

Create a desktop entry to easily launch the session from your system launcher. Save the following as /usr/share/applications/waydroid-session.desktop:

[Desktop Entry]
Version=1.0
Type=Application
Name=Waydroid Session
Comment=Launch Waydroid X11 Session
Exec=/bin/bash -c "cd /usr/bin && ./waydroid-session.sh"
Icon=waydroid
Terminal=false
Categories=System;Emulator;

Make the desktop entry executable:

chmod +x /usr/share/applications/waydroid-session.desktop

Troubleshooting

If you encounter any issues, consider the following:

Weston fails to start: Ensure that you have Weston installed and your X11 session is running correctly.
Waydroid session does not launch: Check your Weston configuration and ensure that Waydroid is properly installed.
Performance issues: Consider allocating more system resources to Waydroid and Weston by adjusting your system settings.

For advanced troubleshooting, consult the official Waydroid documentation.

References

This guide now includes the initialization steps for Waydroid, both with and without GAPPS, and instructions for enabling clipboard functionality inside the Weston.

1999AZZAR/waydroid on x11.md