Getting GeckoView to Build+Run On Your Phone Under WSL2

README.md

Building GeckoView on WSL(2) basically works out of the box like building it natively on Linux with mach.

Running your build is the real issue.

You generally have two options for running:

• Run GeckoView in an emulator
• Run GeckoView natively on a phone

Trying to launch an emulator is likely to run into KVM errors, although apparently this has been fixed in the latest versions of Windows 11 (haven't confirmed).

Trying to launch natively on a phone will run into the fact that USB is sandboxed so your phone won't show up in WSL. However there is a way around this. Connecting to the device is generally managed by a program called ADB which runs as a server. ADB servers on the same machine can generally talk to eachother even through the WSL sandbox. So we are going to setup ADB natively in Windows, and then use that to feed our phone into the ADB instance in WSL that mach run uses.

The rest of this guide will cover the native phone case.

Step 1: Install Android Studio On Your Native Windows System

Installer is here: https://developer.android.com/studio/

This serves two purposes:

• To install command line tools on your system (notably adb).

• To give you an environment to test/debug your setup under ideal conditions (make a sample project, try to launch it on your phone)

Ideally adb.exe will be available in %LOCALAPPDATA%\Android\Sdk\platform-tools

Step 2: (Optional) Add Android command-line tools to your %PATH%

If you type "path" into start it should bring up "Edit The System Variables"

Add the following entry to %PATH%:

%LOCALAPPDATA%\Android\Sdk\platform-tools

You will likely need to close and restart your terminal.

Step 3: Get your device in "Developer Mode"

Do the weird Click The Build ID thing in the docs.

Enable USB debugging in the developer settings.

Step 4: (Optional) Confirm your computer sees your phone over USB

Launch one of the sample projects in android studio, build and deploy to device.

Make sure everything's working natively.

Step 5: Find your device's IP Address

For me it's in Settings > About Phone > Status

This IP will be the method WSL uses to identify the device.

Step 6: Feed One ADB Into The Other

In PowerShell run:

adb tcpip 5555

This will broadcast your device for other ADB instances

In WSL run:

~/.mozbuild/android-sdk-linux/platform-tools/adb connect YOUR_DEVICE_IP

You will need to unlock your device and accept some prompts. If this all works, you should see something like:

connected to 10.0.0.100:5555

Now when you run ./mach run it will see your device!

Step 7: (Optional) Ensure mozconfig has aarch64 (ARM64) enabled

Uncomment ac_add_options --target=aarch64 in your mozconfig to get a 64-bit ARM build, which is what nearly every phone uses.