CBT - A Bundle of Corona SDK Build Tools
Concepts
You split your CoronaSDK based mobile app into many component
s.
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
or
$ 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.