Advanced Build Settings

This guide outlines various advanced build options for Solar2D apps.

This guide is intended for those who require more specialized configuration options and customized app settings. If you're looking for general/basic build settings and options, please consult the Project Build Settings guide.

Advanced Settings — iOS

Device Capabilities

If you wish to limit your iOS app to devices with specific capabilities, you can include the optional UIRequiredDeviceCapabilities key within the iphoneplist table. The value of this key should be a table containing specific keys matching Apple's documentation. For example:

settings =
{
    iphone =
    {
        plist =
        {
            UIRequiredDeviceCapabilities =
            {
                ["gyroscope"] = true,
            },
        },
    },
}

When including a specific key within the UIRequiredDeviceCapabilities table, its value is expected to be a boolean with this logic:

  • true — Devices must have the associated feature in order to run the app.
  • false — Devices must not have the associated feature in order to run the app.
Notes
  • You should only include a specific key if you absolutely must limit the app's target devices — if it doesn't matter whether a device supports a certain capability, omit its key.

  • Omitting a key's value will yield the same result as setting it to true. For instance, the following are equivalent:

UIRequiredDeviceCapabilities = { "gyroscope" }

UIRequiredDeviceCapabilities = { ["gyroscope"] = true }

PNG Processing

If you need to circumvent PNG file processing (pngcrush) at build time, you can include the skipPNGCrush key with a value of true. This key should be specified outside of the plist table but inside the iphone table:

settings =
{
    iphone =
    {
        plist =
        {

        },
        skipPNGCrush = true,
    },
}

Advanced Settings — Android

Minimum SDK Version

Providing a minimum SDK version with the minSdkVersion key value allows you to exclude your app from being installed on devices with older versions of the Android OS. It corresponds to the minSdkVersion item detailed here. This setting is invisible to users.

settings =
{
    android =
    {
        minSdkVersion = "16",
    },
}
Notes
  • The minimum SDK version must be specified as an integer — it cannot contain any decimal points.

  • Solar2D only allows values as low as "15" for Android 4.0.3 (the oldest version supported by Solar2D). For details on the various Android SDK versions and API levels, see here.

  • The minimum SDK version defaults to "15" if not specified otherwise.

Android TV

If you are deploying an app to Android TV, you should include the supportsTV key with a value of true. This will make the app available to Android TV devices via purchase through Google Play.

In addition, you can set the isGame key with a value of true to categorize the app under the games section of Google Play. If this key is omitted or set to false, the app will be categorized under the apps section.

settings =
{
    android =
    {
        supportsTV = true,
        isGame = true,
    },
}

Screen Support

The optional supportsScreens table specifies/limits which screens an Android app supports. See the Android documentation for detailed descriptions and more options.

settings =
{
    android =
    {
        supportsScreens =
        {
            smallScreens  = true,
            normalScreens = true,
            largeScreens  = true,
            xlargeScreens = false,
            requiresSmallestWidthDp = 320,
        },
    },
}

Disabling File Access

By default, other apps are granted read-only access to your app's files via an Android content:// URL. This is required to attach your app's files to e-mails, post photos via the social plugin, or open your files via the system.openURL() function. If you want to block all access to your app's files, set the following in the build.settings file:

settings =
{
    android =
    {
        allowAppsReadOnlyAccessToFiles = false,
    },
}
Note

You cannot block file access on Android devices which have been rooted. This applies to all Android apps, including those not built with Solar2D. Thus, if your app's files contain any sensitive information, it's recommended that you encrypt this information yourself.

Large Heap

You can request that the Android OS provides your app with more heap memory in Java by adding the largeHeap key with a value of true. For example, it may raise the max heap size on a particular device from 32 MB to 256 MB. This parameter might be a viable option if your app is triggering out-of-memory exceptions on low-end devices.

settings =
{
    android =
    {
        largeHeap = true,
    },
}

Android Directives

Important

This section details additional directives which can be used to fine-tune the AndroidManifest.xml in your application. They are rarely needed and if you don't understand what they do, you can break your application or cause unexpected behavior. Essentially, use of these directives is not recommended unless you're familiar with the concepts involved.

The following specialized directives are available for Solar2D-built Android apps:

  • strings — This directive enables the creation of a strings.xml file in the .apk.
settings =
{
    android =
    {
        strings =
        {
            permdesc = "Custom permission description",
            permlabel = "custom-permission-Label",
        },
    },
}
  • permissions — This directive enables the creation of custom Android permissions.
settings =
{
    android =
    {
        permissions =
        {
            {
                name = ".PERMISSION1",
                description = "@string/permdesc",
                icon = "@mipmap/icon",
                label = "@string/permlabel",
                permissionGroup = "android.permission-group.COST_MONEY",
                protectionLevel = "normal",
            },
        },
    },
}
  • manifestChildElements — This directive adds XML elements to the manifest element of AndroidManifest.xml.
settings =
{
    android =
    {
        manifestChildElements = 
        {
            -- Array of strings
            [[
            <uses-configuration android:reqFiveWayNav="true" />
            ]],
        },
    },
}
  • applicationChildElements — This directive adds XML elements to the application element of AndroidManifest.xml.
settings =
{
    android =
    {
        applicationChildElements =
        {
            -- Array of strings
            [[
            <activity android:name="com.example.MyActivity"
                android:configChanges="keyboard|keyboardHidden"/>
            ]],
        },
    },
}
  • apkFiles — This directive causes files to be copied from the project directory to the root of the .apk file, preserving any directory hierarchy. In the following example, google-play-services.json is copied to the root of the .apk and res/raw/mypage.html is copied to res/raw. The file paths are always relative to the base directory of the project.
settings =
{
    android =
    {
        apkFiles =
        {
            "google-play-services.json",
            "res/raw/mypage.html",
        },
    },
}
  • coronaActivityFlags — This directive allows attributes to be added to the com.ansca.corona.CoronaActivity activity definition in the app's AndroidManifest.xml. Activity attributes are documented here.

Solar2D uses the following attributes for its own purposes and they cannot be overridden:

Attribute
android:configChanges
android:label
android:launchMode
android:name
android:screenOrientation
android:theme
settings =
{
    android =
    {
        coronaActivityFlags =
        {
            resizeableActivity = true,
            persistableMode = "persistRootOnly",
        },
    },
}

Plugins — Supported Platforms

If necessary, you may fine-tune a plugin to be supported only on specific platforms. This is done by including a supportedPlatforms table with key-value pairs (value of true) which indicate the platform(s) that a plugin should be supported on. For example:

["plugin.gpgs"] =
{
    publisherId = "com.coronalabs",
    supportedPlatforms = { android=true },
},

Inside this table, the following keys are allowed:

Key Platform(s)
iphone all iOS devices
android all Android devices
appletvos Apple TV
macos macOS desktop
win32 Windows desktop
["android-kindle"] Amazon Kindle
["iphone-sim"] Xcode iOS Simulator
Note

Omitting the supportedPlatforms table effectively includes the plugin on all platforms that it inherently supports.

Build Control

Normally, distribution builds of an app (those intended for app stores) have Lua debug info stripped from the compiled code, while development builds are not stripped. Generally, stripping debug symbols is preferred for distribution because it reduces app size and provides a small performance gain, but this entirely depends on the type of app and how you prefer to do error reporting.

In iOS, distribution builds are made by using a provisioning profile whose name contains iPhone Distribution: and on Android they are made by using a keystore with any name except Debug.

Sometimes it can be useful to have debug symbols available in distribution builds of your app. This means that you get more detail in stack traces and runtime error messages. Depending on your needs, the neverStripDebugInfo setting can be used to turn off debug symbol stripping altogether. In theory, there's no reason why an app built with this setting could not be submitted to an app store, but policies vary and there are no guarantees — just be aware that the debug info may reveal details of your app that you may prefer remain proprietary.

settings =
{
    build =
    {
        neverStripDebugInfo = true,
    },
}