Developer workflow

Building Wolvic

1. Get the code

git clone https://github.com/Igalia/wolvic.git
cd wolvic
git clone https://github.com/Igalia/wolvic-third-parties.git third_party
git submodule update --init --recursive

The third_party folder can be updated like this:

pushd third_party && git fetch && git checkout main && git rebase origin/main && git submodule update --init --recursive --remote && popd

2. Setup Wolvic in Android Studio

Open the wolvic folder in Android Studio and wait for the project to sync. Select the appropriate build variant for your device. For example, if you are developing for a Meta device:

Module:  :app
Active Build Variant:  oculusvrArm64WorldDebug
Active ABI:  arm64-v8a

3. Build

Build > Make project

And verify that the code compiles without problems.

If you have already set up a device, you can now launch the app with:

Run > Run 'app'

(for additional details check the github repo)

Building Gecko

These are the instructions to compile Gecko and use it in Wolvic. Gecko is Firefox's Web engine, the library that interprets the source code of a website and renders it on the screen.

Note: compiling Gecko is not strictly required to run Wolvic, which can also use a prebuilt binary from Maven. This is much faster than building Gecko but has the downside of not being able to run WebXR experiences.

1. Get the code

Wolvic v1.5 and later

curl -O https://ftp.mozilla.org/pub/firefox/releases/116.0.3/source/firefox-116.0.3.source.tar.xz
tar -xf firefox-116.0.3.source.tar.xz

git clone https://github.com/Igalia/wolvic-gecko-patches.git

cd firefox-116.0.3
find ../wolvic-gecko-patches/gecko-116.0.3/ -type f -name "*patch" -print0 | sort -z | xargs -t -n1 -0 patch -p1 -i

Wolvic before v1.5

git clone git@github.com:Igalia/gecko-dev.git
cd gecko-dev
git checkout FIREFOX_103_0_2_RELEASE

Early versions of Wolvic used other branches. That is not very relevant now as it's becoming more and more difficult to get those old versions running in VR devices due to OS updates that broke the support for those versions.

Building a specific version of Wolvic

Wolvic releases have been tagged since the beginning. The format of the tag names used is vX.Y.Z (note that the Wolvic repository still contains tags from the previous FirefoxReality project which do not start with the v character).

You can build a specific version just by checking out a specific flag

git checkout vX.Y.Z

Starting in the 1.3.x cycle, we have been also using release branches to backport fixes from main branch into the stable release branches. Currently you could find in the repo the following stable branches release/1.3, release/1.4 and release/1.5.

2. Edit the mozconfig file

Edit the file mozconfig in the gecko-dev folder and ensure that these two lines are present and not in a comment:

ac_add_options --enable-application=mobile/android
ac_add_options --target=aarch64

Optionally you could include the following

ac_add_options --enable-optimize --disable-debug --enable-geckoview-lite

3. Configure the build

./mach bootstrap

When prompted, select this option:

4. GeckoView/Firefox for Android

The script will install a bunch of packages required to compile the project inside the ~/.mozbuild folder and save the configuration in the mozconfig file.

(The packages in ~/.mozbuild take up several GB of space; if needed, it is safe to delete them after compiling the project).

4. Build Gecko

./mach build

(This might take some time)

5. Configure Wolvic

Go to the folder with the Wolvic source code and add two new lines in the file local.properties

dependencySubstitutions.geckoviewTopsrcdir=PATH_TO_GECKO_SOURCES
dependencySubstitutions.geckoviewTopobjdir=PATH_TO_GECKO_SOURCES/obj-aarch64-unknown-linux-android

These lines will tell Wolvic where to look for the alternative version of the library.

For example, if the Wolvic source code is in

/home/USER/Projects/wolvic

and the Gecko sources project are in

/home/USER/Projects/gecko-dev

These two lines should be be added to /home/USER/Projects/wolvic/local.properties:

dependencySubstitutions.geckoviewTopsrcdir=/home/USER/Projects/gecko-dev
dependencySubstitutions.geckoviewTopobjdir=/home/USER/Projects/gecko-dev/obj-aarch64-unknown-linux-android

6. Open and update Wolvic in Android Studio:

File > Sync project with Gradle files
Build > Make Project

If things have worked correctly, in the "Build" section (bottom bar) there should be a log line saying something like:

[substitute-local-geckoview] Will substitute GeckoView (geckoview-{nightly,beta}) with local GeckoView (geckoview-default) from …

7. Run Wolvic in your device

Run Wolvic on your device and check that WebXR experiences now work correctly.