From 20de7e472de3243e495e910d86a25d3cfd28ea4b Mon Sep 17 00:00:00 2001 From: Thom Chiovoloni Date: Fri, 26 Apr 2019 09:30:14 -0700 Subject: [PATCH] Document the local publish process (#1082) --- .../locally-published-components-in-fenix.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/howtos/locally-published-components-in-fenix.md diff --git a/docs/howtos/locally-published-components-in-fenix.md b/docs/howtos/locally-published-components-in-fenix.md new file mode 100644 index 000000000..347cbc906 --- /dev/null +++ b/docs/howtos/locally-published-components-in-fenix.md @@ -0,0 +1,118 @@ +# Using locally-published components in Fenix + +Note: This is a bit tedious, so feel free to ask in slack if there's a better +way to test things. At the moment substitution is broken, so this is necessary +in more cases than we'd like. + +Note 2: This is fenix-specific only in that some links on the page go to the +`mozilla-mobile/fenix` repository, and that I'm describing `fenix`, however +these steps should work for e.g. `reference-browser`, as well. (Same goes for +lockwise, or any other consumer of our components, but they may use a different +structure -- lockwise has no Dependencies.kt, for example) + +1. If you've added a new project to the megazord: + 1. In the gradle plugin's [`AppServicesExtension.kt`](AppServicesExtension), + add the new component to the relevant megazord. Note: you may have + already done this. + 2. In the gradle plugin's [`build.gradle`](plugin-build-gradle), change + `ext.plugin_version` to end with `-TESTING$N` + 1 where `$N` is some number + that you haven't used for this before. + + Example: `ext.plugin_version = '0.4.4-TESTING3'` + 3. Inside the `gradle-plugin` directory run `./gradlew publishToMavenLocal`. + + It's important that you do this from inside the plugin's directory, + e.g. cwd must be `path/to/application-services/gradle-plugin`! + +2. Inside the `application-services` repository root: + 1. In [`.buildconfig-android.yml`](app-services-yaml), change + `libraryVersion` to end in `-TESTING$N` 1, + where `$N` is some number that you haven't used for this before. + + Example: `libraryVersion: 0.27.0-TESTING3` + 2. Check your `local.properties` file, and add `rust.targets=x86` if you're + testing on the emulator, `rust.targets=arm` if you're testing on 32-bit + arm (arm64 for 64-bit arm, etc). This will make the build that's done in + the next step much faster. + 3. Run `./gradlew publishToMavenLocal`. This may take between 5 and 10 minutes. + +3. Inside the `android-components` repository root: + 1. In [`.buildconfig.yml`](android-components-yaml), change + `componentsVersion` to end in `-TESTING$N` 1, + where `$N` is some number that you haven't used for this before. + + Example: `componentsVersion: 0.51.0-TESTING3` + 2. Inside [`buildSrc/src/main/java/Dependencies.kt`](android-components-deps), + change `mozilla_appservices` to reference the `libraryVersion` you + published in step 2 part 1. + + Example: `const val mozilla_appservices = "0.27.0-TESTING3"` + + 3. Inside [`build.gradle`](android-components-build-gradle), add + `mavenLocal()` inside `allprojects { repositories { } }`. + + 4. Inside the android-component's `local.properties` file, ensure + `substitutions.application-services.dir` is *NOT* set. + + 5. Run `./gradlew publishToMavenLocal`. + +4. Inside the `fenix` repository root: + 1. Inside [`build.gradle`](fenix-build-gradle-1), add + `mavenLocal()` inside `allprojects { repositories { } }`. + 1. If you added a new project to the megazord (e.g. you went through the + parts of step 1) you must also add `mavenLocal()` to + [`buildscript { ... dependencies { }}`](fenix-build-gradle-2) + + 2. Inside fenix's `local.properties` file, ensure + `substitutions.application-services.dir` is *NOT* set. + + 3. Inside [`buildSrc/src/main/java/Dependencies.kt`](fenix-deps), change + `mozilla_android_components` to the version you defined in step 3 part 1. + + Example: `const val mozilla_android_components = "0.51.0-TESTING3"` + 1. If you added a new project to the megazord (e.g. you went through the + parts of step 1) you must also change `appservices_gradle_plugin` to + the version you defined in step 1 part 1. + + Example: `const val appservices_gradle_plugin = "0.4.4-TESTING3"` + 2. If there are any direct dependencies on application services (at the + moment there are not, but there have been in the past and may be in + the future), change it's version here to the one defined in step 2 + part 1. + +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 repos, unless you know you need to + not be. +3. This omits the steps if changes needed because, e.g. application-services + 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 application-services changelog). +4. Ask in #rust-components slack (or #sync on mozilla IRC if you are an + especially brave external contributor) if you get stuck. + +--- + +[1]: It doesn't have to start with `-TESTING`, it only needs +to have the format `-someidentifier`. `-SNAPSHOT$N` is also very common to use, +however without the numeric suffix, this has specific meaning to gradle, so we +avoid it. Additionally, while the `$N` we have used in our running example has +matched (e.g. all of the identifiers ended in `-TESTING3`, this is not required, +so long as you match everything up correctly at the end. This can be tricky, so +I always try to use the same number). + +[AppServicesExtension]: https://github.com/mozilla/application-services/blob/594f4e3f6c190bc5a6732f64afc573c09020038a/gradle-plugin/src/main/kotlin/mozilla/appservices/AppServicesExtension.kt#L21-L55 +[plugin-build-gradle]: https://github.com/mozilla/application-services/blob/594f4e3f6c190bc5a6732f64afc573c09020038a/gradle-plugin/build.gradle#L3 +[app-services-yaml]: https://github.com/mozilla/application-services/blob/594f4e3f6c190bc5a6732f64afc573c09020038a/.buildconfig-android.yml#L1 +[android-components-yaml]: https://github.com/mozilla-mobile/android-components/blob/b98206cf8de818499bdc87c00de942a41f8aa2fb/.buildconfig.yml#L1 +[android-components-deps]: https://github.com/mozilla-mobile/android-components/blob/b98206cf8de818499bdc87c00de942a41f8aa2fb/buildSrc/src/main/java/Dependencies.kt#L37 +[android-components-build-gradle]: https://github.com/mozilla-mobile/android-components/blob/b98206cf8de818499bdc87c00de942a41f8aa2fb/build.gradle#L28 +[fenix-build-gradle-1]: https://github.com/mozilla-mobile/fenix/blob/f897c2e295cd1b97d4024c7a9cb45dceb7a2fa89/build.gradle#L26 +[fenix-build-gradle-2]: https://github.com/mozilla-mobile/fenix/blob/f897c2e295cd1b97d4024c7a9cb45dceb7a2fa89/build.gradle#L6 +[fenix-deps]: https://github.com/mozilla-mobile/fenix/blob/f897c2e295cd1b97d4024c7a9cb45dceb7a2fa89/buildSrc/src/main/java/Dependencies.kt#L28