Debugging Guide

Using Break Points

One key concept in using an interactive debugger is the ability to stop your program at certain points so you can observe the current state. This includes looking at the value of variables in scope, stepping through the code one line or one function at a time, and checking the stack trace. This is known as using break points and it all revolves around stopping your program at the points you want to inspect.

You can enable or disable (toggle) break points in one of two ways:

• Click on the line of code and select Corona Editor → Corona Debugger → Toggle Breakpoint from the main menu.

• Right-click the line of code and choose Toggle Breakpoint from the popup context menu.

When you set a break point, a small Corona logo will appear on the line. Then, when you run your app from Sublime Text via Corona Editor → Corona Debugger → Run, it will stop when it reaches this line of code and return to Sublime Text. At this point, you have several options:

• Run — Run the code until the next break point or until completion.

• Step Over — This will step forward one line of code, and if it's a function, it will complete the function and stop on the next line of code.

• Step Into — This will step forward one line of code, and if it's a function, it will enter the function and stop on the first line of that function.

• Toggle Breakpoint — Turn off the breakpoint or set a new one.

• Inspect Variable — See Inspecting Variables below.

• Stop — Stop the program.

Inspecting Variables

From the main menu, select Corona Debugger → Inspect Variable. A search bar will open at the bottom of Sublime Text and you can enter any valid variable. You will then see the details of that variable, and if it's a table, this can provide a better visual representation compared to what is typically available.

Stack Tracing

Sometimes it's helpful to know where an error originated from. When you call a function and it misbehaves, a common reason is that the calling function passed invalid data. By using the stack trace, you can quickly identify which line of code called the function that you are currently executing. More specifically, you can set a break point in that function, continue running your app, and when the function exits and hits the next break point, you can examine the variables that were used to call the function.

For more information on the stack trace, see Viewing Runtime Errors below.

Viewing Runtime Errors

If you have Show Runtime Errors enabled in the Corona Simulator preferences, runtime errors (those that crash your app) will abort the program and reveal a message dialog box with more information about the error, including:

• The filename in which the error occurred in, for example main.lua.
• The line number within that file where the error occurred, for instance Line 218.
• The reason for the error, such as Attempt to perform arithmetic on a nil value..
• The stack trace which can help you locate the origin of the error, for example:

stack traceback:
    main.lua:218: in function 'start'
    main.lua:222: in main chunk

This collective information usually pinpoints the exact spot in your code where the problem lies. In this example, you can open the main.lua file, locate line 218, and look for a math operation where one of the values is nil — specifically, a place where you're attempting to perform math on an undefined variable. Furthermore, the stack trace reveals that the error resides within the function named start, and that function was called from line 222.

Sometimes, the stack trace is less specific and must be followed carefully. For instance:

?: in function <?:221>
    main.lua:218: in function 'start'
    main.lua:222: in main chunk

From this, you know that the error resides on line 221, but you must trace backwards for more details. In this case, the problem occurred on line 221, and that line was called from a function named start at line 218 of main.lua. Thus, even if the first line of the stack trace doesn't pinpoint exactly where the problem occurred, it can usually expose the root of the error.

Corona Simulator Console

Diagnostic output can also be viewed within the Corona Simulator Console. Here, useful debugging messages will be shown, along with the value of print() statements within your code. While this practice may be considered outdated to some developers, tracking the output of print() commands can often reveal the cause of an error or an issue with conditional logic.

Xcode Simulator — macOS

The above methods can help diagnose most coding issues, but the Xcode Simulator for macOS may be necessary to preview how the app will function on actual iOS devices. This helps simulate some device features that the Corona Simulator cannot, but it's still not as accurate as a real device.

To test an app in the Xcode Simulator:

1. Select File → Build → Build for iOS... from within the Corona Simulator.

2. In the dialog window, under the Build for: pull-down menu, select Xcode Simulator.

3. Proceed with the build process and the application will open in a simulated device window.

4. From this application, select Debug → Open System Log... to view the system log.

Device Debugging — iOS

Some errors only manifest themselves once you install the app on a device. Fortunately, each device has its own console log which you can access, and for Apple, you can see this console log within Xcode as follows:

1. Open Xcode if it's not already running.

2. Open the Devices window (Window → Devices).

3. Connect the device to your computer and wait until it appears in the left column of the window. When it does, select it.

4. Near the bottom of the window, click the small button (highlighted below) to open the device's console log.

Device Debugging — Android

Debugging on Android is a bit more "command line oriented," but once you figure out the commands, it's reasonably quick to install an app, view the log as the app runs, and look for error messages.

First, you must install some free tools from Google called Android Debug Bridge. Simply follow these steps:

1. Visit the download page. Instead of clicking the large download button, click on the Download Options link. Then, in the Get just the command line tools section, select the correct option for your system.

2. Install the tools. On Windows, run the installer; on macOS, unzip the file and move the folder to a sensible location.

3. Follow the instructions for Adding SDK Packages. Install at least the Android SDK Tools and Android SDK Platform-tools.

Once the tools are installed, you can use the command line tools. With your Android device connected, simply type the following command in the Terminal (macOS) or Command Prompt (Windows) and watch the messages appear. This command will filter out all messages except those generated by Corona.

adb logcat Corona:v *:s

Sometimes errors are generated by things besides Corona, for example messages from Google Play related to Google In-App Purchases. To see the entire log, use this command instead:

adb logcat

This will prevent filtering for Corona-specific activity, but it will generate a large number of messages and it will be difficult to locate those relevant to the problem. Thus, it may be helpful to include some print() statements within your code near the area which you suspect is problematic. For example:

print( "MYAPP - Purchase: *********************************************" )
store.purchase( "com.coronalabs.NewExampleInAppPurchase.NonConsumableTier1" )

If you prefer a more visual tool, adb also offers a GUI version of adb logcat called monitor. You may need to set your device to "developer mode" to use these tools, and each device and version of Android exposes this in different ways, so we suggest that you search online for your specific OS and "developer mode" to locate the instructions.

Debugging — Win32 Desktop

If you're working on a Win32 desktop app, some details on debugging can be located here.

Debugging — macOS Desktop

If you're working on a macOS desktop app, some details on debugging can be located here.

Proper Indentation

The most important practice for code readability is proper indentation (adding tabs or spaces before lines to distinguish blocks of code). You should use a text editor or Integrated Development Environment (IDE) which handles indentions for you. Consider this code:

local function doSomething( params )
if params.someValue == 10 then
if params.someOtherValue == "test" then
params.yetAnotherValue = params.someValue
end
end

Without indenting the lines to show the various blocks of code, it's very difficult to read. In fact, there's an error which would be obvious if the code was indented correctly. Compare the difference:

local function doSomething( params )
    if params.someValue == 10 then
        if params.someOtherValue == "test" then
            params.yetAnotherValue = params.someValue
        end
    end

As you can see, there is a missing end keyword for the doSomething function, and this is clearly revealed when the code is properly indented.

Many code editors can help you by automatically indenting code and, when you close a block, it will back out one level and put the end in the correct place. Each operating system has a selection of code editors, and better editors feature Lua syntax highlighting. For a list of recommended editors, please see our installation guides for macOS or Windows.

Descriptive Naming

Another important aspect is naming variables and functions so that you and others know what they mean. Consider these two blocks of code:

local function a( b )
    local c = b.target
    if c.x < 100 then
        c.alpha = 0
    end
    return true
end

local function touchEventHandler( event )
    local target = event.target
    if target.x < 100 then
        target.alpha = 0
    end
    return true
end

These functions are identical in behavior, but by using clearer variable and function names, most developers can easily figure out what you're trying to accomplish.

Device Considerations

Some developers are dismayed to find that their project works in the Corona Simulator but not on their actual device. Usually, one of the following factors is at fault:

• File names are not case-sensitive. When testing on macOS or Windows, file names are not case-sensitive, but when running on a device, the file names must match in case. For example, the file name titleimage.png and TitleImage.PNG are the same in the Corona Simulator, but they are considered different on a device.

• There is an error in the build.settings file, and often this is because the various blocks and tables are not properly nested. Please see the Project Build Settings guide for instructions on how to properly construct the build.settings file and each section within it.

• There's a problem with a plugin. Each plugin must be included exactly as specified, and several plugins require device permissions in order to function properly. Please see the appropriate plugin documentation for details.

Listener Removal

In some cases, an event listener function may still be running when you attempt to remove the listener, or a Corona library will be completing an internal process when you attempt to call a certain action. For example, you may attempt to remove a GPS listener while the GPS event is still being processed, or you may try to deactivate a physics body at the exact moment it collides with another object. Both of these are liable to cause an error/warning.

The solution to these type of issues is to perform the necessary action after a short timer delay:

local function handleGPS( event )
    timer.performWithDelay( 10, function() Runtime:removeEventListener( "location", handleGPS ); end )
end

Locating Solutions

If you have exhausted all of the above debugging methods, proceed to the Corona Forums. There you can search for topics which describe the same issue you're struggling with. Often, another developer will have reported the same issue and, in many cases, the thread will contain the solution — as such, please do not post a new topic without first searching for the answer in existing threads.

Note that new contributors will have their first post moderated — these will be entered into the system, but they will not be visible to others until approved by a moderator.

Requesting Assistance

If you cannot locate the solution in any previous forum threads, please post a new request and follow these guidelines:

• Do not post the same topic multiple times. Also, choose the most appropriate sub-forum for your topic, and abstain from posting the same topic in multiple sub-forums.

• Include enough information so that the community can help. You should provide the following:

  —  A detailed description of the problem you're having.
  —  A concise amount of code around the problematic area, if necessary.
  —  Whether you are using macOS or Windows.
  —  Whether you are building for iOS, Android, or Windows Phone.
  —  Which version/build of Corona you're using.
  —  The relevant error messages from your console log.
  —  Screenshots/images which can help the community visualize the problem.

• When including code within a forum post, surround it with [lua] [/lua] tags for clarity and readability:

[lua]
...
[/lua]

• To include screenshots or images, click the More Reply Options button below the message input box. On the next screen, use the Attach Files section to upload the image files. For YouTube or Vimeo videos, simply paste the video URL along with the message.