diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst index 9609fcf6..6d832c24 100644 --- a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst +++ b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/Installing-Android-Studio.rst @@ -24,15 +24,21 @@ to verify that your system satisfies the list of minimum requirements: * `MacOS `__ * `Linux `__ -Java Development Kit -~~~~~~~~~~~~~~~~~~~~ -Earlier versions of Android Studio required that the user install the -Java Development Kit software separately. Current versions of Android -Studio incorporate the Java development software as part of the entire -install package. It is no longer necessary (or recommended) to install -the Java Development Kit separately. Instead, it is recommended that you -use the Java Development Kit that is included with Android Studio. +.. caution:: + + With the introduction of **Android Studio Ladybug**, the JDK that is packaged with + Android Studio is incompatible with the FtcRobotController workspace. If you install + or update an existing installation to Android Studio Ladybug, you will need to install + JDK 17 separately. + + Upon initial load of the FtcRobotController workspace using Android Studio Ladybug, + an error will be displayed during the Gradle sync and Android Studio will recommend that + you upgrade Gradle. Do not upgrade Gradle. + + For more detailed instructions see: Configuring + + Downloading and Installing Android Studio ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -64,3 +70,76 @@ Once the setup package has downloaded, launch the application and follow the on-screen instructions to install Android Studio. +Configuring Android Studio (Ladybug and later) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + See the Caution above for why this is necessary. + +.. note:: + + Android Studio Ladybug updates the underlying JetBrains IntelliJ version such that + the interface is a VSCode look alike. The screenshots in this documentation use the + JetBrains/Android Studio Classic UI which is no longer supported natively by JetBrains. + To follow along, users should install the `Classic UI `__ plugin. + + +#. `Install JDK 17 `__ + If you did not already have this installed independently of Android Studio. + e.g. If you were using Android Studio’s bundled JDK, then when Ladybug is installed Android Studio + will unhelpfully overwrite your old bundled JDK version. Note there’s a bug in the Settings → Build Tools → Gradle dialog + that may make you think your old version of the JDK is there, but it is not. You must use an unbundled version of the JDK. + +#. Go to File -> Settings and under Build, Execution, Deployment -> Build Tools -> Gradle use the Add JDK from disk option + to select the newly installed JDK 17. In the image below take careful note of the directory paths + for the options labeled jbr-17 and jbr-21. Note that they are the same. This is the aforementioned UI bug, + and that is Android Studio overwriting your old JDK. In this image you’ll see I’ve selected the JDK that + was installed independently. + +.. image:: images/AndroidStudioSelectJdk.png + :align: center + +| + +Do Not Upgrade Gradle +~~~~~~~~~~~~~~~~~~~~~ + +If you have upgraded Android Studio from an earlier version to Ladybug, or you did not install and +configure the JDK prior to loading a FtcRobotController workspace, then Android Studio may present an +error and recommend that you upgrade Gradle. + +.. image:: images/AndroidStudioUpgradeGradle.png + :align: center + +| + +Do not do this. The FtcRobotController build is incompatible with upgraded Gradle. If you do, you +will presented with another, even more, indecipherable error. + +To recover, you need to rollback the changes that Android Studio made upon that click. +To do that select Git -> Uncommitted Changes -> Show Shelf + +.. image:: images/AndroidStudioRecoverUpgrade.png + :align: center + +| + +That will show the changes you have in your workspace. You want to rollback the 4 gradle files shown in the +following image. You can either select the Changes checkbox to select all files, or individually select the +gradle files. Note that if you have changes in your workspace that haven’t been committed, you want to be +careful not to select those files or you may lose work. + +.. image:: images/AndroidStudioRollback.png + :align: center + +| + +Once you have the proper files selected, click the Rollback button. + +Resync and that should revert you to the error that prompted you to upgrade Gradle in the first place. +From there follow the instructions above to install JDK 17. + + + + diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioRecoverUpgrade.png b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioRecoverUpgrade.png new file mode 100644 index 00000000..168bf022 Binary files /dev/null and b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioRecoverUpgrade.png differ diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioRollback.png b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioRollback.png new file mode 100644 index 00000000..e6c02ba5 Binary files /dev/null and b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioRollback.png differ diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioSelectJdk.png b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioSelectJdk.png new file mode 100644 index 00000000..cbfc4266 Binary files /dev/null and b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioSelectJdk.png differ diff --git a/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioUpgradeGradle.png b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioUpgradeGradle.png new file mode 100644 index 00000000..2a8fa617 Binary files /dev/null and b/docs/source/programming_resources/tutorial_specific/android_studio/installing_android_studio/images/AndroidStudioUpgradeGradle.png differ