taskman/README.md

Taskman

Taskman is a simple library which allows to conveniently execute '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
namespace taskman;
use Exception;

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

Try executing it from the shell:

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

Real world example

<?php
namespace taskman;
use Exception;

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.) *****

Tasks documentation

Task declaration

Task must be declared using library task function as follows:

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:

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:

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.) *****

Task executed always

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:

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