Bug 1889805: Move the monorepo setup doc into the tree r=owlish,sylvestre

Differential Revision: https://phabricator.services.mozilla.com/D206974

docs/contributing/contribution_quickref.rst

@@ -77,7 +77,7 @@ To Setup Firefox for Android
     $ curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O
     $ python3 bootstrap.py
 
-More information on :ref:`building Firefox for Android <fenix-contributor-guide>`
+More information on :ref:`building Firefox for Android <Firefox for Android>`
 
 To set up your editor
 ---------------------

mobile/android/docs/fenix.rst

@@ -3,79 +3,15 @@
 Building Firefox for Android
 ============================
 
-1. Cloning the repo
+Run Fenix using command line
--------------------
+----------------------------
 
-First, you'll want to `set up your machine to build Firefox </setup>`_.
+As a first step, you need to set up your development environment using the instruction :ref:`here <firefox_for_android>`.
-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
+Run Fenix or other Android projects using command line
-------------
-
-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
-
-.. 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
-
-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_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).

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

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

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
+Firefox for Android consists of three layers:
-which are still useful for other projects
 
-.. toctree::
+- GeckoView: This is a library that brings the Gecko API to Android.
-   :maxdepth: 1
 
-   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>`

mobile/android/docs/overview.rst

@@ -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>`

mobile/android/fenix/docs/index.rst

@@ -15,7 +15,7 @@ Specific documentation on a few topics is available at:
    Creating a release branch<Creating-a-release-branch.md>
    Data practises <Data-Practices.md>
    Development Test Plan <Development-Test-Plan.md>
-   Fennec Migration <Fennec-Migration.md>
+   Fennec Legacy: Migration <Fennec-Migration.md>
    Firebase Cloud Messaging for WebPush <Firebase-Cloud-Messaging-for-WebPush.md>
    Firefox for Android Team Processes <Firefox-for-Android-Team-Processes.md>
    Guide to merging contributor PRs <Guide-to-merging-contributor-PRs.md>