diff options
Diffstat (limited to 'mobile/android/docs')
| -rw-r--r-- | mobile/android/docs/fenix.rst | 95 | ||||
| -rw-r--r-- | mobile/android/docs/geckoview/contributor/contributing-to-mc.rst | 1 | ||||
| -rw-r--r-- | mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst | 136 | ||||
| -rw-r--r-- | mobile/android/docs/index.rst | 176 | ||||
| -rw-r--r-- | mobile/android/docs/overview.rst | 26 | ||||
| -rw-r--r-- | mobile/android/docs/shared/android/device_testing.md | 2 |
6 files changed, 200 insertions, 236 deletions
diff --git a/mobile/android/docs/fenix.rst b/mobile/android/docs/fenix.rst index 56dd6eec8d..c22e55cc28 100644 --- a/mobile/android/docs/fenix.rst +++ b/mobile/android/docs/fenix.rst @@ -3,79 +3,15 @@ Building Firefox for Android ============================ -1. Cloning the repo -------------------- - -First, you'll want to `set up your machine to build Firefox </setup>`_. -Follow the instructions there, choosing "GeckoView/Firefox for Android" or "GeckoView/Firefox for Android Artifact Mode" as -the bootstrap option. Please refer to the "Bootstrap" section below to understand better those options. - -Once you're set up and have a GeckoView build from the above, please -continue with the following steps. - -2. Bootstrap ------------- - -If you intend to work mainly on GeckoView, you can find more information `here <geckoview/contributor/for-gecko-engineers.html>`_. - -Bootstrap configures everything for GeckoView and Fenix (Firefox for Android) development. - -.. code-block:: shell - - ./mach bootstrap - -You should then choose one the following options: - -A- You will not change any GeckoView code, or only Java and JS code on GeckoView: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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 GeckoView 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. - -3. Build GeckoView ------------------- - -You can now build GeckoView, using +Run Fenix using command line +---------------------------- -.. code-block:: shell - - ./mach build - -.. _build_fenix: - -4. Build Fenix or other Android projects Using Android Studio -------------------------------------------------------------- - -1. **You will only work on one of those projects: Fenix, Focus, Android Components** - -Open your project's folder on Android Studio. You can find it under: ``[your mozilla-central path]/mobile/android`` - -After ``./mach build`` completed successfully, you will need to use `File/Sync Project with Gradle files`. - -2. **You will work on GeckoView only, or GeckoView in integration with the other projects** - -Open the root folder (meaning the ``mozilla-central`` folder you just checked out) on Android Studio. -From there, you should be able to choose the project you want to build. - -.. image:: img/android-studio-build-toolbar.png - :alt: Screenshot Android Studio's toolbar, showing the projects that can be built +As a first step, you need to set up your development environment using the instruction :ref:`here <firefox_for_android>`. -After ``./mach build`` completed successfully, you will need to do a full Gradle Sync. -3. Run Fenix or other Android projects using command line +Run Fenix or other Android projects using command line --------------------------------------------------------- +.. _run_fenix_from_commandline: From the root mozilla-central directory, you can run an emulator with the following command: @@ -83,7 +19,6 @@ From the root mozilla-central directory, you can run an emulator with the follow ./mach android-emulator - From the `mobile/android/fenix` working directory, build, install and launch Fenix with: .. code-block:: shell @@ -92,3 +27,23 @@ From the `mobile/android/fenix` working directory, build, install and launch Fen export ANDROID_HOME=$HOME/.mozbuild/android-sdk-<os_name> ./gradlew :app:installFenixDebug "$ANDROID_HOME/platform-tools/adb" shell am start -n org.mozilla.fenix.debug/org.mozilla.fenix.debug.App + + +Run Fenix tests +------------------- + +You can run tests via all the normal routes: + +- For individual test files, click the little green play button at the top +- For a module/component: + + - Right click in project explorer → run all tests + - Select from gradle tasks window + - On command line: ``./gradlew :$module:$variant`` e.g. ``./gradlew :feature-downloads:testDebugUnitTest`` + +If you see the error "Test events were not received", check your top level folder - this happens if you try and run tests in Android Components from ``mozilla-unified/mobile/android/fenix/``. +To build tests for Android Components you need to be using the ``build.gradle`` in ``mozilla-unified/mobile/android/android-components/``. + +If after running tests on your Android device, you can no longer long press, this is because the connected Android tests mess around with your phone’s accessibility settings. +They set the long press delay to 3 seconds, which is an uncomfortably long time. +To fix this, go to Settings → Accessibility → Touch and hold delay, and reset this to default or short (depends on manufacturer). diff --git a/mobile/android/docs/geckoview/contributor/contributing-to-mc.rst b/mobile/android/docs/geckoview/contributor/contributing-to-mc.rst index ee4f5be877..fa92a3466d 100644 --- a/mobile/android/docs/geckoview/contributor/contributing-to-mc.rst +++ b/mobile/android/docs/geckoview/contributor/contributing-to-mc.rst @@ -11,6 +11,7 @@ Table of contents Submitting a patch to Firefox using Git. ======================================== +.. _contribute_with_git: This guide will take you through submitting and updating a patch to ``mozilla-central`` as a git user. You need to already be `set up to use diff --git a/mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst b/mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst index 140dd62784..d111f54b01 100644 --- a/mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst +++ b/mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst @@ -19,141 +19,13 @@ project. If you want to get started using GeckoView in your app then you should refer to the `wiki <https://wiki.mozilla.org/Mobile/GeckoView#Get_Started>`_. -Get set up with Mozilla Central -------------------------------- - -The GeckoView codebase is part of the main Firefox tree and can be found -in ``mozilla-central``. You will need to get set up as a contributor to -Firefox in order to contribute to GeckoView. To get set up with -``mozilla-central``, follow the `Quick Start Guide for Git -Users <mc-quick-start.html>`_, or the `Contributing to the Mozilla code -base <https://firefox-source-docs.mozilla.org/setup/contributing_code.html>`_ -guide and `Firefox Contributors’ Quick Reference -<https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html>`_ -for Mercurial users. - -Once you have a copy of ``mozilla-central``, you will need to build -GeckoView. - -Bootstrap Gecko ---------------- - -Bootstrap configures everything for GeckoView and Fennec (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. - -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 - - Select ``4. GeckoView/Firefox for Android`` when prompted and respond to any subsequent prompts as they appear. - -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 new configuration -that you should append to your existing file. - -Build from the command 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 --------------------------- - -- Install `Android - Studio <https://developer.android.com/studio/install>`_. -- 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. - - |alt text 1| - -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/>`_. - -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 - Performing a bug fix -------------------- -One you have got GeckoView building and running, you will want to start +As a first step, you need to set up :ref:`mozilla-central <mozilla-central-setup>`, +and :ref:`Bootstrap <bootstrap-setup>` and build the project. + +Once you have got GeckoView building and running, you will want to start contributing. There is a general guide to `Performing a Bug Fix for Git Developers <contributing-to-mc.html>`_ for you to follow. To contribute to GeckoView specifically, you will need the following additional diff --git a/mobile/android/docs/index.rst b/mobile/android/docs/index.rst index 232363b934..8fc986d19a 100644 --- a/mobile/android/docs/index.rst +++ b/mobile/android/docs/index.rst @@ -1,10 +1,172 @@ -Fennec Legacy -============= +Firefox for Android +=================== +.. _firefox_for_android: -This collection of linked pages contains old fennec documentation -which are still useful for other projects +Firefox for Android consists of three layers: -.. toctree:: - :maxdepth: 1 +- GeckoView: This is a library that brings the Gecko API to Android. - mma +- 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:`Mozilla Central Quick Start <Mozilla Central Quick Start>` +- :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>`_. +- 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/>`_. + +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>` diff --git a/mobile/android/docs/overview.rst b/mobile/android/docs/overview.rst deleted file mode 100644 index 97f6d19541..0000000000 --- a/mobile/android/docs/overview.rst +++ /dev/null @@ -1,26 +0,0 @@ -Firefox for Android -=================== - -GeckoView ---------- - -GeckoView is a full-featured webview that can be embedded into Android apps using Gecko as the -rendering engine. - -:ref:`Read more <GeckoView>` - -Android Components ------------------- - -Android components is a collection of components useful for building web browser applications on -Android using GeckoView as the rendering engine. - -`Read more <https://mozac.org/>`_ - -Frontend --------- - -The frontend for Firefox for Android is built as a native Android UI in Kotlin and makes use of -Android Components and GeckoView. - -:ref:`Read more <Building Firefox for Android>` diff --git a/mobile/android/docs/shared/android/device_testing.md b/mobile/android/docs/shared/android/device_testing.md index f2e89b1a9b..ddf1c6c601 100644 --- a/mobile/android/docs/shared/android/device_testing.md +++ b/mobile/android/docs/shared/android/device_testing.md @@ -18,7 +18,7 @@ By default the Fenix CI runs tests using virtual devices on `x86`. That's faster when the host is also a `x86(_64)` system, but most physical devices use the Arm platform. So first we need to instruct it to run tests on Arm. -Which platform to test on is defined in [`taskcluster/ci/ui-test/kind.yml`](https://github.com/mozilla-mobile/fenix/blob/58e12b18e6e9f4f67c059fe9c9bf9f02579a55db/taskcluster/ci/ui-test/kind.yml#L65). +Which platform to test on is defined in [`taskcluster/kinds/ui-test/kind.yml`](https://searchfox.org/mozilla-central/source/taskcluster/kinds/ui-test/kind.yml). Find the line where it downloads the `target.apk` produced in a previous step and change it from `x86` to `arm64-v8a`: ```patch |