Page 1 of 1

Building love-android-sdl2 on Win10 (x64) step by step

Posted: Wed Aug 15, 2018 6:33 pm
by jonthysell
I'm on Windows 10 (64-bit) and I wrote a game for LOVE 0.10.2.

I decided I wanted to try releasing my game as an Android app, but software changes fast and none of the official docs worked exactly as written. I'm not a Java/Android developer, and I wanted to install as little as possible to my system. Before running these steps I had nothing Java/Android related installed.

So for the benefit of the next person who is in the same position as me, here's what I did, step by step. For everyone who asks "but why aren't you using version XYZ instead?", I tried so many different permutations of versions and settings and this is what finally got me a working APK as of August 2018.

1. Get the latest Java SE JDK
Download and install the latest Java SE JDK (10.0.2) from here. During the install, you can uncheck the box for the "Public JRE", as it's not necessary.

1.a. Set the JAVA_HOME system environment variable (in System Properties):

Code: Select all

set JAVA_HOME=C:\Program Files\Java\jdk-10.0.2
2. Get Apache Ant
Download the latest zip file of Apache Ant (1.10.5) from here.

2.a. Unzip the contents to a folder on your machine (I used D:\ant).

2.b. Set the ANT_HOME system environment variable (in System Properties):

Code: Select all

set ANT_HOME=D:\ant
3. Get the Anrdoid SDK
Download the latest zip file of the "Command line tools only" from the bottom of here.

3.a. Unzip the contents to a folder on your machine (I used D:\android\android-sdk).

3.b. Set the ANDROID_SDK, ANDROID_HOME, ANDROID_SWT, and JAVA_OPTS system environment variables (in System Properties):

Code: Select all

set ANDROID_SDK=D:\android\android-sdk
set ANDROID_HOME=D:\android\android-sdk
set ANDROID_SWT=D:\android\android-sdk\tools\lib\x86_64
set JAVA_OPTS=--add-modules java.xml.bind
3.c. Open an administrator command prompt and change to the tools\bin folder:

Code: Select all

cd %ANDROID_SDK%\tools\bin
3.d. Run SDK manager to install the SDK we need:

Code: Select all

sdkmanager "platform-tools" "build-tools;19.1.0" "extras;android;m2repository" "extras;google;usb_driver" "platforms;android-19" "sources;android-19" "system-images;android-19;default;armeabi-v7a" "system-images;android-19;google_apis;armeabi-v7a"
This will take a while but when it's done close this command prompt.

4. Get the Anrdoid NDK
Download the revision 14b zip file of the the Android NDK from here.

4.a. Unzip the contents to a folder on your machine (I used D:\android\android-ndk).

4.b. Set ANDROID_NDK system environment variable (in System Properties):

Code: Select all

set ANDROID_NDK=D:\android\android-ndk
5. Update your PATH variable
Add %ANT_HOME%\bin, %ANDROID_SDK%\tools, and %ANDROID_NDK% to the PATH system environment variable (System Properties):

Code: Select all

set PATH=%PATH%;%ANT_HOME%\bin;%ANDROID_SDK%\tools;%ANDROID_NDK%
Congratulations! If you've made it this far, you should have all of the base dependencies installed. Now to actually building something.

6. Get and setup the love-android-sdl2 repo
We're going to get the source for the 0.10.x branch of the love-android-sdl2 project. You have two choices here, depending on whether or not you use Git. (I don't know if the 0.10.x branch is ever going to get updated, but for this guide I'm going to target a specific commit as the starting point).

If you have Git installed, open an administrator command prompt and run the following to get a new branch win10base at the correct commit:

Code: Select all

git clone https://bitbucket.org/MartinFelis/love-android-sdl2.git
cd love-android-sdl2
git checkout -b win10base 6ed3ba3810187c7582fca54bd564d98441a7613b
If you aren't using Git you can download the source zip here. Unzip it into a folder of your choice and open an administrator command prompt at that location.

6.a. Update gradle to version 4.6. Edit the file .\gradle\wrapper\gradle-wrapper.properties and change line 6 to:

Code: Select all

distributionUrl=https\://services.gradle.org/distributions/gradle-4.6-all.zip
6.b. Update the gradle tools version and repositories. Edit build.gradle and replace the contents with:

Code: Select all

// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.1.0'

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

allprojects {
    repositories {
        google()
        jcenter()
    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}
6.c. Create a file in the love-android-sdl2 folder named local.properties with the following contents:

Code: Select all

sdk.dir=D:\\android\\android-sdk
ndk.dir=D:\\android\\android-ndk
Use the Android_SDK and ANDROID_NDK folders that you selected in steps 3 and 4. Note you have to escape the backslashes.

7. Verify the code builds

Now's the moment of truth. In your open administrator command prompt, in the love-android-sdl2 folder, run the following command:

Code: Select all

gradlew.bat build
It will take a couple minutes, but in the end you should see a nice BUILD SUCCESSFUL message. Congratulations! You should now have two base APKs: .\app\build\outputs\apk\debug\app-debug.apk and .\app\build\outputs\apk\release\app-release-unsigned.apk.

You can sideload app-debug.apk to your developer-mode Android device, and it should be able to run .love game packages.

Now to transform it into a package with "your" game for distribution.

8. Packaging your game for distribution
For this, I'm assuming you already have a .love package, and we're going to publish this "YourGame" as version 1.0.0 with the id "com.example.yourgame".

8.a. Make a sub-folder named assets under .\app\src\main

8.b. Rename your .love file to game.love and copy it into .\app\src\main\assets

8.c. Update the file build.gradle in the .\app folder and edit the applicationId and versionName lines:

Code: Select all

applicationId "com.example.yourgame"
versionName "1.0.0-love2d-v0.10.2"
Now you can put the version to whatever you want, I simply chose the convention of also specifying which version of LOVE I am building off of (in case I ever get to upgrade in the future). Note: if you plan on releasing your app on Google Play, as of August 1st, 2018, you'll need to change the target SDK version to 26:

Code: Select all

targetSdkVersion 26
8.d. Update the file AndroidManifest.xml in the .\app\src\main folder by replacing its contents with this:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<manifest package="com.example.yourgame"
      android:installLocation="auto" xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.VIBRATE"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <!-- Allow writing to external storage -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

  <!-- OpenGL ES 2.0 -->
  <uses-feature android:glEsVersion="0x00020000" />

  <application
      android:allowBackup="true"
      android:icon="@drawable/love"
      android:label="YourGame"
      android:theme="@android:style/Theme.NoTitleBar.Fullscreen" >
      <activity
        android:name="com.example.yourgame.YourGameActivity"
        android:configChanges="orientation|screenSize"
        android:label="YourGame"
        android:launchMode="singleTop"
        android:screenOrientation="landscape" >
        <intent-filter>
          <action android:name="android.intent.action.MAIN" />
          <category android:name="android.intent.category.LAUNCHER" />
          <category android:name="tv.ouya.intent.category.GAME"/>
        </intent-filter>
      </activity>
    </application>
</manifest>
Be sure to use your id and game name info. Note the id is set in the second line (package attribute), the name of the game is set in lines 16 and 21 (android:label attribute) and the main activity name is on line 19 (android:name attribute). We'll address the main activity name in the next step.

8.e. Create a new main activity for your game.

In the last step we set the main activity for our game to com.example.yourgame.YourGameActivity, and now we need to create the code for that. Under the .\love\src\main\java folder, you'll need to make sub-folder hierarchy com\example\yourgame.

Then, in that deepest folder (.love\src\main\java\com\example\yourgame) create a new file named YourGameActivity.java with the following contents:

Code: Select all

package com.example.yourgame;
import org.love2d.android.GameActivity;

public class YourGameActivity extends GameActivity {}
Of course, be sure to use your id and game name info.

8.f. Update the icons.
Under the .\app\src\main\res folder, you should find several sub-folders with the icon love.png in different resolutions. Simply replace each file with your icon of the same size.

8.g. Build your game.
In your open administrator command prompt, in the love-android-sdl2 folder, run the following command:

Code: Select all

gradlew.bat build
If everything was successful, you should now have two APKs: .\app\build\outputs\apk\debug\app-debug.apk and .\app\build\outputs\apk\release\app-release-unsigned.apk.

As mentioned before, app-debug.apk can be side-loaded to your developer-mode enabled Android device. If you want to release your game on Google Play, you'll need to sign the app-release-unsigned.apk first. (See https://stackoverflow.com/questions/109 ... mpiled-apk for details.)

I hope others find this useful. I can't promise this will work for everyone, or that I'll be able to keep this up to date, but whether it works for you or you run into problems, let me know!

/jon

Re: Building love-android-sdl2 on Win10 (x64) step by step

Posted: Wed Aug 15, 2018 7:25 pm
by milon
Wow, awesome work! Thanks for sharing!!

I've attempted to get into Android builds a couple times, and eventually abandoned the idea because I couldn't get anywhere with it. I don't have much time for coding IRL, but if I ever get more serious about it, I'll be sure to come back looking for this post!

I assume that you haven't yet found a method that works for Love 11.1?

Re: Building love-android-sdl2 on Win10 (x64) step by step

Posted: Wed Aug 15, 2018 7:37 pm
by jonthysell
milon wrote: Wed Aug 15, 2018 7:25 pm I assume that you haven't yet found a method that works for Love 11.1?
I tried to build off the android 0.11.x branch but try as I might, I couldn't get it to build. There's just so many layers of dependencies in this toolchain that no matter what I tried there were always tons of errors, and I'm not familiar enough with Love, Java, Android, Gradle, etc. to be able to debug it effectively.

Even with the steps I outlined, there are all kinds of warnings about being on legacy APIs, etc. All I know is that at the end of this I got an APK that runs on my Android 7 phone, and now I may finally be able to publish my first Android game.

My hope is that this setup works long enough for me to work on a few games using love and get them published.

Re: Building love-android-sdl2 on Win10 (x64) step by step

Posted: Thu Aug 16, 2018 3:29 am
by jonthysell
Whelp, I've done all the work to get my apk signed for distribution, and Google Play won't accept it because it's targeting API 25.

Guess I've got some more work to do. :-(

Re: Building love-android-sdl2 on Win10 (x64) step by step

Posted: Sat Aug 25, 2018 8:51 pm
by jonthysell
Apparently all I had to do to target API 26 (the minimum required to publish on Google Play as of August 1st, 2018) was to update the targetSdkVersion in .\app\build.gradle. I've updated the guide to reflect this.