Usage Generate

Generate

Once you have installed your packages the generate commands allow you to generate certain configuration files for your application. These commands will analyse all of the packages you have installed and add the appropriate entries into the specified output.

Application Descriptor

The most useful of these commands will be the generation of the application descriptor.

apm generate app-descriptor

The application descriptor is the file that contains all the details about your application, including name, version, icon imagery, initial view settings, platform settings such as manifest additions for Android, and the included extensions.

The process for creating app descriptor includes merging all the following and resolving conflicts where possible:

dependencies
Android manifest additions
iOS Info Additions and Entitlements
required configuration variables to be inserted into the above

Once complete you will have an application descriptor with all the required Android manifest additions, iOS InfoAdditions and Entitlements and extension IDs ready for use in your application.

What currently works?

Android merging with all package manifests is complete and you should expect to get a valid android manifestAdditions entry in your application descriptor.

iOS InfoAdditions and Entitlements are merged from packages and inserted into iPhone.InfoAdditions and iPhone.Entitlements.

The extensions node will be correctly populated with all the extensionID entries.

We are still looking for suggestions to better handle the output destination and suggestions on handling reading existing values. Currently we read the application descriptor destination and make modifications to it. We were considering building from a supplied template but figure the destination file probably is a good place for this.

By default the output will be written to src/${filename}-app.xml. filename will either be the value of the filename property in your project definition file, or the value of name (with all whitespace removed).

The command can be run with an optional output file to redirect the output to another location:

apm generate app-descriptor example-app.xml

In either case, the process will read any content that is found at the destination file and only overwrite the appropriate sections including:

namespace (to correctly set the AIR version)
id
versionNumber
versionLabel (if specified)
android / manifestAdditions
iPhone / InfoAdditions
iPhone / Entitlements
extensions

Other sections will remain the same, eg if you have a list of icons in the file they will remain.

Advanced configuration

You may wish to add in other configuration items, such as additional manifest entries. This can be done by supplying some additional configuration files.

You may wish to use this approach to integrate extensions that aren't supplied as an airpackage.

Application Descriptor Template

The generate command utilises an application template to inject the generated values into. By default this is the output destination file.

Generally we advise against creating this file. Instead the output application descriptor should serve this purpose and makes more sense. This is only useful in the situation where you want to completely define the application descriptor in a location separate from the output.

If you wish to provide a base application descriptor that will be used as the template for every call to apm generate app-descriptor you can create a file at the following location:

project.apm
config
|___ application-descriptor.xml

This file if present will be used as the base template and any changes made in the output file will be overwritten. So if you create this file it is important that you update it when developing.

The order of precedence of these templates is as follows:

config/application-descriptor.xml;

output path (either the command line parameter or the default src/${filename}-app.xml);

built-in template (if neither of the above are present);

Android

If you wish to provide additional manifest entries you can add a file at the following location alongside your project.apm:

project.apm
config
|___ android
  |___ AndroidManifest.xml

The AndroidManifest.xml file at this location will be merged with all the other manifest files from the other packages and added into your manifest additions. For example you may wish to set a specific minSdkVersion or targetSdkVersion for your application, you could then set the contents of this file to be:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" >

    <uses-sdk android:minSdkVersion="19" android:targetSdkVersion="30" />

</manifest>

Note: The file must have the correct manifest tag as above to be able to be processed correctly.

To create this file call:

apm generate config android

An appropriate default android manifest will be created for you in the correct path.

iOS

If you wish to provide additional plist entries you can add a file at the following location alongside your project.apm:

project.apm
config
|___ ios
  |___ InfoAdditions.xml
  |___ Entitlements.xml

The InfoAdditions.xml and Entitlements.xml files at this location will be merged with all the other manifest files from the other packages and added into your info additions and entitlements respectively. One can add one or both of these files. For example you may wish to set a specific minSdkVersion or targetSdkVersion for your application, you could then set the contents of the InfoAdditions.xml file to be:

<plist version="1.0">
<dict>

  <key>MinimumOSVersion</key>
  <string>9.0</string>

</dict>
</plist>

Note: The file must be in this plist format with the plist and dict nodes, as above, to be able to be processed correctly. This is the same format for InfoAdditions.xml and Entitlements.xml

To create these files call: