@ncalexander

Bumpy landings: How to land a Fennec feature behind a build flag

Wed 09 July 2014 / tagged: android, build system, fennec

Fennec (Firefox for Android) features are staged and ride the trains (Nightly, Aurora, and Beta) before reaching the Release audience. Features that land on Nightly may — or may not — continue to Aurora. To support rapid Nightly development, while letting code mature before it reaches Aurora, you should land your new feature behind a runtime preference or a build flag. Here’s a guide to landing behind such a flag.

Examples

We’ll use the following ticket as an example of landing a new build flag, code behind the flag, and build system integration:

  • Bug 1021864 landed the code and Android resources for the Search Activity. The Search Activity is an Android activity that depends on GeckoView. As such, it’s built as part of the main Fennec code-base, since GeckoView is essentially the same as Fennec. The build flag is MOZ_ANDROID_SEARCH_ACTIVITY.

You can also look at the following tickets, which are being actively developed during the Firefox for Android 33 cycle.

  • Bug 1024708 will land the code and Android manifest integration for the Mozilla Stumbler. The stumbler is an Android background service that uploads location sensor data to Mozilla. That location sensor data is then reflected to device users through the Mozilla Location Service. This helps device users locate themselves in the world, without requiring a GPS lock. Since the stumbler presents no UI directly, it’s built as a separate Java JAR, and integrated into the Fennec APK via manifest fragments.
  • Bug 1033560 "flipped the switch" to enable flinging videos to Google Chromecast devices. (The code landed in a long sequence of earlier tickets.) The Chromecast source code is part of the main Fennec code base, and parts of it are compiled (or manifest fragments included) conditionally.

Guide to landing

Let’s look at Bug 1021864. This ticket landed as a series of 5 commits [1].

Build flags

The interesting commits of Bug 1021864 are the second and the fifth. The second commit adds a build flag, MOZ_ANDROID_SEARCH_ACTIVITY, that defaults to not being set:

--- a/configure.in
+++ b/configure.in
@@ -3915,16 +3915,17 @@ if test -n "$MOZ_RTSP"; then
 fi
 MOZ_LOCALE_SWITCHER=
+MOZ_ANDROID_SEARCH_ACTIVITY=
 ACCESSIBILITY=1

And enables it just for mobile/android:

--- a/mobile/android/confvars.sh
+++ b/mobile/android/confvars.sh
@@ -69,8 +69,11 @@ fi
 # Enable second screen using native Android libraries
 MOZ_NATIVE_DEVICES=
+
+# Enable the Search Activity.
+MOZ_ANDROID_SEARCH_ACTIVITY=1

Guarding a feature behind the build flag

Use the preprocessor to conditionally include code (and other includes, etc) behind the build flag. For example, the first commit landed all the code for the initial version of the Search Activity with no build integration at all. Then, the third commit exposed the build flag:

--- a/mobile/android/base/locales/moz.build
+++ b/mobile/android/base/locales/moz.build
@@ -1,6 +1,8 @@
 # -*- Mode: python; c-basic-offset: 4; indent-tabs-mode: nil; tab-width: 40 -*-
 # vim: set filetype=python:
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.

+if CONFIG['MOZ_ANDROID_SEARCH_ACTIVITY']:
+    DEFINES['MOZ_ANDROID_SEARCH_ACTIVITY'] = 1

and used the flag in a preprocessed Android resource file:

--- a/mobile/android/base/strings.xml.in
+++ b/mobile/android/base/strings.xml.in
@@ -3,16 +3,19 @@
 <!-- This Source Code Form is subject to the terms of the Mozilla Public
    - License, v. 2.0. If a copy of the MPL was not distributed with this
    - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
   <string name="android_package_name_for_ui">@ANDROID_PACKAGE_NAME@</string>
+
+#ifdef MOZ_ANDROID_SEARCH_ACTIVITY
+#include ../search/strings/search_strings.xml.in
+#endif
+
 #include ../services/strings.xml.in

The fourth commit includes the bulk of the integration: the Java code itself is built and included in Fennec by the code changes in mobile/android/base/moz.build and mobile/android/base/Makefile.in.

Landing disabled

The fifth commit disables the Search Activity. This is because we wanted to land build-time disabled, work out initial issues using local and try builds, and then build-time enable when the feature stabilizes.

--- a/mobile/android/confvars.sh
+++ b/mobile/android/confvars.sh
 # Enable second screen using native Android libraries
 MOZ_NATIVE_DEVICES=

-# Enable the Search Activity.
-MOZ_ANDROID_SEARCH_ACTIVITY=1
+# Don't enable the Search Activity.
+# MOZ_ANDROID_SEARCH_ACTIVITY=1

Guide to enabling

To enable a feature behind a build time flag, we merely need to flip the switch in mobile/android/confvars.sh. This can be a conditional flip; for example, to enable only in Nightly:

if test "$NIGHTLY_BUILD"; then
  MOZ_ANDROID_SEARCH_ACTIVITY=1
else
  MOZ_ANDROID_SEARCH_ACTIVITY=
fi

Likewise, to enable only when not in Release or Beta:

if test ! "$RELEASE_BUILD"; then
  MOZ_ANDROID_SEARCH_ACTIVITY=1
else
  MOZ_ANDROID_SEARCH_ACTIVITY=
fi

See https://wiki.mozilla.org/Platform/Channel-specific_build_defines for details on the relevant flags.

Nick Alexander

About Nick Alexander

Mathematician. Mozillian. Runner. Master of Disguise.