Tutorial: Understanding “build.settings”

Share on Facebook0Share on Google+1Tweet about this on TwitterShare on LinkedIn0

Some developers, especially those new to Corona or app development in general, struggle with the settings and parameters which are necessary to successfully build an app for localized testing and, eventually, deployment to market. In Corona, these settings are dictated through the build.settings file, but inspecting a complex build.settings file can be intimidating. However, if you understand Lua tables and mentally separate this file into sections, you’ll better understand this crucial element of your project.


Essentially, the build.settings file contains information which determines which features must occur at build (compile) time. These are broken down into five primary areas:

  • Orientation — Controls what screen orientations the app will support.
  • iOS Settings — Specific features for iOS.
  • Android Settings — Specific features for Android OS.
  • Plugins — Loads the various plugins which the app may need to access.
  • Excluded Files (new) — Exclude certain files from your app builds (details).
  • Window behavior (new) — Configure some screen settings for desktop apps (details).

This all begins with a simple Lua table called settings:

In turn, this table should contain various key-value pairs for each of the five sections, and each of these tables may contain various nested key-value pairs, several of which we’ll explore in this tutorial.

Key-Value Declaration

These key-value sections can be defined in one of three ways, or a combination of all three, depending on your preference or, in some cases, the name of the key being defined.

1. Table Properties

2. Associative Array

Note that this method is required when your key contains special characters like a dash. For instance, if you need to state a key like hokey-pokey, you’ll need to specify it as settings["hokey-pokey"]and not as settings.hokey-pokey which is considered invalid by Lua. This will be important when defining plugins.

3. Nested Table Structure

Additional Notes

  • All three formats are perfectly valid, but the “standard” format shown in our samples and documentation is the nested table format.
  • Each of these key-value sections are optional. If you’re only building for iOS, you don’t need to include the android table. Conversely, if you’re only building for Android, you don’t need to include the iphone table. If you don’t use any plugins, you can omit the plugins table. And, while you don’t technically need an orientation table, you should provide one in almost every instance since it defines the allowed orientations for the app.
  • The order of these sections is not important, as long as you properly include them as key-value pairs.

The “orientation” Table

The orientation section is the easiest of the five — it merely defines which orientation is the “default” for the app, and which other orientations are allowed if the user turns/flips the device.

There are two keys for this table: default and supported. The default value is a string value which determines the orientation in which the app will start. Valid strings include:

  • "portrait"
  • "portraitUpsideDown"
  • "landscapeLeft"
  • "landscapeRight"

The supported value is an indexed table (no keys) which can contain any of the four options listed above, separated by commas. Note that this table should include the same value which you defined for default, in addition to any other orientations you wish to support. In the example above, the app will load in "landscapeRight" orientation, but it also allows for the flipped "landscapeLeft" orientation, thus providing a far better user experience.

The “iphone” Table

The iphone table contains all necessary settings in regard to building for iOS devices. Note the following:

This table must be typed as iphone (all lowercase) even though the device is usually printed as “iPhone” — this is a common issue for new users, so ensure that you’ve typed it as lowercase iphone.

The iphone table covers all iOS devices including iPhone, iPad, and iPod Touch, so you only need this one section to build for all of them.

The “plist” Sub-Table

The iphone table always contains another nested table called plist. This is a table whose values are copied into the Xcode project’s plist dictionary. So, if you need things in this list, add them here.

The keys within the plist table are the same as in Xcode, but the values are Lua-oriented. For instance, in Xcode there is a key-value pair UIApplicationExitsOnSuspend which accepts Xcode boolean values of YES or NO. However, Lua uses the true or false boolean notation, so to set this preference for a Corona app, your iphone table may include this:

Most iphone tables will include more than this, and some developers haphazardly copy this table from existing build.settings files without understanding its contents. Consider the following example:

This table may look complex, so let’s explore and explain the various elements:

  • CFBundleIconFile — This string value declares the “base” name of the app icon file. This value can usually remain as "Icon.png" (note that this is case-sensitive with a capital I).
  • CFBundleIconFiles — This is an indexed table (no keys) that tells iOS which icon files should be used on various devices. For an optimal user experience, you should include all of these string values, and you should create all of the associated icon files in the proper sizes as described in our guide.
  • UIApplicationExitsOnSuspend — This boolean value instructs iOS that the app should not terminate (quit) when it’s suspended. This value should be false in almost every instance.
  • FacebookAppID — To implement Facebook functionality, you’ll need to include this key-value pair. Your unique value can be obtained from Facebook as described in our guide.
  • CFBundleURLTypes — This is an indexed array of key-value pairs which describes the URL schemes supported by the app bundle (see Apple’s documentation for further details). Because of this structure, this table begins with an additional non-keyed sub-table. In the above example, we relate a URL scheme for Facebook, as explained in our guide.

Other Elements

This tutorial cannot discuss every element which may exist in the iphone table, so please refer to our guide and Apple’s documentation for more information.

The “android” Table

The Android is reasonably simple in most cases — typically it’s just a list of permissions and features. Note that you should include a usesPermissions table inside the android table which is an indexed list of permissions that you want to grant to the app. In the following example, we permit the Corona app to access the Internet.

A somewhat more complex version may include a usesFeatures table which tells the Android Marketplace which hardware capabilities the app does or doesn’t require.

Other Elements

This tutorial cannot discuss every element which may exist in the android table, so please refer to our guide and Google’s documentation on permissions and features.

The “plugins” Table

The final section to discuss is the table to support Corona SDK plugins. A basic example which enables the AdMob plugin would look like this:

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 the plugin name doesn’t include punctuation, this method provides a level of consistency:

This example also shows an important aspect of including plugins: the supportedPlatforms sub-table. If you use a plugin that is platform specific, you can use the supportedPlatforms key to instruct the Corona build servers to only include the plugin for a specific platform.

Why is Facebook considered “platform specific” in the context of plugins? Facebook functionality is, in fact, available to both iOS and Android developers, but as of Daily Build #2165, Facebook for iOS was removed from the core and it’s now implemented via a plugin. If you’re using this build or later, and you’re deploying for iOS, you must include the above ["facebook"] key in your plugins table, along with the supportedPlatforms sub-table.

Important Precautions!

1. Copying/Pasting Code Blocks

Commonly, developers copy and paste example code from the Corona documentation. This is fine, but you must be aware of — and fully maintain — the organization of all tables within build.settings. For example, don’t simply copy the settings table example for Facebook, then copy the settings table example for AdMob and paste it directly after.

Similarly, make sure that you don’t paste sub-tables into the wrong section, for example, inadvertently pasting a plugin block inside the iphone table.

2. Proper Indentation

It really helps to indent your code. Most modern code/text editors handle code indentation automatically, and it’s even more important to use proper indentation within build.settings because there will likely be a myriad of tables and sub-tables. With proper indentation, it will be far easier to keep your elements organized and readable.


The build.settings can seem overly complex, but at the core, it’s nothing more than nested Lua tables with key-value pairs, and the more comfortable you are with these aspects, the easier it is to construct a flawless build file for all platforms.

Share on Facebook0Share on Google+1Tweet about this on TwitterShare on LinkedIn0
Rob Miracle

Rob Miracle creates mobile apps for his own enjoyment and the amusement of others. He serves the Corona Community in the forums, on the blog, and at local events.

This entry has 14 replies

  1. Lerg says:

    I haven’t heard of “supportedPlatforms” attribute until recently, it really helps for the google play services plugin.

    One suggestion from me to that file is to add “ignore” table specifying what files and directories should not be included into end binaries.

  2. Felipe says:

    Is it possible to define custom settings here?

    How can I access build.setting table from main.lua?


    • Rob Miracle says:

      The build.settings is not accessible to Lua. It’s used by the build servers.

      • but you could copy build.settings to build.lua and get access to the lua tables that way, which is probably exactly what you want..

  3. Teodor says:

    I have this issue: in buildind an app i want the orientation to chenage only if is android or ipad! On iphone i want it only portrait! How cand i handle this in the build.settings file?

    • Rob Miracle says:

      You can’t. There is no processing that goes on in that file. You could always configure it for supporting orientation change and build for Android, and then for iOS build for iPad only. Then change the build.settings to support the single orientation on the phone and then build for the iPhone only. You can use Lua comments like –[[ and –]] to block out one orientation block while using the other.


  4. davey says:

    We have an app that was released about a year ago that had this functionality. The iPhone was portrait only and the iPad was portrait and landscape. Did something change? I tried my app files using 2014.2511 and it no longer works.

    Settings was set to default = “portrait” but then added in other supported orientations for ipad using this

    settings.iphone.plist[“UISupportedInterfaceOrientations~ipad”] =

  5. Fishy says:

    What type of file build.settings file had to be and how to imlement it into main.lua


    • Rob Miracle says:

      Technically speaking, build.settings is just a Lua table. It’s named .settings, but it’s just Lua code. It’s a separate file from your main.lua.


      • again, as i mentioned above, copy build.settings to build.lua and then you can access it in lua with require(“build”).. obvious, i know..

        • orangecyan says:

          Hi Stephen,

          I have to ask, too: My aim is to have an app with build settings that make a difference between smartphone and tablet as well: smartphone with portrait mode only, tablet with portrait+landscape.
          Renaming build.settings in build.lua in order to control the settings (inside or from main.lua) didn’t work (2015.2646).

          How can I do this?

          Thanks for help!

          • Rob Miracle says:

            You cannot simply rename build.settings to build.lua. It has to be build.settings. To do what you want to do is set the build.settings to support a single orientation and then do device detection and watch for orientation events in your code and rotate and re-layout your screen on a per-device, per-rotation setup.

  6. ethan Greene says:

    this goes in the config.lua file correct?

    • Rob Miracle says:

      No, you have a separate file in your project named “build.settings”. The contents described in this post go there. Contents in config.lua, while also a big Lua table are different.