CBT - A Bundle of Corona SDK Build Tools

Concepts

You split your CoronaSDK based mobile app into many components.

Each component contains one or more .lua module files, a series of *_spec.lua unit-test files, a main.lua file used to run the unit-tests, and may also have some asset files (pictures and audio files).

The default location to store components under components/ folder, one sub-folder corresponds for one component. You create/edit your .lua files under the components/ folder, and use

$ cbt

to copy those files along with other component files to workspace folder, where you check the behavior of your component using Corona's simulator. Cbt command will figure out which component you are working on from the current git branch name (we will describe more options and commands later).

All your components are configured in config/components.yml file.

Every .lua file and asset file may have several platform-specific versions, include:

iOS: for iphone and ipad build
android: for android build
mock: provide a mock-up module for other component's development
debug: the default file that used for development and test

For example you may have Timer.mock.lua, Timer.android.lua ... Where cbt will chose one of them to use. Also, there is a mechanism to include platform specific code inside a file using Luobo syntax (we will reveal the details later).

Component Development

A workspace is a sub-folder under workspaces, like workspace/component_platform.

You use cbt checkout command to create and update a workspace.

For example,

$ cbt checkout --platform ios --require debug component_a

Will create (or update existing contents inside) workspaces/component_a_ios, the .lua and asset files for component components_a are copied to the workspace using their ios version, but files that components_a requires from other components will be copied using their debug version.

The default value for the developing component and required components are debug and mock, so

$ cbt checkout component_a

means

$ cbt checkout --platform debug --require mock component_a

Work with Dev-flow Tool

Create tasks with the component name in format like one of the follows

[++] component/component_name: xxxxxx
[++] comp/component_name: xxxxxx
[++] ct/component_name: xxxxxx

cbt commands will respect component_name as the current working component so you do not need to specify it in the command line:

$ cbt checkout

under ct/comp_a branch will checkout comp_a. Also, checkout is the default command for cbt tool, so the above command can be write as simple as:

$ cbt

(same as cbt checkout --platform debug --require mock component_a if you are in a proper git branch).

NOTE: do not edit any file under workspace folder. Usually you should add workspace in you .gitignore file.

Start A New Component

To begin a new component development, first you add an entry in config/components.yml like:

components:
  component_name1:
    lua_modules: [lua_file1, SomeClass<SuperClass]

This defined a component component_name1 and two .lua module files inside the component.

If your component only have one module .lua file and has the same name as the component itself, you can omit the module key in component definitions.

SomeClass<SuperClass means SomeClass will inherited from SuperClass.

Then you can:

$ cbt create component_name1

to create file skeleton for those .lua files under components/component_name1.

Then you:

$ cbt checkout component_name1

to create a folder under workspaces/component_name1, include the debug version of lua_file1.lua ... and mock version of ALL other files from other components.

$ cbt cleanup

$ cbt close

Will safely delete files and folders under workspace.

Platforms

Each .lua module file and asset file may has several platform-specific versions of them.

The current supported platforms include ios, android, mock and debug. You name you file like:

comp.ios.lua
comp.mock.lua
...

Debug is the default platform so you could use just comp.lua.

Asset files use the similar naming role, such as slash.png, slash.mock.png, slash.ios.png ...

The debug version component.lua is the default version, will be used if other version is not available. Ensure it exists otherwise cbt raise errors.

Usually you do not need a component.debug.lua (as component.lua is the debug version already), but you can provide this file if you will edit component.lua for a while, but do not prevent others from build a debug app use your stable version of component.lua file.

Luobo Converters

The mock version of the component should be implement as quickly as possible, provide only mocking functions of public APIs. This helps other component's development, as they can interact with a quick version of your component.

For ios, android and debug versions of your component, usually they are not so different so you do not need to separate them to different files. An other way to provide platform-specific code is use Luobo (search luobo-gem) converter's syntax:

IOS ->
  some_code_only_for_iOS

Android ->
  some_code_only_for_android

DEBUG ->
  ...

Use indent to end the code block. If you want no indent before your code, use:

IOS: noindent ->
  code_without_indent

Refer luobo-gem for more syntax details.

By this way, usually you only need platform-specific lua file component_name.lua and component_name.mock.lua, and occasionally provide a component_name.debug.lua while you make a long term development on that component.

API and SPEC tests

You should provide the same API for both build and mock version of your component.

You should have a component_lua_file_spec.lua file as unit test for each .lua module file.

This spec file should in Luobo::CoronaSpec format.

Components Diagram

Based on components.yml and API function definition in your source lua file (the debug version will be parsed),

$ cbt diagram

will create a series of diagram png file reflect component relationships under docs folder.

Class inherit relations and class method definitions will automatically handled. You can also create custom relationship with:

# diagram -> SomeLuaModule related to

Strings after SomeLuaModule will become label of Graphviz's edge (arrow).

When you done your development of all components, issue cbt build to create a device build of the whole app.

Build the Entire Application

For example if you have a application names dulcinea, you define main as lua_module in it, then you can build a distribution version as:

$ cbt checkout --platform ios --require_platform ios dulcinea

build is a alias of command checkout and will force require_platform to the same of platform option. So the above command also can be issued as:

$ cbt build -p ios dulcinea

Which will results a workspaces/dulcinea_ios folder that contains files you can use to build you application to distribute to AppStore.