forked from mirrors/gecko-dev
Bug 1889805: Move the monorepo setup doc into the tree r=owlish,sylvestre
Differential Revision: https://phabricator.services.mozilla.com/D206974
This commit is contained in:
gela
parent
dd19a2b81a
commit
58465b2927
7 changed files with 201 additions and 237 deletions
|
|
@ -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
|
||||
---------------------
|
||||
|
|
|
|||
|
|
@ -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>`_.
|
||||
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.
|
||||
As a first step, you need to set up your development environment using the instruction :ref:`here <firefox_for_android>`.
|
||||
|
||||
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
|
||||
|
||||
.. 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 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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>`
|
||||
|
|
|
|||
|
|
@ -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>`
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue