You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by er...@apache.org on 2025/07/14 13:20:43 UTC

(cordova-docs) branch master updated: doc(android): refactor build-extras.gradle (#1425)

This is an automated email from the ASF dual-hosted git repository.

erisu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git


The following commit(s) were added to refs/heads/master by this push:
     new 6c7f4e24eb doc(android): refactor build-extras.gradle (#1425)
6c7f4e24eb is described below

commit 6c7f4e24ebe63113123c4c4ad0f1aab5ba3cc1bc
Author: エリス <er...@users.noreply.github.com>
AuthorDate: Mon Jul 14 22:20:37 2025 +0900

    doc(android): refactor build-extras.gradle (#1425)
---
 www/docs/en/dev/guide/platforms/android/index.md | 33 ++++++++++++++++--------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/www/docs/en/dev/guide/platforms/android/index.md b/www/docs/en/dev/guide/platforms/android/index.md
index e8fd35213c..4374b703ca 100644
--- a/www/docs/en/dev/guide/platforms/android/index.md
+++ b/www/docs/en/dev/guide/platforms/android/index.md
@@ -477,7 +477,7 @@ You can set these properties in one of four ways:
     cdvMinSdkVersion=20
     ```
 
-- [Extending `build.gradle`](#extending-buildgradle) with the `build-extras.gradle file
+- [Extending `build.gradle`](#extending-buildgradle) with the `build-extras.gradle` file
 
     Create a file named `build-extras.gradle` in the directory `<project-root>/platforms/android/app` with the contents such as:
 
@@ -487,14 +487,31 @@ You can set these properties in one of four ways:
 
 The latter two options both involve including an extra file in your Android platform folder. In general, it is discouraged to edit the contents of this folder because it is easy for those changes to be lost or overwritten. Instead, these files should be copied into the folder as part of the build command by using the `before_build` [hook script](../../appdev/hooks/index.html).
 
-#### Extending build.gradle
+#### Extending `build.gradle`
 
-If you need to customize the `build.gradle` file, rather than edit it directly, it is recommended to create a sibling file named `build-extras.gradle`. This file will be included by the main `build.gradle` script when present. This file must be placed in the `app` folder of the Android's platform directory (`<your-project>/platforms/android/app`). It is recommended to use the `before_build` [hook script](../../appdev/hooks/index.html) to copy this file over.
+To customize the `app/build.gradle` file without modifying it directly, create a sibling file named `build-extras.gradle`.
 
-Here's an example:
+If this file exists in the `<your-project>/platforms/android/app` directory during the build process, it will be automatically applied by the app's `build.gradle` script.
+
+To automate placing `build-extras.gradle` in the correct location, use the `<resource-file>` element in `config.xml`.
+
+In the example below, the source `build-extras.gradle` is saved in a `res/` directory in the project root. It is then declared in `config.xml` to copy it to the appropriate target location:
+
+```xml
+<resource-file src="res/build-extras.gradle" target="app/build-extras.gradle"/>
+```
+
+**Note:** The `res/` directory name is just an example. You can use any directory and file name you prefer. However, it's recommended not to place the file inside the `platforms`, `plugins`, or `www` directories. Also, make sure the `target` path matches exactly as shown in the example.
+
+**Note:** Plugin developers can also include a `build-extras.gradle` file, but should use the `<framework>` element in `plugin.xml` instead of `<resource-file>`:
+
+```xml
+<framework src="build-extras.gradle" custom="true" type="gradleReference" />
+```
+
+**Example `build-extras.gradle`:**
 
 ```groovy
-// Example build-extras.gradle
 // This file is included at the beginning of `build.gradle`
 
 // special properties (see `build.gradle`) can be set and overwrite the defaults
@@ -518,12 +535,6 @@ ext.postBuildExtras = {
 }
 ```
 
-Note that plugins can also include `build-extras.gradle` files via:
-
-```xml
-<framework src="some.gradle" custom="true" type="gradleReference" />
-```
-
 #### Configuring Gradle JVM Args
 
 To change the Gradle JVM args, the `--jvmargs` flag can be used with both Cordova's `build` and `run` commands. This is mostly useful for controlling how much memory gradle is allowed to use during the build process. It is recommended to allow at least 2048 MB.


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org