Project Build Settings

Build-time properties for an app are defined using a optional build.settings file written in Lua syntax. It should be placed in the project's base directory.

Basic Structure

At the minimum, the build.settings file should contain a settings table which will contain various child tables to dictate build-time options.

settings =
{
    --child tables here
}

Device Orientation

The build.settings file can be used to set app orientation in relation to the device's physical orientation in space — this includes auto-orientation triggered by the accelerometer if the device is rotated or flipped during runtime.

Important

Please note that there are three different things which are subject to orientation:

  1. The launch screen image (see Launch Images below).
  2. Native UI elements such as alerts and the visual keyboard.
  3. The Corona display stage itself.

All orientation settings must be contained in the orientation table within settings.

settings =
{
    orientation =
    {
        --parameters
    },
}

Within the orientation table, there are three optional key values: default, content, supported.

settings =
{
    orientation =
    {
        default = "",  --initial launch orientation
        content = "",  --locked orientation of the Corona stage, independent of Native UI elements (iOS only)
        supported = { },  --table of allowed options for auto-orientation
    },
}

Each of these must be set to one the following name conventions (or a list of these for the supported table).

Name Orientation
portrait Device in the vertical position with the home button at the bottom
portraitUpsideDown Device in the vertical position with the home button at the top
landscapeRight Device in the horizontal position with the home button at the right
landscapeLeft Device in the horizontal position with the home button at the left

Auto-Orientation

On most devices, auto-orientation is triggered by the accelerometer if the device is rotated or flipped during runtime. If you want to limit an app to landscape orientation, specify both landscape conventions in the supported table as shown below. To limit an app to portrait orientation, specify both "portrait" and "portraitUpsideDown".

settings =
{
    orientation =
    {
        default = "landscapeRight",
        supported = { "landscapeLeft", "landscapeRight" },
    },
}
Important
  1. When the device orientation changes, the coordinate position (0,0) on the Corona display stage will correspond to the top-left corner of the current orientation.

  2. The iPad ignores the default setting and attempts to launch in the current physical orientation of the device, assuming that orientation is specified in the supported list.

  3. On Android, if your supported list contains both a portrait and a landscape orientation, then your app will support all orientations on the device, except on some Android devices that don't support portraitUpsideDown at all.

  4. In iOS, you can optionally use the content key value to lock the Corona stage to a particular orientation. Native UI elements such as alerts or the visual keyboard will auto-orient, but the Corona display stage will remain locked. This is useful if you want to maintain a fixed coordinate system in an iOS app.

  5. If you ever need to detect the current device orientation, it can be read from the system.orientation property. This will return one of six values from a set of the four standard conventions plus faceUp and faceDown.

iOS Build Settings

Within the settings table, you can include a plist table nested within the iphone table, which encompasses all iOS devices, not just iPhone. This plist table is used to set values for the compiled app's Info.plist file.

For boolean values in plist keys, use Lua-style booleans (true and false ) rather than Objective-C booleans (YES and NO).

settings =
{
    iphone =
    {
        plist =
        {
            CFBundleDisplayName = "My Corona App",
            CFBundleName = "My Corona App",
            UIApplicationExitsOnSuspend = false,
            UIPrerenderedIcon = true,
            UIStatusBarHidden = true,
            UIAppFonts = { "AvenirLTStd-Black.otf","SourceCodePro-Black.ttf" },
            CFBundleIconFiles = { },
            MinimumOSVersion = "6.0",
        },
    },
}

In the example above, a few useful plist keys are shown:

Please see Apple's documentation for more information on supported values and what you can do with them.

PNG File 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. Note that including this key and setting it to true is not recommended and may result in issues when submitting apps to Apple.

Android Build Settings

Within the settings table, you can include a android table to control build setting for Android devices.

Version Code

An Android app should always have a version code declared with the versionCode key value. This is an internal number used to distinguish application releases for the Android Marketplace. It corresponds to the versionCode item detailed here. It is not visible to users.

  • The version code must be an integer — it cannot contain any decimal points.

  • The version code defaults to "1" if it's not set. However, this field should be specified and it must be set to a higher value when submitting an updated app to market. One possible scheme is to set versionCode to "10" for version 1.0. The next update would be "11" for version 1.1, and so forth. If you already submitted an app to the Android Marketplace but you didn't specify the version code, just add the versionCode key value and set it to "2" or higher.

Permissions

The usesPermissions table creates <uses-permission> tags in the AndroidManifest.xml file. It replaces the deprecated androidPermissions table, although that method is still supported for backwards compatibility.

settings
{
    android =
    {
        versionCode = "11",
        usesPermissions =
        {
            "android.permission.INTERNET",
            "android.permission.WRITE_EXTERNAL_STORAGE",
            "android.permission.ACCESS_FINE_LOCATION",
            "android.permission.ACCESS_COARSE_LOCATION",
        },
    },
}

In the example above, a few useful android.permission keys are exhibited.

  • "android.permission.INTERNET" — permits a Corona app to access the Internet.

  • "android.permission.WRITE_EXTERNAL_STORAGE" — allows media.save() and camera support.

  • "android.permission.ACCESS_FINE_LOCATION" — allows access to GPS.

  • "android.permission.ACCESS_COARSE_LOCATION" — allows getting the location from WiFi/CellularService.

See the Android documentation for more information on supported values and what you can do with them.

Features

The usesFeatures table creates <uses-feature> tags in the AndroidManifest.xml file. These parameters tell the Android Marketplace which hardware capabilities the app does or doesn't require. See the Android features reference for a list of supported values.

settings
{
    android =
    {
        usesFeatures =
        {
            { name="android.hardware.camera", required=true },
            { name="android.hardware.location", required=false },
            { name="android.hardware.location.gps", required=false },
        }
    }
}
Important

If you grant permission to a feature using the usesPermissions table above, Android assumes that this feature is also required. For example, if you grant permission to the CAMERA, the Android Marketplace will assume that a camera is required for the app to function. Thus, devices lacking a camera will not be able to download or purchase the app. As a precaution, if your app uses the camera for some features but does not require it for basic functionality, you should include this feature and set its required tag to false in the usesFeatures table.

{ name = "android.hardware.camera", required = false },

Expansion Files

The usesExpansionFile boolean indicates if the app should be built with expansion files. If it is set to true and the build target is Google Play, then everything in the project directory except the Lua scripts are put into the expansion file. Make sure you have Google licensing set up or the expansion files might not be downloaded. See the Android documentation for more information.

settings = 
{
    android =
    {
        --this tells the Corona Simulator to create an expansion file.
        usesExpansionFile = true,

        --the following permissions are required to download expansion files.
        usesPermissions =
        {
            "android.permission.INTERNET",
            "com.android.vending.CHECK_LICENSE",
            "android.permission.WRITE_EXTERNAL_STORAGE"
        },
    },
}

Large Heap

You can set your app to use a large heap by adding the largeHeap = true parameter. For example, you might need to raise the max heap size on a particular device from 32 MB to 256 MB, allowing a Corona app to load 2048×2048 images.

settings =
{
    android =
    {
        largeHeap = true
    }
}

Please note that this setting is for Android 3.0 and higher. Android 2.x devices will still run the app but they'll ignore this setting.

Plugins

Corona offers several plugins which can be used in your projects. These plugins can be included via the plugins table nested within the settings table. For example, the AdMob plugin may be included as follows:

settings = 
{
    plugins =
    {
        ["CoronaProvider.ads.admob"] =
        {
            publisherId = "com.coronalabs",
            supportedPlatforms = { iphone=true, android=true }
        },
    }, 
}

Note that the key name for this plugin (CoronaProvider.ads.admob) includes punctuation. Because of this, you must use the "brackets and quotes" version of defining its key. Even if a plugin name doesn't include punctuation, for example facebook, this method provides a level of consistency.

Plugins vary in terms of availability for different subscription tiers. Please refer to the plugins documentation for details on the plugin(s) you wish to utilize.

Custom App Icons

iOS

For iOS, you must create a series of app icons for the iOS devices you plan to support. Apple recommends that you also create a set of small icons for spotlight search results and settings. All icons should adhere to the standard iOS names and sizes listed below. Note that each icon has a definition for "normal" plus a Retina version appended with @2x. For detailed information on creating icons, please refer to the iOS Human Interface Guidelines.

File iOS Version Size (w×h) Usage
Icon-60.png >= 7.0 60 × 60 App Icon — iPhone
Icon-60@2x.png >= 7.0 120 × 120 App Icon — Retina iPhone
Icon-76.png >= 7.0 76 × 76 App Icon — iPad
Icon-76@2x.png >= 7.0 152 × 152 App Icon — Retina iPad
Icon-Small-40.png >= 7.0 40 × 40 Search/Settings — all devices  (recommended)
Icon-Small-40@2x.png >= 7.0 80 × 80 Search/Settings — all devices  (recommended)
Icon.png <= 6.1 57 × 57 App Icon — iPhone
Icon@2x.png <= 6.1 114 × 114 App Icon — Retina iPhone
Icon-72.png <= 6.1 72 × 72 App Icon — iPad
Icon-72@2x.png <= 6.1 144 × 144 App Icon — Retina iPad
Icon-Small-50.png <= 6.1 50 × 50 Search/Settings — iPad  (recommended)
Icon-Small-50@2x.png <= 6.1 100 × 100 Search/Settings — Retina iPad  (recommended)
Icon-Small.png <= 6.1 29 × 29 Search/Settings — iPhone  (recommended)
Icon-Small@2x.png <= 6.1 58 × 58 Search/Settings — Retina iPhone  (recommended)
 

These files should be included in the project's base directory. Additionally, you must specify them in the CFBundleIconFiles table.

settings =
{
    iphone =
    {
        plist =
        {
            CFBundleIconFiles = {
            "Icon.png",
            "Icon@2x.png",
            "Icon-Small-40.png",
            "Icon-Small-40@2x.png",
            "Icon-60.png",
            "Icon-60@2x.png",
            "Icon-72.png",
            "Icon-72@2x.png",
            "Icon-76.png",
            "Icon-76@2x.png",
            "Icon-Small-50.png",
            "Icon-Small-50@2x.png",
            "Icon-Small.png",
            "Icon-Small@2x.png"
            },
        }
    },
}

Android

For Android, icon files will be copied into the .apk during the build, if they are available in your project folder. These icons should adhere to the standard Android icon names and sizes listed below. For detailed information on creating icons, please refer to the Android Icon Design Guidelines.

File Size (w×h)
Icon-xxhdpi.png 144 × 144
Icon-xhdpi.png 96 × 96
Icon-hdpi.png 72 × 72
Icon-mdpi.png 48 × 48
Icon-ldpi.png 36 × 36

Ouya

If your Android app is targeting Ouya, then you must add the following app icon to your project folder.

File Size (w×h)
Icon-ouya.png 732 × 412

Launch Images

To enhance the user experience, you must provide at least one launch image (splash screen) to display when the app starts. It will appear until the app is fully ready to use, then your first screen/scene will appear and replace the launch image.

These images should adhere to the standard names and sizes listed below. Similar to icon files, these image files should be included in the project's base directory. However, you do not need to specify them in the plist table or in the android table.

File Size (w×h) iPhone/iPod iPad Android
Default.png 320 × 480  
Default@2x.png 640 × 960  
Default-568h@2x.png 640 × 1136    
Default-Portrait.png 768 × 1024  
Default-Portrait@2x.png 1536 × 2048    
Default-Landscape.png 1024 × 768  
Default-Landscape@2x.png 2048 × 1536    
Important
  • If you're developing an app for iPhone5 compatibility, you might be tempted to wait until the project is complete to create these launch images. However, you must at least include the Default-568h@2x.png file from the start, even if it's a blank image for testing. This activates the iPhone5 "tall" mode. As indicated above, this image must be exactly 640×1136 in size — do not flip it to 1136×640 for a landscape app.

  • On Android, if the width or height of the display is greater than 480 pixels, the larger image file(s) will be used.

  • Android displays all launch images in letterbox format, regardless of the scale setting in config.lua.

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 the tradeoffs entirely depend on the type of app and how you like to do error reporting.

In iOS, distribution builds are made by using a code signing identity whose name begins with iPhone Distribution: and on Android they are made by using a keystore with any name other than 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
    }
}