When I introduced Kivy a while back, I mentioned that I had not been able to deploy a Kivy app on Android. I’ve managed to do this now, using the VirtualBox image provided by the Python For Android project. Using this image was substantially less work than trying to figure out how to install and set up all the prerequisites under Arch Linux. So here’s how to do it:
First download the VirtualBox image from Google Drive. Sadly I cannot find an adequate
wget command to download this. Shame on you, Google!
You may want to double check the documentation to see if a later image has been made available.
It’s a big honkin’ file (1.4GB), so grab a cup of coffee, lunch, or go to bed, depending on your bandwidth and the current time of day.
Extract the file using p7zip. This takes a while, so you might want to grab another coffee:
7z e Python\ for\ Android\ -\ Ubuntu\ 12.04.7z
Make sure VirtualBox is installed and the kernel module is loaded. The commands on Arch Linux are:
pacman -S virtualbox virtualbox-host-modules sudo modprobe vboxdrv
Fire up VirtualBox and hit Machine->Add.
Navigate to the folder the vbox image was extractedto. Select the
Python for Android - Ubuntu 12.04.vbox machine and hit open.
If you have enough RAM, select the
Python for Android machine and hit settings. Browse to the
System tab and increase the RAM to a comfortable level (I set it to 2GB on my 4GB machine). You might also want to increase the number of processors and the video RAM. Hit
Start to power on the machine.
Once Ubuntu has loaded, review the README for some important information. You may want to update the VirtualBox Guest Additions install, although I’m sure it will work fine without it.
Now you’re ready to build an APK from a Python project. Open a terminal from the menu on the sidebar. The first thing you’ll want to do is update the
project to the latest git checkout. This is a bit messy because there are a couple edits in the current checkout that were later fixed upstream. So you'll want to stash the changes before pulling:
cd android/python-for-android git stash git pull git stash apply
Unfortunately, this introduces a merge conflict in
distribute.sh. The upstream project has made some of the customizations obsolete by including more generic code. Luckily, it's a trivial fix. Open
distribute.sh in an editor (
gedit distribute.sh works, but I used vim.) and search for the characters
=======. It's at line 170. Delete the line above that says
<<<<<<< Updated upstream. Leave the export line that was above the
=======. Then delete the
>>>>>>> Stashed changes and the outdated
export line in between. Save the file and close the editor.
Now you need a Kivy application to install. Presumably you've written your own, but for this example, I'm going to use a cool one supplied by the Kivy team. The Kivy Remote Shell creates an ssh server on the phone that allows you to log in from your computer over ssh and execute Python commands on the phone. You can even run Java commands using the beta pyjnius connector.
These commands will prepare a python for android distribution ready for installation:
cd .. git clone git://github.com/kivy/kivy-remote-shell cd python-for-android ./distribute.sh -m 'openssl pycrypto pyasn1 pyjnius twisted kivy'
This will prompt to see if you want to overwrite the previous python for android distribution. Press <enter> to do so. Give it some time to connect to the network, download the dependencies from Pypi, and compile them.
Now you need a rather ugly command to actually build the apk. The options are summarized in the Python for Android documentation.
cd dist/default ./build.py --package org.kivy.sshshell --name "Kivy Remote Shell" \ --version 1 --dir ../../../kivy-remote-shell/ \ --icon ../../../kivy-remote-shell/icon.png --permission INTERNET debug
This will create the file
bin/KivyRemoteShell-1-.debug.apk. Now let's install it to the phone! First make sure USB debugging is enabled on your phone. Go to the
Settings-->Developer Options menu and make sure
Developer Options are enabled and that
Android Debugging is enabled.
Plug the phone into your computer via the USB cord. Click the little "USB" icon in the VirtualBox status bar and check the box next to the name for your phone.
Run the command
~/android/android-sdk-linux_x86/platform-tools/adb devices to make sure it outputs the identifier of your phone. If it works, simply run
~/android/android-sdk-linux_x86/platform-tools/adb install bin/KivyRemoteShell-1-debug.apk to install the app.
(If you can't get the phone to connect to the VM, you can also copy the
.apk to the host machine to install it. Use VirtualBox's shared folders feature).
You can now shut down the virtual machine from Ubuntu's shutdown menu. For security, it's a good idea to turn off USB debugging on your phone until you need it again. Run the "Kivy Remote Shell" app that is now in your phone's app drawer. Type the command that comes up onto your screen into a terminal on your computer, and you will have access to a Python prompt running on your phone!
This same process can be used to install self-developed Kivy apps to your phone. Congratulations!