You need to have installed:

• the Android SDK
• Elm
• Python
• git

Clone this repo and cd into it:

$ git clone https://github.com/leforestier/elm-android-app
$ cd elm-android-app

Then run:

$ elm init

That will create an elm.json file in the current directory.

The entry point of your Elm application is src/Main.elm. This file contains a basic counter app that you can try to build to test that everything is working on your system.

To create a great app, modify src/Main.elm and add other Elm source files to the src/ directory .

To install additional elm packages, you can use elm install just like with any normal Elm project.

The script that enables you to build and/or install the app onto the device is manage.py. It's a single Python script without any dependencies. You can call it like this on the command line:

$ python manage.py (see next section for available commands)

On Linux you should be able to do simply:

$ ./manage.py (see next section for available commands)

First, and this is something you only have to do once per project, create a debug Android keystore using the command:

$ ./manage.py create-debug-key

This creates a keystore in the current directory under the file name debug.keystore.

You need to supply three environment variables to the script:

- BUILD_TOOLS_DIR: the directory of the Android SDK where reside tools such as `aapt` and `dx`.
  For example, I use `BUILD_TOOLS_DIR=/home/myusername/Android/build-tools/30.0.3/`

- PLATFORM_DIR: the directory of the Android SDK where reside `android.jar`.
  For example I use `PLATFORM_DIR=/home/myusername/Android/platforms/android-30/`

- KEYSTORE_FILE: the keystore file. If you created it by `manage.py create-debug-keystore`,
  then the file is `debug.keystore` and you should use `KEYSTORE_FILE=debug.keystore`

The rest of this tutorial assume you have exported these 3 environment variables using:

$ export BUILD_TOOLS_DIR=... PLATFORM_DIR=... KEYSTORE_FILE=...

Build an apk with the command:

$ ./manage.py build

The apk is created inside the build directory.

Make sure your device is connected to your computer in debug mode (you can use the command adb devices to check if your device appear in the list). Then:

$ ./manage.py install

You can also install the app and start it automatically using:

$ ./manage.py install+run

You change the name of the application exactly like you would in a normal Java only android application.

The name of our example application is "Elm App" and our package name is com.example.elmwebviewapp. Here's how to change it, for, say, a bird watching application called "Bird Watch" with package name net.birdwatchers.birdspot.

To change the application name to "Bird Watch":

• in AndroidManifest.xml replace android:label="Elm App" with android:label="Bird Watch"

To change the package name to net.birdwatchers.birdspot:

• rename the directory java/com/example/elmwebviewapp to java/net/birdwatchers/birdspot
• in MainActivity.java, replace the first line package com.example.elmwebviewapp; with package net.birdwatchers.birdspot;
• in AndroidManifest.xml, replace the package="com.example.elmwebviewapp" manifest attribute with package="net.birdwatchers.birdspot"

Same as with a normal Java only android application. Refer to Android development documentation.

Before loading the app on the device, you can develop using elm-live and see your changes in the browser of your laptop/desktop. This requires to have installed elm-live.

Then:

$ ./manage.py elm-live

This is just a shortcut for:

$ elm-live src/Main.elm -d assets -- --output=assets/main.js

You'll probably want to handle events such as swipes, presses, rotations, pinches etc...

To be able to use event attributes such as onSwipe, onSwipeLeft, onPress, onPinch... just as easily as you would use onClick, I published a helper library that you can install:

leforestier/elm-hammer-events

This helper library relies on the excellent Hammer.js Javascript library : it's just a single file hammer.min.js to add to your assets directory.

Alternatively, if you want to deal with HTML5 touch events directly, you can use the

Html.Events.Extra.Touch module from mpizenberg/elm-pointer-events