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.