protify: instantaneous, on-device development for Android

Latest version Join the chat at https://gitter.im/scala-android/sbt-android

NOTE: 1.2.0 is the last version published using addSbtPlugin("com.hanhuy.sbt" % "android-protify" % "1.2.0"), all future updates can be accessed by using addSbtPlugin("org.scala-android" % "sbt-android-protify" % VERSION)

Features:

  • Multiple language support: Java (including retrolambda), Scala, Kotlin
  • No code changes to app required!
  • Support for appcompat-v7, design and support-v4 libraries
  • Works with most existing android projects
  • Android devices api level 5+
  • Dex sharding for near-instant deployment

Demo:

Live coding and hot deploy

Getting started:

Android Studio / Gradle Quick Start

  1. Install sbt from http://scala-sbt.org, homebrew, ports, or your package manager of choice
  2. Optionally add idea-sbt-plugin to run SBT inside of Android Studio
  3. Install the sbt-android-gradle SBT plugin to automatically load your gradle build. From the base of your Android project, do:
    • mkdir project
    • echo 'addSbtPlugin("org.scala-android" % "sbt-android-gradle" % "1.3.2")' > project/plugins.sbt
    • echo >> project/plugins.sbt
    • If you have any flavors or build types that must be loaded:
      • echo 'android.Plugin.withVariant("PROJECT-NAME (e.g. app)", Some("BUILD-TYPE"), Some("FLAVOR"))' > build.sbt
      • echo >> build.sbt
        • Replace Some(...) with None if you don't have a flavor or build type to apply
  4. Install the sbt-android-protify plugin, also from the project base, do:
    • echo 'addSbtPlugin("org.scala-android" % "sbt-android-protify" % "1.4.4")' >> project/plugins.sbt
    • For every application sub-project, do: echo 'enablePlugins(AndroidProtify)' > APP-PROJECT-DIR/protify.sbt
  5. Launch SBT, sbt (first time's gonna take a while, downloading the internet and all)
  6. Build and install the application normally, at least once:
    • PROJECT-NAME/android:install (or run instead of install) -- the first time will take a while too, since it will download the parts of the internet that your app requires
  7. Thereafter: PROJECT-NAME/protify, do ~PROJECT-NAME/protify to automatically trigger on all source changes

Everyone else:

  1. Install sbt from http://scala-sbt.org, homebrew, ports, or your package manager of choice
  2. Install sbt-android: echo 'addSbtPlugin("org.scala-android" % "sbt-android" % "1.7.7")' > ~/.sbt/0.13/plugins/android.sbt
  3. Start from an existing or new project (for trivial projects): sbt "gen-android ..." to create a new project, sbt gen-android-sbt to generate sbt files in an existing project. Non-trivial projects will need more advanced sbt configuration.
    • Alternatively, use sbt-android-gradle when working with an existing gradle project:
      • echo 'addSbtPlugin("org.scala-android" % "sbt-android-gradle" % "1.3.2")' > project/plugins.sbt
  4. Add the protify plugin: echo 'addSbtPlugin("org.scala-android" % "sbt-android-protify" % "1.4.4")' >> project/plugins.sbt
  5. Add AndroidProtify: echo enablePlugins(AndroidProtify) >> build.sbt
  6. Run SBT
  7. Select device to run on by using the devices and device commands. Run on all devices by executing set allDevices in Android := true
  8. android:run, and ~protify
    • Alternatively, high speed turnaround can be achieved with protify:install and protify:run to pretend the app is getting updated, rather than using the live-code mechanism.
  9. Enjoy

Full IntelliJ IDEA & Android Studio integration

To make it so that protify can be run when triggered in the IDE with a keystroke, do the following

  1. Install Scala plugin in IDE
  2. Install SBT plugin in IDE
  3. Create a new Run configuration, press the dropdown next to the play button, select Edit Configurations
    • Press + -> Android Application
    • Name the configuration protify, instant run, or whatever you like
    • Select the app module
    • Select Do not deploy anything
    • Select Do not launch activity
    • For target device, select anything that will not prompt
    • Uncheck Activate tool window
    • Remove Make from Before launch
    • Before launch -> + -> Add New Configuration -> SBT
      • In the drop down, edit the text to say protify
  4. You can now invoke protify directly as a run configuration and see changes instantly (FSVO instant) appear on-device.

Vim, etc.

  1. Just do any of the above getting started steps and follow your own workflow.

LIMITATIONS

  • Manifest changes will require android:install again (i.e. adding/removing: activities, services, permissions, receivers, etc). Incremental deployment cannot modify manifest.
  • No longer true with build-tools 24.0.0 and newer: Deleting a constant value from R classes (removing resources) will require running protify:clean or else the build will break
  • Object instance state, including singleton and static, will not be restored upon deploying new dex code (or resources when on device api level <14). All Android Bundled state will be restored in all situations
  • Android instrumented tests are not supported. They will fail to run because of the sharded dex and re-located resource files.
  • NDK is not supported at the moment (initial install works, no protify updates when jni code changes)

TODO (volunteers wanted)

  • Support NDK. This means delivering the .so libraries from the build environment to the device, placing them into the correct location and triggering an app restart
  • Support instrumented testing. This would need implementation similar to MultiDexTestRunner