Exporting and Running on your Embedded Target

A Storyboard application can be exported in several different ways. The output of the export process is what is considered a Storyboard Deployment Bundle. Depending on the bundle packaging these can be ran by sbengine, installed on an iOS/Android based mobile platform, executed on Windows as a normal application, or used by the user to compile into their RTOS application.

In the past deployment exports were done through a few different export wizards, but as of Storyboard 5.0 these have been consolidated into a single export configuration system. This export system allows the user to create, save, and share their application export parameters. These configurations can be customized through the Storyboard Application Export Configuration dialog.

Export Workflow

To export a Storyboard Deployment Bundle, right-click the Storyboard application file (*.gde) and select Storyboard Export, and choose the deployment type.

export_right_click_flavours.png

An export can also be launched by clicking on the Storyboard Application Export button in the toolbar. This button will launch the first export configuration found for the current application, or create one if none exist.

export_toolbar_launch.png

The Storyboard Export Configuration dialog will appear the first time an application is exported for deployment. This dialog allows you to customize how the application is exported and can be accessed at any time by clicking on the Storyboard Application Export Configuration button in the toolbar.

export_toolbar_config.png

The export dialog is separated into sections that take you through the required elements of an export.

export_dialog.png
Application Model To Export

The first export parameter block is the selection of which application model file (*.gde) files to export. Selecting more than one will cause these files to be merged when exporting the deployment bundle.

Generic Model Export Options

The second export parameter block lists generic Storyboard Model export options. These are options that are independent of the specific packaging format but apply generically to the model.

The Generate condensed output option determines if extraneous character information is removed from the exported model file.
The Generate precompiled Lua option will attempt to pre-compile the project's Lua scripts to bytecode prior to packaging. Only the top level files in the project's scripts directory will be compiled into platform independent bytecode. Compilation uses the same file names as the original files so this option is only available when the user is exporting to a directory other than the project directory.
Export Packaging

The third export parameter block determines how the exported model should be packaged. These packages and their options are described below.

Export Transfer

The final export parameter block is where the packaged content should be saved or transferred. Currently transfer methods include copy the package to the local filesystem or transferring it to a target over the network using scp. The transfer methods and their options are described below.

Once the user has finished customizing their export configuration they can click the Apply button to save the configuration and the export can be launched by click on the Run button. The application will then be exported according to the configuration.

Selecting Files For Export

All of the resources used by the application (images, fonts, scripts, translation files etc) must be available at runtime and included in the bundle packaging. The exporter will automatically select common resources but the packaged content can be customized using the Export Resources tab of the export wizard

The common resources extracted from the Storyboard application's project include:

  • The images directory content. These are image assets that are required by the application.

  • The fonts directory content. These are fonts that are required by the application

  • The scripts directory content. These are usually Lua script files that provide glue logic for the application

  • The translations directory content. These are usually translation files used by the application

Users may include additional content or exclude specific files as required by the application. The directory structure of the exported bundle package will reflect the same directory structure as used in the Designer project and should be maintained when the deployment bundle is moved to an embedded target.

Deployment Bundle Packages

Storyboard Embedded Engine (GAPP)

This will export the application as a GAPP file. The application resources will be transferred along with the GAPP file. This is the default package when exporting a new application.

Storyboard Compressed Package (SBP)

Export the application as a compressed package. The exported .sbp file will contain the application resources that were selected.

The following are parameters available for the Storyboard Compressed Packaged export

Encrypt exported package

The user can choose to encrypt the exported SBP package.

Native Android Application (APK)

Export the application as a Android Native Application. The exported .apk file will contain the application resources that were selected.

The following are parameters available for the Native Android Application export

Application Parameters

These parameters allow the user to change the application name, the APK file name, the application UID, and the application version information. Other parameters allow the user to change the application orientation, scaling, and whether the status bar is shown.

Application Name

The name that will appear on your device's UI for the app. This name doesn't have to be unique

Android Package File Name

This is the name of the apk file that is exported. This name has no effect once your application is installed.

Android Unique Application Identifier

This ID uniquely identifies your app on the device and in Google Play Store. It looks like a Java package name (ie. com.example.myapp).

Runtime Parameters

This is where the user specifies the Storyboard Runtime to export in the APK. The user can also specify runtime options here.

Manifest Parameters

Here the user can set their shared object list and add additional permissions to the Android manifest file.

Icon Parameters

Here the user can set the icons for the application.

Native iOS Application

Export the application as a iOS Application. The exported .app file will contain the application resources that were selected. This option is only available on MacOS development platforms and requires that the iOS mobile development environment be configured prior to export. This configuration is discussed in the chapter Exporting to iOS Devices.

The following are parameters available for the Native iOS Application export

Application Parameters

These parameters allow the user to change the application name, the company identifier, the signing identity and provisioning profile. Other parameters allow the user to change the application orientation, scaling, whether the status bar is shown.

Runtime Parameters

This is where the user specifies the Storyboard Runtime to export in the app. The user can also specify runtime options here.

Icon Parameters

Here the user can set the icons and launch screens for the application. There are different images for different types of iOS devices, i.e. iPhone, iPhone retina, iPad, iPad retina.

Windows Standalone Launcher (EXE)

Export the application as a standalone Windows application. The exported .exe file will contain the application resources that were selected.

The following are parameters available for the Windows Standalone Launcher export

Windows Standalone Launcher Parameters:

The user specifies the Storyboard Runtime to export in the exe. The user can also specify runtime options here.

Storyboard Embedded Resource Header (C/C++)

Export the application as a set of C/C++ header files. This will export one or more header files that can be used in conjunction with the Storyboard RTOS SDK product which generally requires a direct compilation of the Storyboard application into the system image. There are a number of parameters available for this export, the full context of use for these options are described in the Storyboard RTOS SDK users guide.

The following are parameters available for the C/C++ Resource Header export

Draw images directly from code storage (Flash/ROM)

This option relates to how the images used in the Storyboard application are going to be treated by the engine on the embedded system. Standard compressed image formats such as PNG or JPEG require decoding to a temporary buffer prior to display. This requires additional dynamic memory that may be beyond what the hardware platform has available. In order to support these smaller memory configuration systems with a graphically rich user interface, Storyboard Designer can pre-decode the images to a format that is directly compatible with the system's display output. When this occurs, the image data can stay resident in read-only memory and the Storyboard Engine can render it without incurring any additional dynamic memory overhead.

Export Model/Resources/Bitmap Fonts

The C/C++ header export is split into three separate header file choices one for model, one for the image and file resources and one for the bitmap fonts (if they are being used). By default these files will all point to the same header file location, but they can be separated if that is more suitable for your development purposes. The paths specified are paths that are relative to the output location set in the Transfer section.

The bitmap font header selection is only required if the platform configuration does not include a dynamic font rendering engine, such as FreeType. In the absence of a font engine, which would use the TrueType font files directly, the fonts and glyphs must be pre-rendered for use by Storyboard's bitmap font engine. The number of glyphs generated is dependent on the content of the font files and the quality of the font rendering is controlled by the Alphamap Font selection. The more bits that are used, the smoother the font will render but the larger the resulting data will be

Export Transfer Methods

Filesystem

Copy the deployment bundle to a directory on the filesystem. The user can choose to export to the project directory or select another directory on the filesystem to copy to. This is the default transfer method when exporting a new application.

SCP Transfer

Copy the deployment bundle to a target via scp. The user needs to enter the target address (either hostname, IP address or mDNS service name eg: 'mydevboard.local' if supported), the username and password, and the target directory they want to copy to. Selecting the Post Transfer Script option will allow the user to execute a script on their target post launch. This could be used to launch the application they exported.

After running a export the scp parameters will be saved as a global workspace preset that could be used with future exports. Currently only 10 presets are saved at a time.

Exporting from the Command Line

It also possible to perform headless exports of the Storyboard Design files to the Storyboard Embedded Engine files from a command line or scripting environment.

All of the Storyboard executables will be located in the PATH_TO_INSTALL/Storyboard_Designer directories, though on each desktop platform they are named slightly differently

Windows:

"..../Crank Storyboard.exe" -application com.crank.gdt.ui.gappexport
    model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
    output=<PathToGAPPFile>

Mac:

..../Storyboard.app/Contents/MacOS/Storyboard -application
    com.crank.gdt.ui.gappexport
    model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
    output=<PathToGAPPFile>

Linux:

..../Storyboard -application com.crank.gdt.ui.gappexport
     model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
     output=<PathToGAPPFile>

Note: Storyboard requires a display, so to run in a true headless environment a Virtual frame buffer needs to be setup.

Xvfb :1 -ac -screen 0 1024x768x8 export DISPLAY=:1
    ..../storyboard -application com.crank.gdt.ui.gappexport
    model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
    output=<PathToGAPPFile>

Where the model is the path to the Storyboard Designer model file. In the situation where multiple GDE model files are being joined together it is a comma separated list of model files where the first model file will be used for the start screen and the remaining models will be used for additional content. The output parameter specifies the filesystem path where the Storyboard Engine file will be created and the directory containing that file will be used to for the additional resource directories (scripts, images and fonts).

If the gde file that is being selected for export does not reside in the workspace that is going to be used by the comman line exporter, then the export configuration must be stored in the project. This is an option that is availble when modifying the export configuration. The following picture illustrates the selection that needs to be made:

export_storage_select.png

Note that the "Configuration Location" option is set to "Project". If the project resides in the same workspace that the command line exporter will be using, the configuration can be stored in either the workspace or the project

By default the exported gapp file will be compacted and not in a readable format. If a more readable format is desired, then the readable parameter can be passed along the command line such as:

..../Storyboard -application com.crank.gdt.ui.gappexport
     readable
     model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
     output=<PathToGAPPFile>

Exporting from the Command Line using Export Configuration

It is also possible to perform a headless export using a pre-configured export configuration. After configuring the export in Designer a user can export this from the command line or scripting environment.

All of the Storyboard executables will be located in the PATH_TO_INSTALL/Storyboard_Designer/storyboard directories, though on each desktop platform they are named slightly differently

Windows:

..../Storyboard.exe -application com.crank.gdt.ui.configexport
    model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
    configuration=<ConfigurationName>

Mac:

..../Storyboard.app/Contents/MacOS/Storyboard -application 
    com.crank.gdt.ui.configexport
    model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
    configuration=<ConfigurationName>

Linux:

..../Storyboard -application com.crank.gdt.ui.configexport
    model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
    configuration=<ConfigurationName>

Note: Storyboard requires a display, so to run in a true headless environment a Virtual frame buffer needs to be setup.

Xvfb :1 -ac -screen 0 1024x768x8 export DISPLAY=:1
    ..../storyboard -application com.crank.gdt.ui.configexport
    model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
    configuration=<ConfigurationName>

Where the model is the full path to the Storyboard Designer model file. This model file will be used to search for a export configuration. The configuration parameter specifies the configuration name. If this is provided then only the configuration with that name will be used in the export.

Additional Options

-data Is used to specify the workspace to be used when performing the export. This workspace should not be opened by other instances of Storyboard. This is helpful when running the configexport option in order for Storyboard to find your export configurations in your project. It is specified as follows:

..../Storyboard.exe -application com.crank.gdt.ui.configexport -data <PathToWorkspace>
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]> 
configuration=<ConfigurationName>

-consoleLog Is used to enable additional logging to the console.

-noExit Is used to prevent the application from closing automatically after performing the export. This is sometimes useful to keep the log console open post-mortem.

Was this article helpful?
0 out of 0 found this helpful