IDE Build Environment for Java2D Studio - magic-lantern-studio/mle-documentation GitHub Wiki
This page discusses how to build the Magic Lantern IDE for Java Standard Edition titles using Eclipse and Ant.
Table of Contents
- Dependencies
- Assumptions
- Environment Variables
- Details
- Test Magic Lantern Java2D Studio
- Generate Product Package
Dependencies
This section identifies dependencies for building the Magic Lantern IDE.
- Eclipse SDK, Eclipse IDE for RCP and RAP Developers Version: Oxygen.1a (4.7.1a) support is deprecated
- Apache Ant, version 1.8.0
- Oracle Java Development Kit (JDK), version 1.8.0_111
Windows Host Development Dependencies
If Microsoft Windows is being used to develop the Magic Lantern Java2D Studio toolchain, then the following dependencies are requried:
- Microsoft Visual Studio 2017 is installed. Note that Microsoft Visual Studio C++ v6.0, Microsoft Visual Studio C++ 2005 and Microsoft Visual Studio 2010 are no longer being supported.
Linux Host Development Dependencies
If Ubuntu Linux is being used to develop the Magic Lantern Java2D Studio toolchain, then the following dependencies are required:
TBD - add sudo calls here.
Assumptions
Windows Host Development Assumptions
Windows platform development makes the following assumptions:
- 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.
Linux Host Development Assumptions
Linux platform development makes the following assumptions:
- The Magic Lantern software has been downloaded into the "$HOME/Projects/MagicLantern" directory and the MLE_HOME environment variable is set to "$HOME/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
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" (for Windows) or "$HOME/Projects/MagicLantern" (for Linux).
MLE_ROOT Environment Variable
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" (for Windows) or "/opt/MagicLantern" (for Linux).
Note that this variable uses the UNIX-style path delimiter ('/').
MLE_WORKPRINTS Environment Variable
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 (for Windows) or "$HOME/Projects/MagicLantern" (for Linux).
The Magic Lantern Studio assumes that the Digital Workprints will be located under the $MLE_WORKPRINTS/workprints directory.
Note that this variable uses a canonical path style for the drive (i.e. //M/).
Details
This section discusses how to build the Magic Lantern IDE components targeting the Java Standard Edition (J2SE) platform. The Magic Lantern IDE 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 |
| com.wizzer.mle.codegen | The Magic Lantern Code Generation Plug-in | $(MLE_HOME)\tools\java\com.wizzer.mle.codegen |
| com.wizzer.mle.studio | The Magic Lantern Core Studio Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio |
| com.wizzer.mle.studio.framework | The Magic Lantern Utility Framework Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.framework |
| com.wizzer.mle.studio.dwp | The Magic Lantern Digital Workprint Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.dwp |
| com.wizzer.mle.studio.dpp | The Magic Lantern Digital Playprint Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.dpp |
| com.wizzer.mle.studio.branding | The Magic Lantern Branding Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.branding |
| com.wizzer.mle.studio.java2d | The Magic Lantern Core Java2D Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.java2d |
| com.wizzer.mle.studio.java2d.help | The Magic Lantern Java2D Help Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.java2d.help |
| com.wizzer.mle.studio.java2d.branding | The Magic Lantern Java2D Branding Plug-in | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.java2d.branding |
| com.wizzer.mle.studio.feature | The Magic Lantern Core Feature | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.feature |
| com.wizzer.mle.studio.java2d.feature | The Magic Lantern Java2D Feature | $(MLE_HOME)\Studio\plugins\com.wizzer.mle.studio.java2d.feature |
Build the Core util Library for Tools
These libraries are required by the Digital Workprint Reader below.
Windows Platform Build Instructions
The following Visual Studio solution will build the Core util libraries for the Magic Lantern Studio tools.
- Visual Studio 2017 Solution: "$MLE_HOME\Core\util\win32\build\msvc15\mleutil.sln"
- Visual Studio 2010 Solution: "$MLE_HOME\Core\util\win32\build\msvc10\mleutil.sln" (Deprecated)
- Visual Studio 2005 Solution: "$MLE_HOME\Core\util\win32\build\msvc8\mleutil.sln" (Deprecated)
- Visual Studio v6.0 Workspace: "$MLE_HOME\Core\util\win32\build\msvc6\MleUtil.dsw" (Obsolete)
The library components that are built include
| Library | Directory Location | Component |
|---|---|---|
| util.lib | "$MLE_HOME\lib\tools" | Magic Lantern Studio (Release) |
| utild.lib | "$MLE_HOME\lib\tools" | Magic Lantern Studio (Debug) |
Linux Platform Build Instructions
The instructions for building the Core util library for a Linux platform may be found on the Build the Core util Library for Tools wiki.
Build the Core math Libraries
These libraries are required by the Digital Workprint Reader below.
Windows Platform Build Instructions
The following Visual Studio solution will build the Core math libraries for the Magic Lantern Studio tools.
- Visual Studio 2017 Solution: "$MLE_HOME\Core\math\win32\build\msvc15\mlmath.sln"
- Visual Studio 2010 Solution: "$MLE_HOME\Core\math\win32\build\msvc10\mlmath.sln" (Deprecated)
- Visual Studio 2005 Solution: "$MLE_HOME\Core\math\win32\build\msvc8\mlmath.sln" (Deprecated)
- Visual Studio v6.0 Workspace: "$MLE_HOME\Core\math\win32\build\msvc6\mlmath.dsw" (Obsolete)
The library components that are built for the Magic Lantern Studio include
| Library | Directory Location | Component |
|---|---|---|
| mlmath.lib | "$MLE_HOME\lib\runtime\cdecl" | Magic Lantern Studio (Floating-point Release DLL) |
| mlmath.lib | "$MLE_HOME\lib\tools" | Magic Lantern Studio (Floating-point Release DLL Symbols) |
| mlmathd.lib | "$MLE_HOME\lib\runtime\cdecl" | Magic Lantern Studio (Floating-point Debug DLL) |
| mlmathd.lib | "$MLE_HOME\lib\tools" | Magic Lantern Studio (Floating-point Debug DLL Symbols) |
Linux Platform Build Instructions
The instructions for building the Core math library for a Linux platform may be found on the Build the Core math Library for Tools wiki.
Build Digital Workprint Reader
This section describes how to build the native, DWP Reader component used by the Java2D Studio.
Windows Platform Build Instructions
The following Visual Studio solution will build the DWP Reader.
- Visual Studio 2017 Solution: "$MLE_HOME\Studio\plugins\com.wizzer.mle.studio.dwp\src\win32\build\msvc15\JavaDWP.sln"
- Visual Studio 2010 Solution: "$MLE_HOME\Studio\plugins\com.wizzer.mle.studio.dwp\src\win32\build\msvc10\JavaDWP.sln" (Deprecated)
- Visual Studio 2005 Solution: "$MLE_HOME\Studio\plugins\com.wizzer.mle.studio.dwp\src\win32\build\msvc8\JavaDWP.sln" (Deprecated)
- Visual Studio v6.0 Workspace: "$MLE_HOME\Studio\plugins\com.wizzer.mle.studio.dwp\src\win32\build\msvc6\JavaDWP.dsw" (Obsolete)
The library of components that are built include
| Executable | Directory Location | Component |
|---|---|---|
| DwpReader.dll | "$MLE_HOME\Studio\plugins\com.wizzer.mle.studio.dwp\os\win32\x86" | Magic Lantern Digital Workprint Reader (Release) |
Linux Platform Build Instructions
Use these instructions for building the DWP Reader library for the Linux platform.
Import the Eclipse DwpReader project by selecting "File->Import...". This will bring up a Import dialog where you can choose "Existing Projects into Workspace" under the "General" tree item. Select "Next>" button to continue and browse to the "$MLE_HOME/Studio/DwpReader/linux/DwpReader" linux project.
In the Eclipse ProjectExplorer, right-click on the DwpReader project and select "Build Project" from the pop-up menu.
The library of components that are built include
| Executable | Directory Location | Component |
|---|---|---|
| libDwpReader.so | "$MLE_HOME/Studio/DwpReader/linux/DwpReader/libDwpReader/.libs/libDwpReader.so" | Magic Lantern Digital Workprint Reader (Debug) |
The DSO must then be installed in the com.wizzer.mle.studio.dwp.reader.linux plugin. To do this, open up a console terminal and type:
$ cd $MLE_HOME/Studio/DwpReader/linux/DwpReader/libDwpReader
$ make install_plugin
libDwpReader.so will be installed into the "$MLE_HOME/Studio/plugins/com.wizzer.mle.studio.dwp.reader.linux/os/linux/x86_64" directory.
Build Plugins for Eclipse IDE
This section describes how to use Eclipse to build the Magic Lantern IDE 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.
After importing the studio plugins, the Eclipse "Package Explorer" should look like the following image.
Figure 1: Eclipse Package Explorer
com.wizzer.mle.studio JAXB Dependency
The com.wizzer.mle.studio plugin is dependent upon JAXB. If this plugin fails to build because of this dependency, try following the instructions described in the JAXB Dependency wiki.
Build codegen Library
The codegen JAR library needs to be built
| Library | Component | Directory Location | Jar Description File |
|---|---|---|---|
| com.wizzer.mle.codegen | Code Generation Library | $(MLE_HOME)\tools\java\com.wizzer.mle.codegen | codegen.jardesc, codegen-linux.jardesc |
To build the Java archive, JAR, file for this component, do the following:
- In Eclipse, open the Jar Description File (e.g. codegen.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/tools.
:information_source: Note: Use the "-linux.jardesc" files when building on the Ubuntu Linux development platform.
Build Java2D Runtime Engine Libraries
This section describes how to build the Java libraries for the Runtime Engine and title parts.
The library of components that are built include
| Library | Component | Directory Location | Jar Description File |
|---|---|---|---|
| com.wizzer.mle.runtime | Core Runtime Engine Library | $MLE_HOME\Core\mlert\java\com.wizzer.mle.runtime | mlert.jardesc, mlert-linux.jardesc |
| com.wizzer.mle.math | Math Runtime Engine Library | $MLE_HOME\Core\math\java\com.wizzer.mle.math | mlmath.jardesc, mlmath-linux.jardesc |
| com.wizzer.mle.parts | Parts Runtime Engine Library | $MLE_HOME\Parts\base\java\com.wizzer.mle.parts | parts.jardesc, parts-linux.jardesc |
| com.wizzer.mle.parts.actors | Actors Runtime Engine Library | $MLE_HOME\Parts\actors\java\com.wizzer.mle.parts.actors | actors.jardesc, actors-linux.jardesc |
| com.wizzer.mle.parts.mrefs | Media Reference Runtime Engine Library | $MLE_HOME\Parts\mrefs\java\com.wizzer.mle.parts.mrefs | mrefs.jardesc, mrefs-linux.jardesc |
| com.wizzer.mle.parts.props | Properties Runtime Engine Library | $MLE_HOME\Parts\props\java\com.wizzer.mle.parts.props | props.jardesc, props-linux.jardesc |
| com.wizzer.mle.parts.roles | Roles Runtime Engine Library | $MLE_HOME\Parts\roles\java\com.wizzer.mle.parts.roles | roles.jardesc, roles-linux.jardesc |
| com.wizzer.mle.parts.sets | Sets Runtime Engine Library | $MLE_HOME\Parts\sets\java\com.wizzer.mle.parts.sets | sets.jardesc, sets-linux.jardesc |
| com.wizzer.mle.parts.stages | Stages Runtime Engine Library | $MLE_HOME\Parts\stages\java\com.wizzer.mle.parts.stages | stages.jardesc, stages-linux.jardesc |
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.
:information_source: 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.
:information_source: Note: you may need to refresh the "Package Explorer" view in Eclipse to see the new "doc" directory containing the new HTML documentation.
| Package | Directory Location | Ant Build File |
|---|---|---|
| com.wizzer.mle.runtime | $MLE_HOME\Core\mlert\java\com.wizzer.mle.runtime\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.math | $MLE_HOME\Core\math\java\com.wizzer.mle.math\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.parts | $MLE_HOME\Parts\base\java\com.wizzer.mle.parts\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.parts.actors | $MLE_HOME\Parts\actors\java\com.wizzer.mle.parts.actors\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.parts.mrefs | $MLE_HOME\Parts\mrefs\java\com.wizzer.mle.parts.mrefs\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.parts.props | $MLE_HOME\Parts\props\java\com.wizzer.mle.parts.props\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.parts.roles | $MLE_HOME\Parts\roles\java\com.wizzer.mle.parts.roles\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.parts.sets | $MLE_HOME\Parts\sets\java\com.wizzer.mle.parts.sets\doc | javadoc.xml, javadoc-linux.xml |
| com.wizzer.mle.parts.stages | $MLE_HOME\Parts\stages\java\com.wizzer.mle.parts.stages\doc | javadoc.xml, javadoc-linux.xml |
Build Java Documentation Jar Packages
For distribution, the HTML documentation should be archived into Jar files.
The archive of documentation that should be built include
| Package | Directory Location | Jar Description File |
|---|---|---|
| com.wizzer.mle.runtime | $MLE_HOME\Core\mlert\java\com.wizzer.mle.runtime | mlertdoc.jardesc, mlertdoc-linux.jardesc |
| com.wizzer.mle.math | $MLE_HOME\Core\math\java\com.wizzer.mle.math | mlmathdoc.jardesc, mlmathdoc-linux.jardesc |
| com.wizzer.mle.parts | $MLE_HOME\Parts\base\java\com.wizzer.mle.parts | partsdoc.jardesc, partsdoc-linux.jardesc |
| com.wizzer.mle.parts.actors | $MLE_HOME\Parts\actors\java\com.wizzer.mle.parts.actors | actorsdoc.jardesc, actorsdoc-linux.jardesc |
| com.wizzer.mle.parts.mrefs | $MLE_HOME\Parts\mrefs\java\com.wizzer.mle.parts.mrefs | mrefsdoc.jardesc, mrefsdoc-linux.jardesc |
| com.wizzer.mle.parts.props | $MLE_HOME\Parts\props\java\com.wizzer.mle.parts.props | propsdoc.jardesc, propsdoc-linux.jardesc |
| com.wizzer.mle.parts.roles | $MLE_HOME\Parts\roles\java\com.wizzer.mle.parts.roles | rolesdoc.jardesc, rolesdoc-linux.jardesc |
| com.wizzer.mle.parts.sets | $MLE_HOME\Parts\sets\java\com.wizzer.mle.parts.sets | setsdoc.jardesc, setsdoc-linux.jardesc |
| com.wizzer.mle.parts.stages | $MLE_HOME\Parts\stages\java\com.wizzer.mle.parts.stages | stagesdoc.jardesc, stagesdoc-linux.jardesc |
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.
Unit Testing
The following unit tests are available for testing the Java2D Runtime Engine components:
Test Magic Lantern Java2D Studio
In order to test the Magic Lantern Java2D Studio IDE toolchain from within the Eclipse development environment, follow the documentation on the Test Magic Lantern Java2D Studio wiki page.
Generate Product Package
A product definition for creating a distribution package is available in the com.wizzer.mle.studio.java2d.branding plugin. It is called java2dstudio.product. More information can be found on the Package Magic Lantern Java2D Studio wiki page.