From d5adf4d3b2a58a3ef1603133498d49d32dd3a46b Mon Sep 17 00:00:00 2001 From: Jan-Erik Rediger Date: Fri, 3 Jan 2025 11:27:12 +0100 Subject: [PATCH] Rewrite docs on how to use local glean plugin in m-c [doc only] --- .dictionary | 3 +- docs/dev/SUMMARY.md | 4 +- .../development-with-android-components.md | 86 ------------------- .../development-with-mozilla-central.md | 52 +++++++++++ docs/dev/android/gradle-plugin-in-mc.md | 35 ++++++++ .../locally-published-components-in-fenix.md | 36 -------- 6 files changed, 91 insertions(+), 125 deletions(-) delete mode 100644 docs/dev/android/development-with-android-components.md create mode 100644 docs/dev/android/development-with-mozilla-central.md create mode 100644 docs/dev/android/gradle-plugin-in-mc.md delete mode 100644 docs/dev/android/locally-published-components-in-fenix.md diff --git a/.dictionary b/.dictionary index e9c78ca5b7..01ed0bd70c 100644 --- a/.dictionary +++ b/.dictionary @@ -1,4 +1,4 @@ -personal_ws-1.1 en 294 utf-8 +personal_ws-1.1 en 295 utf-8 AAR AARs ABI @@ -18,6 +18,7 @@ CODEOWNERS Cartfile CircleCI Ciufo +Codebase DNS DOM Datetime diff --git a/docs/dev/SUMMARY.md b/docs/dev/SUMMARY.md index 23b729d0ea..1e74af7f8a 100644 --- a/docs/dev/SUMMARY.md +++ b/docs/dev/SUMMARY.md @@ -11,8 +11,8 @@ - [Setup Build Environment](android/setup-android-build-environment.md) - [Android SDK/NDK versions](android/sdk-ndk-versions.md) - [Logging](android/logging.md) - - [Development with android-components](android/development-with-android-components.md) - - [Locally-published components in Fenix](android/locally-published-components-in-fenix.md) + - [Development with mozilla-central](android/development-with-mozilla-central.md) + - [Replacing the Glean Gradle plugin in mozilla-central](android/gradle-plugin-in-mc.md) - [Substituting glean_parser](android/glean-parser-substitution.md) - [iOS bindings](ios/index.md) - [Setup Build Environment](ios/setup-ios-build-environment.md) diff --git a/docs/dev/android/development-with-android-components.md b/docs/dev/android/development-with-android-components.md deleted file mode 100644 index 6510dc14eb..0000000000 --- a/docs/dev/android/development-with-android-components.md +++ /dev/null @@ -1,86 +0,0 @@ -# Working on unreleased Glean code in android-components - -This is a companion to the [equivalent instructions for the android-components repository](https://mozilla-mobile.github.io/android-components/contributing/testing-components-inside-app). - -Modern Gradle supports [composite builds](https://docs.gradle.org/current/userguide/composite_builds.html), which allows to substitute on-disk projects for binary publications. Composite builds transparently accomplish what is usually a frustrating loop of: -1. change library -1. publish library snapshot to the local Maven repository -1. consume library snapshot in application - -## Preparation - -Clone the Glean SDK and android-components repositories: - -```sh -git clone https://github.com/mozilla/glean -git clone https://github.com/mozilla-mobile/firefox-android -``` - -## Cargo build targets - -By default when building Android Components using gradle, the rust-android plugin will compile Glean for every possible platform, -which might end up in build failures. -You can customize which targets are built in `glean/local.properties` -([more information](https://github.com/ncalexan/rust-android-gradle/blob/HEAD/README.md#specifying-local-targets)): - -``` -# For physical devices: -rust.targets=arm - -# For unit tests: -# rust.targets=darwin # Or linux-*, windows-* (* = x86/x64) - -# For emulator only: -rust.targets=x86 -``` - -## Substituting projects - -android-components has custom build logic for dealing with composite builds, -so you should be able to configure it by simply adding the path to the Glean repository in the correct `local.properties` file: - -In `firefox-android/android-components/local.properties`: - -```groovy -autoPublish.glean.dir=../glean -``` - -This will auto-publish Glean SDK changes to a local repository and consume them in android-components. - -### Replacing the Glean Gradle plugin - -> **Note**: If you only need to replace the `glean_parser` used in the build see [Substituting `glean_parser`](glean-parser-substitution.md). -> This is only necessary if you changed `GleanGradlePlugin.groovy`. - -If you need to replace the Glean Gradle Plugin used by other components within Android Components, follow these steps: - -1. In your Glean repository increment the version number in `.buildconfig.yml` - - ```yaml - libraryVersion: 60.0.0 - ``` - -2. Build and publish the plugin locally: - - ``` - ./gradlew publishToMavenLocal - ``` - -3. In the Android Components repository change the required Glean version `buildSrc/src/main/java/Dependencies.kt`: - - ```kotlin - const val mozilla_glean = "60.0.0" - ``` - -4. In the Android Components repository add the following at the top of the `settings.gradle` file: - - ```gradle - pluginManagement { - repositories { - mavenLocal() - gradlePluginPortal() - } - } - ``` - -Building any component will now use your locally published Glean Gradle Plugin (and Glean SDK). diff --git a/docs/dev/android/development-with-mozilla-central.md b/docs/dev/android/development-with-mozilla-central.md new file mode 100644 index 0000000000..feeb126a7d --- /dev/null +++ b/docs/dev/android/development-with-mozilla-central.md @@ -0,0 +1,52 @@ +# Working on unreleased Glean code in mozilla-central + +> **Note**: This guide is for mozilla-central Android builds. If you only need to replace the Glean Rust parts, refer to [Developing with a local Glean build](https://firefox-source-docs.mozilla.org/toolkit/components/glean/dev/local_glean.html) in the Firefox Source Docs. + +> **Note**: This guide only refers to building Fenix. It should work similarly for Focus Android. + +## Preparation + +This guide assumes you already have are setup to build the mozilla-central repository for Android. +Refer to [Getting Set Up To Work On The Firefox Codebase](https://firefox-source-docs.mozilla.org/setup/index.html) for more. + +Clone the Glean SDK repositories: + +```sh +git clone https://github.com/mozilla/glean +``` + +## Cargo build targets + +By default when building Fenix using gradle, the rust-android plugin will compile Glean for every possible platform, +which might end up in build failures. +You can customize which targets are built in `glean/local.properties` +([more information](https://github.com/ncalexan/rust-android-gradle/blob/HEAD/README.md#specifying-local-targets)): + +``` +# For physical devices: +rust.targets=arm + +# For unit tests: +# rust.targets=darwin # Or linux-*, windows-* (* = x86/x64) + +# For emulator only: +rust.targets=x86 +``` + +## Substituting projects + +Fenix has custom build logic for dealing with composite builds, +so you should be able to configure it by simply adding the path to the Glean repository in the correct `local.properties` file: + +In `mozilla-central/mobile/android/fenix/local.properties`: + +```groovy +autoPublish.glean.dir=../../../../glean +``` + +Make sure to use the correct path pointing to your Glean checkout. + +> **Note**: This substitution-based approach will not work for testing updates to the Glean Gradle plugin or `glean_parser` as shipped in the Glean Gradle Plugin. +> +> See [Replacing the Glean Gradle plugin in mozilla-central](android/gradle-plugin-in-mc.md). +> For replacing `glean_parser` in a local build, see [Substituting `glean_parser`](glean-parser-substitution.md). diff --git a/docs/dev/android/gradle-plugin-in-mc.md b/docs/dev/android/gradle-plugin-in-mc.md new file mode 100644 index 0000000000..39752e32db --- /dev/null +++ b/docs/dev/android/gradle-plugin-in-mc.md @@ -0,0 +1,35 @@ +# Replacing the Glean Gradle plugin in mozilla-central + +> **Note**: If you only need to replace the `glean_parser` Python parts used in the build see [Substituting `glean_parser`](glean-parser-substitution.md). +> The approached documented in this chapter is only necessary if you changed `GleanGradlePlugin.groovy`. + +If you need to replace the Glean Gradle Plugin used by any component in mozilla-central, follow these steps: + +1. In your Glean repository increment the version number in `.buildconfig.yml` to something unused: + + ```yaml + libraryVersion: 70.0.0 + ``` + +1. Build the Glean Gradle plugin and publish the plugin locally: + + ``` + ./gradlew glean-gradle-plugin:publishToMavenLocal + ``` + +1. In your `mozilla-central` checkout, add the following line in `mobile/android/fenix/settings.gradle` file in the `pluginManagement` block: + + ```gradle + mavenLocal() + ``` + +1. Use the new version number where the plugin is imported in `mobile/android/fenix/build.gradle`: + + ``` + classpath "org.mozilla.telemetry:glean-gradle-plugin:70.0.0" + ``` + + This might need to be applied to the top-level `build.gradle` and other `build.gradle` files under `mobile/android` to apply to all components. + + +Building Fenix will now use your locally published Glean Gradle Plugin. diff --git a/docs/dev/android/locally-published-components-in-fenix.md b/docs/dev/android/locally-published-components-in-fenix.md deleted file mode 100644 index 6c3341fc04..0000000000 --- a/docs/dev/android/locally-published-components-in-fenix.md +++ /dev/null @@ -1,36 +0,0 @@ -# Using locally-published Glean in Fenix - -> **Note**: this substitution-based approach will not work for testing updates to `glean_parser` as shipped in the Glean Gradle Plugin. -> For replacing `glean_parser` in a local build, see [Substituting `glean_parser`](glean-parser-substitution.md). - -## Preparation - -Clone the Glean SDK, android-components and Fenix repositories: - -```sh -git clone https://github.com/mozilla/glean -git clone https://github.com/mozilla-mobile/fenix -``` - -## Substituting projects - -android-components has custom build logic for dealing with composite builds, -so you should be able to configure it by simply adding the path to the Glean repository in the correct `local.properties` file: - -In `fenix/local.properties`: - -```groovy -autoPublish.glean.dir=../glean -``` - -This will auto-publish Glean SDK changes to a local repository and consume them in Fenix. -You should now be able to build and run Fenix (assuming you could before all this). - -## Caveats - -1. This assumes you have followed the [Android/Rust build setup](setup-android-build-environment.md) -2. Make sure you're fully up to date in all repositories, unless you know you need to not be. -3. This omits the steps if changes needed because, e.g. Glean made a breaking change to an API used in android-components. - These should be understandable to fix, you usually should be able to find a PR with the fixes somewhere in the android-component's list of pending PRs - (or, failing that, a description of what to do in the Glean changelog). -4. Ask in the [#glean channel on chat.mozilla.org](https://chat.mozilla.org/#/room/#glean:mozilla.org).