264 lines
10 KiB
ReStructuredText
264 lines
10 KiB
ReStructuredText
Firefox for Android
|
||
===================
|
||
.. _firefox_for_android:
|
||
|
||
Firefox for Android consists of three layers:
|
||
|
||
- GeckoView: This is a library that brings the Gecko API to Android.
|
||
|
||
- Android Components: This is a library of reusable browser building blocks.
|
||
|
||
- Frontend (Fenix): This refers to the frontend interface.
|
||
|
||
All three components can be found in ``mozilla-central``.
|
||
To contribute to any of the three, you will need to get set up as a contributor to Firefox.
|
||
|
||
Mozilla Central Setup
|
||
---------------------
|
||
.. _mozilla-central-setup:
|
||
|
||
To set up Mozilla Central, you can follow the general instructions provided in the Mozilla Source Docs:
|
||
|
||
- :ref:`Getting Set Up To Work On The Firefox Codebase <Getting Set Up To Work On The Firefox Codebase>`
|
||
|
||
Additionally, to set up specifically for mozilla-central, you can refer to the following guide:
|
||
|
||
- :ref:`Quick Start Guide for Git Users <contribute_with_git>`
|
||
|
||
Bootstrap
|
||
----------
|
||
.. _bootstrap-setup:
|
||
|
||
Bootstrap configures everything for GeckoView and Fenix (Firefox for Android) development.
|
||
|
||
- Ensure you have ``mozilla-central`` checked out. If this is the first
|
||
time you are doing this, it may take some time.
|
||
|
||
.. code:: bash
|
||
|
||
git checkout central/default
|
||
|
||
If you are on a mac, you will need to have the Xcode build tools
|
||
installed. You can do this by either `installing
|
||
Xcode <https://developer.apple.com/xcode/>`__ or installing only the
|
||
tools from the command line by running ``xcode-select --install`` and
|
||
following the on screen instructions.
|
||
|
||
If you are on a newer mac with an Apple Silicon M2 or M3 processor,
|
||
you also need to install rosetta for backwards compatilibilty:
|
||
|
||
.. code:: bash
|
||
|
||
softwareupdate --install-rosetta
|
||
|
||
You will need to ``bootstrap`` for GeckoView/Firefox for Android. The easiest way is to run the following command:
|
||
|
||
.. code:: bash
|
||
|
||
./mach --no-interactive bootstrap --application-choice="GeckoView/Firefox for Android"
|
||
|
||
.. note::
|
||
|
||
- The ``--no-interactive`` argument will make ``bootstrap`` run start to finish without requiring any input from you. It will automatically accept any license agreements.
|
||
- The ``--application-choice="GeckoView/Firefox for Android"`` argument is needed when using ``--no-interactive`` so that "bootstrapping" is done for the correct application (instead of the default).
|
||
|
||
If you want to make all the selections yourself and/or read through the license agreements, you can simply run:
|
||
|
||
.. code:: bash
|
||
|
||
./mach bootstrap
|
||
|
||
You should then choose one the following options:
|
||
|
||
A- You will not change or debug any C++ code:
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Choose: ``3. GeckoView/Firefox for Android Artifact Mode``
|
||
|
||
Artifact mode downloads pre-built C++ components rather than building them locally, trading bandwidth for time.
|
||
(more on Artifact mode)
|
||
|
||
B- You intend to change or debug C++ code:
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Choose: ``4. GeckoView/Firefox for Android``
|
||
|
||
This will build GeckoView from scratch, and take more time than the option above.
|
||
|
||
Once ``./mach bootstrap`` is complete, it will automatically write the configuration into a new ``mozconfig`` file.
|
||
If you already have a ``mozconfig``, mach will instead output a new configuration that you should append to your existing file.
|
||
|
||
Build from the command line
|
||
---------------------------
|
||
.. _build_from_cmd_line:
|
||
|
||
In order to pick up the configuration changes we just made we need to
|
||
build from the command line. This will update generated sources, compile
|
||
native code, and produce GeckoView AARs and example and test APKs.
|
||
|
||
.. code:: bash
|
||
|
||
./mach build
|
||
|
||
Build Using Android Studio
|
||
--------------------------
|
||
.. _build_with_android_studio:
|
||
|
||
- Install `Android
|
||
Studio <https://developer.android.com/studio/install>`_.
|
||
- If on Windows, create a JAVA_HOME environment variable
|
||
and set it to the path of the Android Studio jbr. With the default installation locations, it is
|
||
``C:\Program Files\Android\Android Studio\jbr``.
|
||
- Choose File->Open from the toolbar
|
||
- Navigate to the root of your ``mozilla-central`` source directory and
|
||
click “Open”
|
||
- Click yes if it asks if you want to use the gradle wrapper.
|
||
|
||
- If the gradle sync does not automatically start, select File >
|
||
Sync Project with Gradle Files.
|
||
|
||
- Wait for the project to index and gradle to sync. Once synced, the
|
||
workspace will reconfigure to display the different projects.
|
||
|
||
- annotations contains custom Java annotations used inside GeckoView
|
||
- app contains geckoview build settings and omnijar. omnijar contains
|
||
the parts of Gecko and GeckoView that are not written in Java or Kotlin
|
||
- geckoview is the GeckoView project. Here is all the Java files
|
||
related to GeckoView
|
||
- geckoview_example is an example browser built using GeckoView.
|
||
|
||
Now you’re set up and ready to go.
|
||
|
||
**Important: at this time, building from Android Studio or directly from
|
||
Gradle does not (re-)compile native code, including C++ and Rust.** This
|
||
means you will need to run ``mach build`` yourself to pick up changes to
|
||
native code. `Bug
|
||
1509539 <https://bugzilla.mozilla.org/show_bug.cgi?id=1509539>`_ tracks
|
||
making Android Studio and Gradle do this automatically.
|
||
|
||
If you want set up code formatting for Kotlin, please reference
|
||
`IntelliJ IDEA configuration
|
||
<https://pinterest.github.io/ktlint/rules/configuration-intellij-idea/>`_.
|
||
|
||
Mobile Devices and Emulators
|
||
-------------------------------------
|
||
|
||
The default mozconfig file, located in the root directory of your ``mozilla-central`` contains
|
||
configurations for running mobile test devices in x86, arm64, and x86_64 architectures.
|
||
|
||
With the default mozconfig configurations, your machine's architecture should match the test device's
|
||
architecture. On newer Macs built on Apple Silicon, the mozconfig will likely not need to be changed
|
||
since it runs on arm64 and most mobile devices run on arm64.
|
||
|
||
If your machine has a different architecture compared to your physical test device, you should
|
||
uncomment the option matching your test device. Usually, this means uncommenting the arm64 option:
|
||
|
||
.. code:: bash
|
||
|
||
ac_add_options --target=aarch64
|
||
|
||
**Note:** When using an emulator, the mozconfig target configuration will most likely need to match
|
||
the architecture of your machine.
|
||
|
||
Custom AVD
|
||
~~~~~~~~~~
|
||
|
||
There are several reasons creating a custom AVD can be required, like e.g. the
|
||
default emulator setup might be too old for some tasks, and it might be
|
||
required to run some newer versions of the APIs or others.
|
||
|
||
Assuming the following environment variables are already set (versions/OS may change):
|
||
|
||
.. code:: bash
|
||
|
||
JAVA_HOME=$HOME/.mozbuild/jdk/jdk-17.0.12+7
|
||
ANDROID_HOME=$HOME/.mozbuild/android-sdk-linux
|
||
ANDROID_AVD_HOME=$HOME/.mozbuild/android-device/avd
|
||
PATH=$ANDROID_HOME/cmdline-tools/12.0/bin/:$PATH
|
||
|
||
You can identify usable packages already installed on your system via
|
||
|
||
.. code:: bash
|
||
|
||
sdkmanager --list
|
||
|
||
It will output list of available and installed packages. Packages of interest
|
||
are ``system-images`` and follow the rule ``system-images;android-API;pkg;arch`` where
|
||
|
||
- ``API`` is the `Android API level <https://developer.android.com/tools/releases/platforms>`_
|
||
- ``pkg`` is the set of package installed, e.g., ``default``, ``google_apis``, ``google_apis_playstore``
|
||
- the last one being the emulator architecture and usually stick to ``x86_64``.
|
||
|
||
The system image package you will use needs to be installed, so if it is not
|
||
already in the list above, please use (in this example it installs the package
|
||
for Android 14 (API level 34), ``default`` package and ``x86_64`` arch).
|
||
|
||
.. code:: bash
|
||
|
||
sdkmanager "system-images;android-34;default;x86_64"
|
||
|
||
Then the AVD can be created with:
|
||
|
||
.. code:: bash
|
||
|
||
avdmanager create avd --name android14-x86_64 --package "system-images;android-34;default;x86_64"
|
||
|
||
The name passed in argument can be whatever you want and the package is one of
|
||
the installed list. It is then required to modify entries within
|
||
`android_device.py <https://searchfox.org/mozilla-central/rev/d56687458d4e6e8882c4b740e78413a0f0a69d59/testing/mozbase/mozrunner/mozrunner/devices/android_device.py#101-175>`_ to be able to make use of ``mach android-emulator``,
|
||
changing the definition to match the name of the AVD created above. Example below:
|
||
|
||
.. code:: diff
|
||
|
||
diff --git a/testing/mozbase/mozrunner/mozrunner/devices/android_device.py b/testing/mozbase/mozrunner/mozrunner/devices/android_device.py
|
||
index 4f883261d45c1..07f91c1ab800e 100644
|
||
--- a/testing/mozbase/mozrunner/mozrunner/devices/android_device.py
|
||
+++ b/testing/mozbase/mozrunner/mozrunner/devices/android_device.py
|
||
@@ -151,7 +151,7 @@ AVD_DICT = {
|
||
),
|
||
"x86_64": AvdInfo(
|
||
"Android x86_64",
|
||
- "mozemulator-x86_64",
|
||
+ "android14-x86_64",
|
||
[
|
||
"-skip-adb-auth",
|
||
"-verbose",
|
||
|
||
Once the avd is created, it can be customized by changing the ``config.ini``
|
||
file (located under ``$ANDROID_AVD_HOME/<avd-name>.avd/``, e.g.,
|
||
``$HOME/.mozbuild/android-device/avd/android14-x86_64/config.ini`` in the above
|
||
example). It is recommended to enable physical keyboard by changing the value
|
||
``hw.keyboard`` to ``yes`` (otherwise only virtual keyboard input will work).
|
||
|
||
Custom mozconfig with Android Studio
|
||
------------------------------------
|
||
|
||
Out of the box, Android Studio will use the default mozconfig file, normally
|
||
located at ``mozconfig`` in the root directory of your ``mozilla-central``
|
||
checkout.
|
||
|
||
To make Android Studio use a mozconfig in a custom location, you can add the
|
||
following to your ``local.properties``:
|
||
|
||
::
|
||
|
||
mozilla-central.mozconfig=relative/path/to/mozconfig
|
||
|
||
Note that, when running mach from the command line, this value will be ignored,
|
||
and the mozconfig from the mach environment will be used instead.
|
||
|
||
To override the mozconfig used by mach, you can use the `MOZCONFIG` environment
|
||
variable, for example:
|
||
|
||
::
|
||
|
||
MOZCONFIG=debug.mozconfig ./mach build
|
||
|
||
Project-Specific Instructions
|
||
------------------------------
|
||
|
||
Now that you're prepared and set up, you can access specific project instructions below:
|
||
|
||
- GeckoView: :ref:`Contributing to GeckoView <Contributing to GeckoView>`
|
||
- Android Components: `Mozilla Android Components <https://mozac.org/>`_
|
||
- Frontend: :ref:`Building Firefox for Android <Building Firefox for Android>`
|