[Android] Improve gradle build flow by automatically setting up the build directory

[m4gr3d]

This PR updates the setup of the gradle build environment as follow:

• If it doesn't already exist, the gradle build directory will be automatically created and set up the first time a project is exported.
• A new editor setting, export/android/build/automatically_delete_build_directory, is added to control whether an existing but invalid build directory (e.g. mismatched versions due to editor upgrade) should be automatically deleted and reinstalled on build.

• If the export/android/build/automatically_delete_build_directory editor setting is disabled, then the build fails with an error prompting the user to manually delete the existing invalid build directory.

• The error is also shown in the project export dialog when an existing build directory is invalid

• The Install Android Build Template menu option is hidden by default but can be restored via the export/android/build/show_install_android_source_button editor setting.

[syntaxerror247]

I have a few concerns here:

1. Users can extend the build directory with custom code and files, such as notification icons, modifying gradle dependencies, and other changes. If we auto delete the build directory when exporting from a newer version, users could accidentally lose those modifications. So instead, I think we should only install the build template when it is not already present. If there is a version mismatch, we should show a dialog with two actions: Open the existing build directory, so users can review or copy their modifications if needed. And delete and reinstall the gradle template.

2. We should also keep the Install Android Build Template menu option. When the Android export template is not present or downloaded, it currently provides an option to Install from a file.
   Removing this dialog would remove the ability to manually install a build template.

[m4gr3d]

We should also keep the Install Android Build Template menu option. When the Android export template is not present or downloaded, it currently provides an option to Install from a file.
Removing this dialog would remove the ability to manually install a build template.

Manually setting up a build template is still possible either through the gradle_build/android_source_template export option, or through the Manage export template dialog and window.

The pattern being observed is to improve the build flow by reducing the number of clicks required for setup. There are in general two scenarios a user may be going through, and both are addressed by the new flow:

• Scenario 1: user is using the default templates.

  • User either first launch the Manage export template window, and download the templates from there. Then user creates an Android export preset, select gradle_build/use_gradle_build, and is able to start exporting right away without any further clicks.
  • Or user first creates an Android export preset and select gradle_build/use_gradle_build. The export preset warns the user that the required template is missing, and provide a button to invoke the template manager so the user can download the required template.

• Scenario 2: user is using custom templates. User then create an Android export preset, select gradle_build/use_gradle_build and set up the custom template using gradle_build/android_source_template. No additional clicks required.

[m4gr3d]

1. Users can extend the build directory with custom code and files, such as notification icons, modifying gradle dependencies, and other changes. If we auto delete the build directory when exporting from a newer version, users could accidentally lose those modifications. So instead, I think we should only install the build template when it is not already present. If there is a version mismatch, we should show a dialog with two actions: Open the existing build directory, so users can review or copy their modifications if needed. And delete and reinstall the gradle template.

Yeah I think we can go with this approach. We should also add a checkbox to allow users to specify Always delete and don't ask me again, as well as an advanced editor settings to control and reset that behavior if needed.

[m4gr3d]

1. Users can extend the build directory with custom code and files, such as notification icons, modifying gradle dependencies, and other changes. If we auto delete the build directory when exporting from a newer version, users could accidentally lose those modifications. So instead, I think we should only install the build template when it is not already present. If there is a version mismatch, we should show a dialog with two actions: Open the existing build directory, so users can review or copy their modifications if needed. And delete and reinstall the gradle template.

Yeah I think we can go with this approach. We should also add a checkbox to allow users to specify Always delete and don't ask me again, as well as an advanced editor settings to control and reset that behavior if needed.

@syntaxerror247 I've updated the implementation. See the updated description.

[syntaxerror247]

We should also keep the Install Android Build Template menu option. When the Android export template is not present or downloaded, it currently provides an option to Install from a file.
Removing this dialog would remove the ability to manually install a build template.

Manually setting up a build template is still possible either through the gradle_build/android_source_template export option, or through the Manage export template dialog and window.

The pattern being observed is to improve the build flow by reducing the number of clicks required for setup. There are in general two scenarios a user may be going through, and both are addressed by the new flow:

• Scenario 1: user is using the default templates.

  • User either first launch the Manage export template window, and download the templates from there. Then user creates an Android export preset, select gradle_build/use_gradle_build, and is able to start exporting right away without any further clicks.
  • Or user first creates an Android export preset and select gradle_build/use_gradle_build. The export preset warns the user that the required template is missing, and provide a button to invoke the template manager so the user can download the required template.

• Scenario 2: user is using custom templates. User then create an Android export preset, select gradle_build/use_gradle_build and set up the custom template using gradle_build/android_source_template. No additional clicks required.

@m4gr3d problem is that I'd have to first export to generate the android build directory, and after that I'd be able to customize that. I'd like to first get the build directory, customize and then export. After this PR there's no option to get build directory before export.
For eg, godot-play-game-services plugin requires users to first customize the build directory to add game's project id before export. we'd have to add an awkward instruction to first export to generate the build directory and then do the rest :-)

Removing Install Android Build Template menu option also breaks every tutorial video, so we should take conservative approach for that as well.

[dsnopek]

I also personally like keeping the Install Android Build Template menu item. It becomes optional (which I expect most people will eventually take advantage of) but leaves the old workflow in place

[m4gr3d]

@dsnopek @syntaxerror247 I've updated the implementation to keep the Install Android Build Template... button, but have it hidden by default with the ability to show it via the export/android/build/show_install_android_source_button editor setting.

[syntaxerror247]

@dsnopek @syntaxerror247 I've updated the implementation to keep the Install Android Build Template... button, but have it hidden by default with the ability to show it via the export/android/build/show_install_android_source_button editor setting.

I don't think hiding a menu option behind an editor setting is a good idea. We should either have this setting or not have it at all.

We can update the documentations to only mention the new export flow but I'd still prefer keeping this option for now and remove it in 5.0 (or maybe later 4.x releases). I just think that removing this option would be a big change.

I'd ask Usability team to share their thoughts on removing Install Android Build Template menu option. @godotengine/usability

[dsnopek]

@dsnopek @syntaxerror247 I've updated the implementation to keep the Install Android Build Template... button, but have it hidden by default with the ability to show it via the export/android/build/show_install_android_source_button editor setting.

I don't think hiding a menu option behind an editor setting is a good idea. We should either have this setting or not have it at all.

I agree.

My inclination would be to just leave the option in the menu for now. Most folks will hit on the automatic behavior by virtue of just going to export and everything working. And the folks who know they need the tool can continue to find it in the menu. There will be a short period where some people may continue using the tool, even though they really need it anymore, but this will likely fade with time

[m4gr3d]

@dsnopek @syntaxerror247 I've updated the implementation to keep the Install Android Build Template... button, but have it hidden by default with the ability to show it via the export/android/build/show_install_android_source_button editor setting.

I don't think hiding a menu option behind an editor setting is a good idea. We should either have this setting or not have it at all.

I agree.

My inclination would be to just leave the option in the menu for now. Most folks will hit on the automatic behavior by virtue of just going to export and everything working. And the folks who know they need the tool can continue to find it in the menu. There will be a short period where some people may continue using the tool, even though they really need it anymore, but this will likely fade with time

The issue is that I am introducing a new button in #121849 to automatically download and setup the Android SDK, so following that PR, a user will have 3 UX to set up and configure their Android export:

1. Export Template Manager used to download the Android export templates from the Available templates tree window
2. Export Template Manager hosting the Setup Android SDK button that users can click to download and install the Android SDK
3. Install Android Build Template... button in the Project menu that's used to install the Android build template.

The last button is now redundant with the functionality being added in this PR, except for expert users. So to avoid confusing regular users (which would be the vast majority), the current approach is to hide the last button by default, and provide a settings for expert users to bring it back if desired, similar to the approach used for the renderer selection drop-down.

Another approach would be to merge the functionality of the Setup Android SDK and Install Android Build Template... button together:

• Clicking on the button would install and set up the Android SDK if it's not already set up
• If the Android SDK is set up, then the logic would automatically install the Android build template, following the same flow as currently provided by the Install Android Build Template... button.

[m4gr3d]

Feedback from discussions with @dsnopek and @syntaxerror247:

• Rename Install Android Build Template... to Setup Android Build
• Update the button logic to check for the Android SDK, and prompt the user for install if it's not already installed.
• Move the Setup Android SDK button in Automate Android & Java SDK setup #121849 from the Export Template Manager to the Export Window. It should be surfaced as a link similar to what we do for the Manage External template link

[m4gr3d]

@dsnopek @syntaxerror247 I've addressed your feedback, the PR should be good to go!

[syntaxerror247]

Looks good to me!

[dsnopek]

Thanks! I skimmed the code, and it looks good to me

I also test all use cases I normally use when developing for Android:

• Automatically installing when default export templates are present
• Automatically installing when export preset has custom export templates
• Using the original "Install Android Build Template..." dialog (both when export templates are present and not)

They all seemed to work great!

[Repiteo]

Thanks!