SDK Build Environment for Android Platform - magic-lantern-android-studio/mle-documentation GitHub Wiki

This page discusses how to build the Magic Lantern SDK for Android platforms using Android Studio on an Apple Macintosh or Ubuntu 18.04 LTS host development platform. The SDK is built targeting the Android Q Platform (version 29).

Note: A top-level build script does not yet exist for this project.

Table of Contents

Dependencies

This section identifies dependencies for building the Magic Lantern SDK.

  1. Google's Android Studio, version 4.1.2 (see Android Studio Installation for more details).
  2. Oracle Java Development Kit (JDK), version 1.8.0_221 Required by Android Studio (download from http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
  3. Python, version 2.7.6

Assumptions

These instructions assume the following:

  • The dependencies above are installed in their default locations.
  • You already know how to use the Android Studio IDE.
  • You already know how to administer an Apple Macintosh or Ubuntu Linux machine.

Download Source

The source for the Android Studio projects are currently located on Github under the Magic Lantern Android Studio organization (https://github.com/magic-lantern-android-studio).

Create a Project Directory

In a console window, create a project directory:

$ mkdir ~/MagicLantern

Note: "~" is your home directory (e.g. /home/msm).

Retrieve Source Using Git

In a console window, clone the git repositories from Github:

$ cd ~/MagicLantern
$ git clone https://github.com/magic-lantern-android-studio/core-math.git
$ git clone https://github.com/magic-lantern-android-studio/core-runtime.git
$ git clone https://github.com/magic-lantern-android-studio/parts-base.git
$ git clone https://github.com/magic-lantern-android-studio/parts-actors.git
$ git clone https://github.com/magic-lantern-android-studio/parts-roles.git
$ git clone https://github.com/magic-lantern-android-studio/parts-sets.git
$ git clone https://github.com/magic-lantern-android-studio/parts-stages.git
$ git clone https://github.com/magic-lantern-android-studio/parts-mrefs.git
$ git clone https://github.com/magic-lantern-android-studio/parts-props.git
$ git clone https://github.com/magic-lantern-android-studio/titles-imagetest.git
$ git clone https://github.com/magic-lantern-android-studio/titles-cubetest.git
$ git clone https://github.com/magic-lantern-android-studio/titles-hellocube.git
$ git clone https://github.com/magic-lantern-android-studio/mle-tools.git

You should now have thirteen Android Studio projects located in

Project Description
~/MagicLantern/core-math Magic Lantern Math utility library
~/MagicLantern/core-runtime Magic Lantern Runtime Engine library
~/MagicLantern/parts-base Magic Lantern Parts support library
~/MagicLantern/parts-actors Magic Lantern Actors library
~/MagicLantern/parts-roles Magic Lantern Roles library
~/MagicLantern/parts-sets Magic Lantern Sets library
~/MagicLantern/parts-stages Magic Lantern Stages library
~/MagicLantern/parts-mrefs Magic Lantern Media Reference library
~/MagicLantern/parts-props Magic Lantern Properties library
~/MagicLantern/titles-imagetest Magic Lantern Image Test application
~/MagicLantern/titles-cubetest Magic Lantern Cube Test application
~/MagicLantern/titles-hellocube Magic Lantern HelloCube application
~/MagicLantern/mle-tools Magic Lantern Tools

Retrieve Source Using repo

Alternatively, you can use the "repo" tool from Google (see repo Installation Instructions) to download the source.

$ cd ~/MagicLantern
$ repo init -u https://github.com/magic-lantern-android-studio/mle-manifests.git
$ repo sync

Build Core Math Utility Library

To build the Magic Lantern Core Math library, mlmath.jar, open the existing Android Studio project found at "~/MagicLantern/core-math". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/core-math" directory and select "OK". This will bring up the main Android Studio IDE, showing the "core-math" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The mlmath.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The mlmath-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the mlmath.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, core-math, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py core-math

The output should look like:

Staging core-math...
	Updating parts-base
	Updating parts-props
	Updating parts-roles
	Updating parts-sets
	Updating parts-stages
	Updating parts-actors
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Build Core Runtime Engine Library

To build the Magic Lantern Core Runtime Engine library, mlert.jar, open the existing Android Studio project found at "~/MagicLantern/core-runtime". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/core-runtime" directory and select "OK". This will bring up the main Android Studio IDE, showing the "core-runtime" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-runtime->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The mlert.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The mlert-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the mlert.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, core-runtime, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py core-runtime

The output should look like:

Staging core-runtime...
	Updating parts-actors
	Updating parts-base
	Updating parts-mrefs
	Updating parts-props
	Updating parts-roles
	Updating parts-sets
	Updating parts-stages
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Build Application Framework Base Library

To build the Magic Lantern Base library, parts.jar, open the existing Android Studio project found at "~/MagicLantern/parts-base". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/parts-base" directory and select "OK". This will bring up the main Android Studio IDE, showing the "parts-base" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "parts-base->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The parts.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The parts-sources.jar library will be created in the project's "app/release" directory.

Build min3d Aar

The min3d-debug.aar module may need to be built. If so, then select the "Make Module 'parts-base.min3d'" sub-menu item found in the pull-down menu when "Build" is selected.

This should build the parts-base/min3d/build/outputs/aar/min3d-debug.arr Android archive file.

Stage Jars

Copy the parts.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, parts-base, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py parts-base

The output should look like:

Staging parts-base...
	Updating parts-actors
	Updating parts-mrefs
	Updating parts-props
	Updating parts-roles
	Updating parts-sets
	Updating parts-stages
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
	Updating test-min3d_01
	Updating test-min3d_02
...Done

Build Application Framework Media Reference library

To build the Magic Lantern Base library, mrefs.jar, open the existing Android Studio project found at "~/MagicLantern/parts-mrefs". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/parts-mrefs" directory and select "OK". This will bring up the main Android Studio IDE, showing the "parts-mrefs" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "parts-mrefs->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The mrefs.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The mrefs-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the mrefs.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, parts-mrefs, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py parts-mrefs

The output should look like:

Staging parts-mrefs...
	Updating parts-actors
	Updating parts-roles
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Build Application Framework Roles Library

To build the Magic Lantern Base library, roles.jar, open the existing Android Studio project found at "~/MagicLantern/parts-roles". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/parts-roles" directory and select "OK". This will bring up the main Android Studio IDE, showing the "parts-roles" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "parts-roles->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The roles.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The roles-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the roles.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, parts-roles, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py parts-roles

The output should look like:

Staging parts-roles...
	Updating parts-props
	Updating parts-sets
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Build Application Framework Props Library

To build the Magic Lantern Base library, props.jar, open the existing Android Studio project found at "~/MagicLantern/parts-props". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/parts-props" directory and select "OK". This will bring up the main Android Studio IDE, showing the "parts-props" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "parts-props->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The props.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The props-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the props.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, parts-props, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py parts-props

The output should look like:

Staging parts-props...
	Updating parts-actors
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Build Application Framework Stages Library

To build the Magic Lantern Base library, stages.jar, open the existing Android Studio project found at "~/MagicLantern/parts-stages". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/parts-stages" directory and select "OK". This will bring up the main Android Studio IDE, showing the "parts-stages" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "parts-stages->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The stages.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The stages-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the stages.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, parts-stages, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py parts-stages

The output should look like:

Staging parts-stages...
	Updating parts-sets
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Build Application Framework Sets Library

To build the Magic Lantern Base library, sets.jar, open the existing Android Studio project found at "~/MagicLantern/parts-sets". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/parts-sets" directory and select "OK". This will bring up the main Android Studio IDE, showing the "parts-sets" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "parts-sets->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The sets.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The sets-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the sets.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, parts-sets, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py parts-sets

The output should look like:

Staging parts-sets...
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Build Application Framework Actors Library

To build the Magic Lantern Base library, actors.jar, open the existing Android Studio project found at "~/MagicLantern/parts-actors". In the Android Studio launch screen, select "Open an Existing Project". In the "Open File or Project" dialog panel, navigate to "~/MagicLantern/parts-actors" directory and select "OK". This will bring up the main Android Studio IDE, showing the "parts-actors" project in the "Project" window (you may need to expand this Window to see the project). By default, the project should successfully build.

Note: You may need to install the build tools and sync the project before the build is successful. The "Messages Gradle Sync" window will display an Error if this is the case.

Export Jars

Export the jar by running the "exportJar" Gradle task. To do this, open the "Gradle" window and navigate to the "parts-actors->app->Tasks->other" folder. There you should see an "exportJar" task; run the task by selecting it (double-click). The actors.jar library will be created in the project's "app/release" directory.

Export Sources Jar

The source files may also be exported to a jar by running the "exportSourcesJar" Gradle task. To do this, open the "Gradle" window and navigate to the "core-math->app->Tasks->other" folder. There you should see an "exportSourcesJar" task; run the task by selecting it (double-click). The actors-sources.jar library will be created in the project's "app/release" directory.

Stage Jars

Copy the actors.jar library to the other Magic Lantern projects that are dependent upon it. This can be done by running the "~/MagicLantern/mle-tools/scripts/stagelibs.py" python script. Pass in the name of the project, parts-actors, to copy the jar library:

$ cd ~/MagicLantern
$ ~/MagicLantern/mle-tools/scripts/stagelibs.py parts-actors

The output should look like:

Staging parts-actors...
	Updating titles-imagetest
	Updating titles-modeltest
	Updating titles-hellocube
	Updating titles-cubetest
...Done

Unit Tests

Unit tests are available for the following SDK components

Test Applications

The Magic Lantern SDK provides several test applications or titles.