SDK Build Environment for J2SE Platform - magic-lantern-studio/mle-documentation GitHub Wiki
This page discusses how to build the Magic Lantern SDK for Java Standard Edition platforms using Eclipse and/or Ant. The SDK is comprised of the following components:
- Magic Lantern Java Runtime Engine
- Magic Lantern Java Parts (actors, roles, sets, stages, and media references)
- Magic Lantern Mastering Tools
Table of Contents
- Dependencies
- Assumptions
- Environment Variables
- Details
- Setup Build Environment
- Build Java SDK Source Code
- Build Mastering Tools
- IDE for J2SE 2D Platform
- Java API Documentation
Dependencies
This section identifies dependencies for building the Magic Lantern SDK for the J2SE Platform.
- Ubuntu 18.04 LTS 64-bit operating system.
- Eclipse IDE for RCP Developers, version 2020-03-R
- Instructions assume that the installation directory is ~/bin/eclipse.
- The most recent version can be found at https://www.eclipse.org/downloads/packages/.
- GNU g++ toolchain.
- Oracle Java Development Kit (JDK), version 1.8.0_221
- Apache Ant toolchain, version 1.10.5
- Version 8.6.4.1 of ActiveTcl from ActiveState is installed. This build environment has been tested with binary build 299124.
- Instructions assume that the installation directory is ~/bin/ActiveTcl-8.6.
- Tcl is required by the mastering process to create a Digital Playprint.
- The most recent version can be found at http://www.activestate.com/activetcl/downloads
Assumptions
These instructions assume the following
- The dependencies above are installed under a Windows drive labeled "M" (e.g. M:).
- The Magic Lantern software has been downloaded into the "M:\projects\MagicLantern" directory and the MLE_HOME environment variable is set to "M:\projects\MagicLantern".
- You already know how to use the Eclipse IDE
- You already know how to create and use Ant build scripts
Environment Variables
MLE_HOME Environment Variable
Windows Host
Set the variable MLE_HOME to reference the home of the Magic Lantern source. This document assumes that it is set to "M:\projects\MagicLantern".
Linux Host
Set the variable MLE_HOME to reference the home of the Magic Lantern source. This document assumes that it is set to "$HOME/projects/MagicLantern".
MLE_ROOT Environment Variable
Windows Host
Set the variable MLE_ROOT to reference the root directory where the Magic Lantern components will be installed. This document assumes that it is set to "M:/projects/MagicLantern".
:information_source: Note: this variable uses the UNIX-style path delimiter ('/').
Linux Host
Set the variable MLE_ROOT to reference the root directory where the Magic Lantern components will be installed. This document assumes that it is set to "/opt/MagicLantern".
MLE_WORKPRINTS Environment Variable
Windows Host
Set the variable MLE_WORKPRINTS to the root directory where Magic Lantern Digital Workprints can be located. This document assumes that it is set to //M/projects/MagicLantern.
The Magic Lantern Studio assumes that the Digital Workprints will be located under the $MLE_WORKPRINTS/workprints directory.
:information_source: Note: this variable uses a canonical path style for the drive (i.e. //M/).
Linux Host
Set the variable MLE_WORKPRINTS to the root directory where Magic Lantern Digital Workprints can be located. This document assumes that it is set to $HOME/projects/MagicLantern.
TCL_HOME Environment Variable
Windows Host
TBD
Linux Host
Set the TCL_HOME variable to the installation directory for ActiveTcl. For these instructions, use ~/bin/ActiveTcl-8.6.
Details
This section discusses how to build the Magic Lantern SDK components targeting the Java Standard Edition (J2SE) platform. The Magic Lantern SDK is comprised of the following components:
| Component | Description | Location |
|---|---|---|
| com.wizzer.mle.runtime | The Magic Lantern Runtime Engine | $(MLE_HOME)\Core\mlert\java\com.wizzer.mle.runtime |
| com.wizzer.mle.math | The Magic Lantern Math Library | $(MLE_HOME)\Core\math\java\com.wizzer.mle.math |
| com.wizzer.mle.parts | The Magic Lantern Core Parts Library | $(MLE_HOME)\Parts\base\java\com.wizzer.mle.parts |
| com.wizzer.mle.parts.actors | The Magic Lantern Core Actor Library | $(MLE_HOME)\Parts\actors\java\com.wizzer.mle.parts.actors |
| com.wizzer.mle.parts.props | The Magic Lantern Core Property Library | $(MLE_HOME)\Parts\props\java\com.wizzer.mle.parts.props |
| com.wizzer.mle.parts.roles | The Magic Lantern Core Role Library | $(MLE_HOME)\Parts\roles\java\com.wizzer.mle.parts.j2d |
| com.wizzer.mle.parts.mrefs | The Magic Lantern Core Media Reference Library | $(MLE_HOME)\Parts\mediaref\java\com.wizzer.mle.parts.mrefs |
| com.wizzer.mle.parts.sets | The Magic Lantern Core Set Library | $(MLE_HOME)\Parts\sets\java\com.wizzer.mle.parts.sets |
| com.wizzer.mle.parts.stages | The Magic Lantern Core Stage Library | $(MLE_HOME)\Parts\stages\java\com.wizzer.mle.parts.stages |
Install Common Build Environment Dependencies
Windows Host
TBD
Linux Host
Before proceeding, make sure that you have installed and configured the Common Build Environment for Linux Platform.
Install Eclipse IDE for RCP Developers
The Eclipse development toolchain needs to be installed on the Ubuntu host development platform:
- tar -xvzf eclipse-rcp-2020-03-R-linux-gtk-x86_64.tar.gz -C ~/bin
- ~/bin/eclipse/eclipse
Add SSH key to Github Account
The Magic Lantern repositories on Github are configured to use SSH. In order to retrieve the source, you will need to generate an SSH key and install the key in your Github user account. Instructions for doing this step may be found at Adding a new SSH key to your Github account
Note that in order to avoid entering your passphrase each time you access a repository, you will want to add the key to your ssh-agent. Instructions for doing this may be found at Generating a new SSH key and adding it to the ssh-agent
Retrieve the Source
Using the Google 'repo' command, retrieve the Magic Lantern source:
$ mkdir Github-MagicLantern
$ cd Github-MagicLantern
$ repo init -u [email protected]:magic-lantern-studio/mle-manifests
$ repo sync
After the source code has been retrieved, it is necessary to stage the $MLE_HOME directory. To do this, links will be created from the MLE_HOME directory to the downloaded source located in Github-MagicLantern. Run the following script in the Github-MagicLantern directory:
$ ./mle-core-env/bin/scripts/stagemle.sh
Build SDK Jars
This section describes how to use Eclipse to build the Magic Lantern SDK for the J2SE Platform.
Each component provides an Eclipse project to facilitate building the component in Eclipse. To build a component, use the following instructions:
- From the main Eclipse toolbar, select the "File->Import..." menu entry. This will display the Import dialog.
- Select the "Existing Projects into Workspace" entry found under the General category.
- Select the "Next>" button in the Import dialog. The dialog should now be displaying the "Import Projects" page.
- Select a directory to search for existing Eclipse projects. Use the the "Browse..." button.
- The "Projects:" widget should now be showing you list of existing projects that are rooted in the directory specified in the above step. Select the project(s) of interest.
- To wrap-up the import, select Finish. The project will now be added to your Eclipse Workspace.
By default, Eclipse will build the component when the project is imported.
Construct Jar Packages
Windows Host
The .jar files can be constructed by using the Eclipwe Jar descriptors provided with the above Eclipse projects.
| Component | Jar Descriptor | Location |
|---|---|---|
| com.wizzer.mle.runtime | mlert.jardesc | M:/projects/MagicLantern/lib/runtime/mlert.jar |
| com.wizzer.mle.math | mlmath.jardesc | M:/projects/MagicLantern/lib/runtime/mlmath.jar |
| com.wizzer.mle.parts | parts.jardesc | M:/projects/MagicLantern/lib/runtime/parts.jar |
| com.wizzer.mle.parts.actors | actors.jardesc | M:/projects/MagicLantern/lib/runtime/actors.jar |
| com.wizzer.mle.parts.props | props.desc | M:/projects/MagicLantern/lib/runtime/props.jar |
| com.wizzer.mle.parts.roles | roles.desc | M:/projects/MagicLantern/lib/runtime/roles.jar |
| com.wizzer.mle.parts.mrefs | mrefs.desc | M:/projects/MagicLantern/lib/runtime/mrefs.jar |
| com.wizzer.mle.parts.sets | sets.desc | M:/projects/MagicLantern/lib/runtime/sets.jar |
| com.wizzer.mle.parts.stages | stages.desc | M:/projects/MagicLantern/lib/runtime/stages.jar |
Linux Host
The .jar files can be constructed by using the Eclipse Jar descriptors provided with the above Eclipse projects.
| Component | Jar Descriptor | Location |
|---|---|---|
| com.wizzer.mle.runtime | mlert-linux.jardesc | $HOME/projects/MagicLantern/lib/java/mlert.jar |
| com.wizzer.mle.math | mlmath-linux.jardesc | $HOME/projects/MagicLantern/lib/java/mlath.jar |
| com.wizzer.mle.parts | parts-linux.jardesc | $HOME/projects/MagicLantern/lib/java/parts.jar |
| com.wizzer.mle.parts.actors | actorst-linux.jardesc | $HOME/projects/MagicLantern/lib/java/actors.jar |
| com.wizzer.mle.parts.props | props-linux.desc | $HOME/projects/MagicLantern/lib/java/props.jar |
| com.wizzer.mle.parts.roles | rolest-linux.desc | $HOME/projects/MagicLantern/lib/java/roles.jar |
| com.wizzer.mle.parts.mrefs | mrefst-linux.desc | $HOME/projects/MagicLantern/lib/java/mrefs.jar |
| com.wizzer.mle.parts.sets | setst-linux.desc | $HOME/projects/MagicLantern/lib/java/sets.jar |
| com.wizzer.mle.parts.stages | stagest-linux.desc | $HOME/projects/MagicLantern/lib/java/stages.jar |
To build the Java archive, JAR, file for each component, do the following:
- In Eclipse, open the Jar Description File (e.g. mlmath.jardesc) for the corresponding component by double-clicking on the resource in the Package Explorer view. This will bring up the "JAR Export" wizard.
- Select the "Next>" button which will display the "JAR Packaging Options" dialog page.
- Deselect the "Save the description of this JAR in the workspace" button.
- Select the "Finish" button. The corresponding component JAR will be generated and placed in $MLE_HOME/lib/runtime.
Note: Use the "-linux.jardesc" files when building on the Ubuntu Linux development platform.
Generate Java Documentation
This section describes how to generate the Java documentation for the Runtime Engine and title parts.
For each component, do the following:
- In Eclipse, select the javadoc.xml (for linux: javadoc-linux.xml) for the corresponding component by right-clicking on the resource in the Package Explorer view.
- Then choose "Run As->Ant Build" to run the XML Ant script.
The HTML documentation will be generated under the package's "doc" directory.
Build Java Documentation Jar Packages
For distribution, the HTML documentation should be archived into Jar files.
To build the Java documentation archive file for each component, do the following:
- In Eclipse, open the Jar Description File (e.g. mlmathdoc.jardesc) for the corresponding component by double-clicking on the resource in the Package Explorer view. This will bring up the "JAR Export" wizard.
- Select the "Next>" button which will display the "JAR Packaging Options" dialog page.
- Deselect the "Save the description of this JAR in the workspace" button.
- Select the "Finish" button. The corresponding component JAR will be generated and placed in $MLE_HOME/lib/runtime.
:information_source: Note: Use the "-linux.jardesc" files when building on the Ubuntu Linux development platform.
Ant Build Environment
See the instructions on the Ant Build Environment for IDE J2SE Platform wiki page for details.
Makefile Instructions
The easiest way to build the mastering tools and libraries is to use the master targets in the top-level Makefile.
$ cd $MLE_HOME/build/linux
$ make master
$ make master_install
This should build the C++ source and install the mastering tools and libraries in $MLE_ROOT.
IDE for J2SE 2D Platform
Instructions for building the Magic Lantern IDE for J2SE may be found on the IDE Build Environment for Java2D Studio wiki page.
:information_source: Note: The IDE build instructions overlap the SDK instructions on this page; so there may be some duplicate information presented in those build instructions.
Java API Documentation
Online documentation for the Java SDK packages can be found on the following links: