taskman/README.md

## Taskman 

Taskman is a simple library which allows to conveniently execute build 'tasks' written in PHP from the shell. Tasks can have dependencies on other tasks.

Taskman is inspired by Make, Capistrano, Ant, Maven and similar build tools.

The central unit of execution is 'task'. The main difference from the plain old function is the fact 'task' is executed **only once** no matter what. 

### Examples 

#### Hello world
Here's a simple example of a task:

```php 
<?php
namespace taskman;

task('hello', function() 
{
   echo "Hello world!\n";
});  
```  

Executing it from the shell yields:

```
./gamectl hello
***** task 'hello' start *****
Hello world!
***** task 'hello' done(0/0.27 sec.) *****
***** All done (0.27 sec.) *****
```

#### Real world example

```php
<?php
namespace taskman;

task('ultimate_build_run', 
  [
    'default' => true, 
    'alias' => 'urun', 
    'deps' => ['autogen', 'pack_configs', 'ensure_unity_player_settings', 'unity_defines']
  ], function() {});  
```  
### Get help and list all tasks 

You can list all tasks and their definition locations using **help** task (yes, it's a task as well):

```
./gamectl help
***** task 'help' start *****

Usage:
 gamectl [OPTIONS] <task-name1>[,<task-name2>,..] [-D PROP1=value [-D PROP2]]

Available options:
 -c    specify PHP script to be included (handy for setting props,config options,etc)
 -V    be super verbose
 -q    be quite, only system messages
 -b    batch mode: be super quite, don't even output any system messages
 --    pass all options verbatim after this mark

Available tasks:
---------------------------------
 apk_install_to_device (/Users/ps/dev/skeletor/gamectl.d/client.inc.php@58)
---------------------------------
 apk_run_on_device (/Users/ps/dev/skeletor/gamectl.d/client.inc.php@67)
---------------------------------
 autogen                           @deps ["unity_defines","cs_autogen","php_autogen"] (/Users/ps/dev/skeletor/gamectl.d/autogen.inc.php@6)
---------------------------------
 bhl_autogen                       @deps ["bhl_make_upm_package"] (/Users/ps/dev/skeletor/gamectl.d/bhl.inc.php@19)
***** task 'help' done(0/0.01 sec.) *****
***** All done (0.01 sec.) *****
```

You can filter tasks you want to get help for by a partial match as follows:

```
./gamectl help name
```

### Tasks documentation 

#### Task declaration

Task must be declared using library **task** function as follows:

```php
<?php
namespace taskman;

task('name', function() {});
``` 

The task above now can be invoked from the shell as follows:

```./gamectl name```

#### Task aliases

Task may have an alias for less typing in the shell. To specify an alias one should put it as an **alias** property of a task declaration:

```php
<?php
namespace taskman;

task('name', ['alias' => 'n'], 
   function() {});
``` 

You can invoke the task by the alias as follows:

```./gamectl n```   

#### Task dependencies

Task may have an dependencies on other tasks. To specify all dependencies one should list them in **deps** section of a task declaration:

```php
<?php
namespace taskman;

task('c', ['deps' => ['a', 'b']], 
   function() {});
``` 

All dependencies are executed before running the specified task. Running the task above yields something as follows:
```
./gamectl c
***** task 'c' start *****
***** -task 'a' start *****
***** -task 'a' done(0/0.18 sec.) *****
***** -task 'b' start *****
***** -task 'b' done(0/0.18 sec.) *****
***** task 'c' done(0/0.18 sec.) *****
***** All done (0.18 sec.) *****
```

#### Always executed tasks

Sometimes it's convenient to define tasks which should be executed every time without explicit invocation. For example for setting the up the default environment, properties, etc. To achieve that one should specify the **always** property for a task:

```php
<?php
namespace taskman;

task('setup_env', ['always' => true], 
   function() {});
``` 

### Build properties

It's possible to specify miscellaneous build properties to setup a proper build environment conditions. There's a set of routines provided by taskman for properties manipulation.

#### Setting a property

Use **set** built-in function:

```php
<?php
namespace taskman;

task('setup_env', ['always' => true], 
   function() {
      set("IOS_APP_ID", "4242jfhFD");
   });
``` 

#### Setting a property only if it's not already set 

Use **setor** built-in function. Property will be set only if it's not set some where before. It's a convenient pattern to have a default set of properties which can be overriden by the environment properties included from an external script.

```php
<?php
namespace taskman;

task('setup_env', ['always' => true], 
   function() {
      setor("IOS_APP_ID", "4242jfhFD");
   });
``` 

#### Getting a property

Use **get** built-in function:

```php
<?php
namespace taskman;

task('build_ios', 
   function() {
      shell("xcode build app " . get("IOS_APP_ID"));
   });
``` 

#### Getting a property or some default value

Use **getor** built-in function:

```php
<?php
namespace taskman;

task('build_ios', 
   function() {
      shell("xcode build app " . getor("IOS_APP_ID", "3232232"));
   });
``` 

#### Listing all build properties

To list all defined build properties one should use the **props** task:

```
./gamectl props

***** task 'props' start *****

Available props:
---------------------------------
UNITY_ASSETS_DIR : '/Users/ps/dev/skeletor//unity/Assets/'
---------------------------------
GAME_COMPANY_NAME : 'Black Hole Light'
***** task 'props' done(0.11/0.11 sec.) *****
***** All done (0.11 sec.) *****
```

You can filter properties you want to get information about by a partial match as follows:

```
./gamectl props FOO
```