Add debug instructions and sample bazelproject (#1888)

Signed-off-by: Martin Conte Mac Donell <[email protected]>

.bazelproject

@@ -0,0 +1,4 @@
+# Uncomment the examples you'd like to use!
+import examples/kotlin/hello_world/.bazelproject
+
+android_sdk_platform: android-31

docs/root/development/debugging/android_local.rst

@@ -0,0 +1,68 @@
+.. _debugging_android_instructions:
+
+Debugging the Hello World App (Android)
+=======================================
+
+Goals
+-----
+
+- As a developer you can compile your `envoy-mobile` repository and the generated `.aar` will be automatically recognized by Android Studio
+- `envoy-mobile` can be compiled to a single arch for debugging
+- While breaking on a C++ function, Android Studio should present the source file and highlight the line where the breakpoint hit with all scope information
+- The workflow works both on emulator and device
+
+Setting up the environment
+--------------------------
+
+Before we start, you'll need to download Android Studio and the `Bazel plugin <https://plugins.jetbrains.com/plugin/9185-bazel>`_, you can find it in Preferences -> Plugins
+.
+
+1. Go `here <https://developer.android.com/studio/>`_ and install Android Studio.
+2. Install the bazel plugin
+
+Adding Envoy-Mobile Project into Android Studio
+-----------------------------------------------
+
+With your environment setup, open Android Studio.
+
+1. Add a new bazel project by clicking here:
+
+.. image:: images/add-project.png
+
+2. Select your repository root path as follows and hit Next:
+
+.. image:: images/select-em.png
+
+3. Import the bazelproject file from the root and hit Next:
+
+.. image:: images/import-project.png
+
+4. You'll see a screen similar to this. Click Finish.
+
+.. image:: images/final-step-project.png
+
+5. Once Android Studio completes loading click on the Bazel Sync icon:
+
+.. image:: images/bazel-sync.png
+
+
+Entering a debugging session
+----------------------------
+
+With the project ready, you can now start debugging with Android Studio.
+
+1. Compile your envoy-mobile with debug symbols to the architecture of the device or emulator you are about to run.
+
+For example:
+::
+
+    $ bazelisk build android_dist --config=android --fat_apk_cpu=x86 -c dbg
+
+Android supported archs are `arm64_v8a`, `armeabi-v7a`, `x86`, `x86_64`.
+
+2. From Android Studio select the `Example App x86 (Debug)` configuration and hit the debug icon. Note: if you don't see this option go to "Add configuration" and it'll be there on the Bazel category, just select it and hit Ok.
+3. Optionally you could create symbolic breakpoints before running by going to the Debugger tab.
+
+Your environment should look like this at this point:
+
+.. image:: images/environment.png

examples/kotlin/hello_world/.bazelproject

@@ -0,0 +1,22 @@
+workspace_type: android
+
+directories:
+  -bazel-bin
+  -bazel-instant-android
+  -bazel-out
+  -bazel-testlogs
+  -buck-out
+  -build
+  examples/kotlin/hello_world
+
+import_run_configurations:
+  examples/kotlin/hello_world/tools/android-studio-run-configurations/run_configuration_example_debug_x86.xml
+
+targets:
+  //examples/kotlin/hello_world:hello_envoy_kt
+
+additional_languages:
+  kotlin
+  java
+  android
+  c

examples/kotlin/hello_world/tools/android-studio-run-configurations/run_configuration_example_debug_x86.xml

@@ -0,0 +1,38 @@
+<configuration name="Example App x86 (Debug)"
+    type="BlazeCommandRunConfigurationType"
+    factoryName="Bazel Command"
+    nameIsGenerated="false">
+    <blaze-settings kind="android_binary"
+        blaze-command="mobile-install"
+        handler-id="BlazeCommandGenericRunConfigurationHandlerProvider"
+        blaze-native-debug="true"
+        DEEP_LINK=""
+        ACTIVITY_CLASS=""
+        MODE="default_activity"
+        launch-method="NON_BLAZE"
+        use-split-apks-if-possible="false"
+        use-work-profile-if-present="false"
+        show-logcat-automatically="false"
+        AM_START_OPTIONS="">
+        <blaze-user-flag>--fat_apk_cpu=x86</blaze-user-flag>
+        <blaze-target>//examples/kotlin/hello_world:hello_envoy_kt</blaze-target>
+        <Profilers>
+            <option name="ADVANCED_PROFILING_ENABLED"
+                value="false" />
+            <option name="STARTUP_PROFILING_ENABLED"
+                value="false" />
+            <option name="STARTUP_CPU_PROFILING_ENABLED"
+                value="false" />
+            <option name="STARTUP_CPU_PROFILING_CONFIGURATION_NAME"
+                value="Sample Java Methods" />
+            <option name="STARTUP_NATIVE_MEMORY_PROFILING_ENABLED"
+                value="false" />
+            <option name="NATIVE_MEMORY_SAMPLE_RATE_BYTES"
+                value="2048" />
+        </Profilers>
+    </blaze-settings>
+    <method v="2">
+        <option name="Blaze.BeforeRunTask"
+            enabled="true" />
+    </method>
+</configuration>