How to compile and run the example code¶

This tutorial explains how to turn the 'library' and 'examples' code into an application you can run on your Android phone.

We are going to assume you are fairly familiar with Android development.
I personally use Android Studio; you can use Eclipse or even command line for your development but setting up the project will be different.

1. Download and install Android Studio: https://developer.android.com/studio/index.html
2. Start it up and click on Menu->File->New->New Project to create a new, empty Project.
   1. In the 'New Project' window set:
      1. Application Name: Examples
      2. Company Domain: distorted.org
      3. Accept 'Package Name' to be org.distorted.examples
   2. In the 'Target Android Devices' window, make sure Phone and Tablet is checked. Everything else can be unchecked.
   3. In the 'Add an Activity to Mobile' select Add No Activity.
   4. Click Finish and an empty project will be created for you.

Now we will need to download the sources and add both 'library' and 'examples' as new modules to the empty Project we've just created.
At the time I am writing this, Android Studio 2.1.1 does not seem to support adding new modules directly from a Git repository; that's why we will have to do this in two steps.

1. Download (git clone) the sources to a local directory:
   1. Menu->VCS->Checkout from Version Control->Git
   2. In the 'Clone Repository' window, set 'Git Repository URL' to 'http://distorted.org/git/distorted-library.git'; you can leave the 'Parent Directory' and 'Directory Name' as they are.
   3. It will ask you if you want to open the new project file - don't do it.
   4. Repeat the above two steps again, this time setting the Git URL to 'http://distorted.org/git/distorted-examples.git'
2. Add the two newly created directories as modules to your Project:
   1. Menu->File->New->Import Module...
   2. Set source directory to wherever the cloned 'distorted-library' is and click 'Finish'.
   3. At this moment it may complain about missing Android SDK platforms and prompt you to 'Add root' of the new VCS. Do both. Once you do it, you should see a new module called 'distorted-library' in your Project's module list, right next to the automatically created 'app' module.
   4. Repeat the above, this time giving it the location where 'distorted-examples' got downloaded to. New module 'distorted-examples' will appear.
   5. Now you can (and should!) remove the empty 'app' module:
      1. Menu->File->Project Structure...
      2. Click on the 'app' module in the left
      3. Click on the red minus sign to remove it
      4. Go to your Project directory and remove the 'app' directory from it.

Now we should have the Project ready and Gradle successfully building it. Let's now try and run it then.

Library uses Open GL ES 3.1, which is not officially supported by Android Emulators; recommended way forward is to test it on a real device.

1. Connect your device to your computer via a USB cable. It needs to support OpenGL ES 3.1 - any fairly recent Android phone should.
2. Make sure it is in Developer mode and USB Debugging is on.
3. Menu->Run->Run 'distorted-examples'
4. In the 'Select Deployment Target' window select your phone and click 'Ok'
5. The 'Distorted Examples' app will get installed on your device.

Next: About the Distorted Examples App