Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/remogatto/mandala

A Go framework for writing native Android applications
https://github.com/remogatto/mandala

Last synced: 5 days ago
JSON representation

A Go framework for writing native Android applications

Awesome Lists containing this project

README 

        
# Mandala

  [![GoDoc](https://godoc.org/github.com/remogatto/mandala?status.png)](http://godoc.org/github.com/remogatto/mandala)



Mandala is a framework for writing Android native applications in

[Go](http://golang.org) using the

[Goandroid](https://github.com/eliasnaur/goandroid) toolchain. You can

develop, test and run your application on your desktop and then deploy

it to an Android device. It encourages the use of idiomatic Go for

writing Android applications: communication happens through channels and 

not callbacks. The framework should not be considered a high-level

game engine but as a basic layer onto which game engines can be built

or existing ones can be used. In my opinion, this opens interesting

scenarios in the developing of native Android applications/games in

Go. Goandroid's

[native_activity](https://github.com/eliasnaur/goandroid/tree/master/native-activity)

example was the initial source of inspiration for this project.



Please consider that Mandala is in a very early stage of development:

API will change, test coverage is not so good for now. Last but not

least, Go doesn't officially support native Android

development. Regarding this point, I hope that the present work could

act as a sort of incentive in the direction of an official Android

support by the Go Team.



Have a nice Mandala!



# Key features



* Code/test/run on your desktop and deploy on the device.

* Build/deploy/run your application using simple shell commands.

* On-device black-box testing.

* Communicate through channels, no callbacks.

* Quick bootstrap using a predefined template.



# Supported desktop platforms



* Linux (xorg)

* OSX (see the wiki [page](https://github.com/remogatto/mandala/wiki/OSX-support))



# Techonologies involved



* [Android NDK](http://developer.android.com/tools/sdk/ndk/index.html)

* [Goandroid](https://github.com/eliasnaur/goandroid)

* [EGL](https://www.khronos.org/egl/)

* [OpenGL ES 2](http://www.khronos.org/opengles/2_X/)

* [GLFW 3](http://www.glfw.org/)

* [Gotask](https://github.com/jingweno/gotask)

* [Loop](https://github.com/tideland/goas/tree/master/v2/loop/)

* [PrettyTest](https://github.com/remogatto/prettytest)



# How does it work?



Mandala uses the [Goandroid](https://github.com/eliasnaur/goandroid) toolchain to compile Go

applications for Android. The graphics abstraction between desktop and

device is obtained using a bunch of technologies. In particular



* EGL

* OpenGL ES 2.0

* GLFW 3



The EGL layer is necessary to use an OpenGL ES 2 context on a

desktop environment. The GLFW library is responsible of managing the rendering

context and the handling of events in a window.



The framework itself provides an event channel from which client code

listen for events happening during program execution. Examples of

events are the interaction with the screen, the creation of the native

rendering context, pausing/resuming/destroying of the application,

etc.



The framework abstracts the Android native events providing a way to

build, run and test the application on the desktop with the promise

that it will behave the same on the device once deployed. Oh well,

this is the long-term aim, at least!



A typical Mandala application has two loops: one continuously listens for

events, the other is responsible for rendering the scene. In order to

dealing with application resources (images, sounds, configuration

files, etc.), the framework provides a ResourceManager object. Client

code sends requests to it in order to obtain resources as slices of

bytes. In the desktop application this simply means opening the file

at the given path. In the Android application the framework will

unpack the apk archive on the fly getting the requested resources from

it. However, it is the framework's responsibility to deal with the right

native method for opening a file. From the client-code point of view the

request will be the same.



The bothersome steps needed to build, package and deploy the

application on the device are simplified using a set of predefined

[gotask](https://github.com/jingweno/gotask) tasks.



# Examples



Please visit

[mandala-examples](https://github.com/remogatto/mandala-examples).



# Prerequisites



* Android NDK

* Goandroid

* EGL

* OpenGL ES 2

* GLFW3

* gotask (to run the tests)

* xdotool (to run the tests on xorg)



## Android NDK



See [here](http://developer.android.com/tools/sdk/ndk/index.html#Installing).



## Goandroid



See [here](https://github.com/eliasnaur/goandroid).



After installing [Goandroid](https://github.com/eliasnaur/goandroid)

you have to export a new environment variable GOANDROID. It

should point to the Go bin folder of the Goandroid

distribution. For example,




export GOANDROID=$HOME/src/goandroid/go/bin




Also note that on a 32 bit host machine, it would be necessary to

generate the toolchain with:




$NDK/build/tools/make-standalone-toolchain.sh --platform=android-9 --toolchain=arm-linux-androideabi-4.8 --install-dir=ndk-toolchain




See [here](eliasnaur/goandroid#13) for further info about the issue.



## EGL/OpenGL ES 2



On a debian-like system:




sudo apt-get install libgles2-mesa-dev libegl1-mesa-dev




Then you should install the Go bindings for EGL and OpenGL ES 2. This

is as simple as:




go get github.com/remogatto/egl

go get github.com/remogatto/opengles2




## GLFW3



Install from source following the instructions

[here](http://www.glfw.org/docs/latest/compile.html). Please note that

you have to configure GLFW in order to use EGL and OpenGL ES 2. For

further information, see

[here](http://www.glfw.org/docs/latest/compile.html#compile_options_egl)

and

[here](http://www.glfw.org/docs/latest/compile.html#compile_options_shared). Be

sure to build GLFW as a shared object!



After installing GLFW3, in order to install the Go binding, see

[here](https://github.com/go-gl/glfw3).



## gotask




go get github.com/jingweno/gotask




## xdotool



On a debian-like system:




sudo apt-get install xdotool




This is needed for black-box testing only.



# Install



Once you have satisfied all the prerequisites:




go get github.com/remogatto/mandala




This will install all the remaining dependencies.



# Quick start



To create a basic application install mandala-template:




go get github.com/remogatto/mandala-template




Then, in a folder inside $GOPATH/src run the following

commands:




mandala-template myapp

cd myapp

gotask init

gotask run android # deploy and run on a connected device

gotask run xorg    # run on a desktop window




This will generate a simple Android application showing a red

screen. See

[mandala-template](https://github.com/remogatto/mandala-template) for

furher info.



# Testing



Setup a testing environment on Android was not straightforward. The

main [issue](https://github.com/eliasnaur/goandroid/issues/20) is

related to the flag package. To avoid dependency from it I

had to hack [PrettyTest](https://github.com/remogatto/prettytest) in

order to remove the dependency from testing (which in turn

depends on flag). So basically, testing a native Android

application is now possible using

[PrettyTest](https://github.com/remogatto/prettytest) but we have to

renounce the benefits of testing (at least for now). See

[test](test/) for further info about testing. To run the tests on your

desktop window you need the xdotool (see the Prerequisites

section)



# To do



* Write a complete game using the framework

* Sound support

* More tests



# Credits



* @jingweno for his cool build tool

  [gotask](https://github.com/jingweno/gotask)



* @eliasnaur for his [Goandroid](https://github.com/jingweno/gotask),

  the necessary condition for this work



* @aded for patiently testing the pre-announcement release on his

  32bit broken machine.



# License



See [LICENSE](LICENSE).