Rand Stats

Tomtit

zef:melezhik

Tomtit

Tomtit - Raku Task Runner

Build Status

SparkyCI

Install

zef install Tomtit

Quick start

Tomtit is a task runner based on Sparrow6 engine, so just drop a few tasks under some folder and run them as Raku scenarios:

mkdir -p tasks/hello

tasks/hello/task.bash:

echo "hello world"

.tomty/hello.raku:

task-run "tasks/hello";

You can do more then that, read more about Sparrow6 tasks on Sparrow6 documentation.

Cli api

tom $action|$options $thing

Initialize tomtit:

tom --init

Run scenario:

tom $scenario

Default action (list of scenarios):

tom

List available scenarios:

tom --list

Get help:

tom --help

Show the last executed scenario:

tom --last

Clean Tomtit cache:

tom --clean

Example:

tom --list

[scenarios list]
test
build
install

tom test

Create scenarios

Tomtit scenarios are just Raku wrappers for underlying Sparrow6 tasks.

Create a .tom directory, to hold all the scenarios:

mkdir .tom/
nano .tom/build.raku
nano .tom/test.raku
nano .tom/install.raku

And the drop some tasks at some folder:

tasks/build/task.bash:

set -e
make
make test
sudo make install

.tom/build.raku:

task-run "tasks/build";

You might want to ignore Tomtit cache which commit files to SCM:

git add .tom/
echo .tom/.cache >> .gitignore

Using prebuilt Sparrow6 DSL functions

Sparrow6 DSL provides one with ready to use function for some standard automation tasks:

.tom/example.raku:

# you can use Sparrow6 DSL functions
# to do many system tasks, like:

# creation of files and directories

file 'passwords.txt', %( 
    owner => "root",
    mode => "700",    
    content => "super secret" 
);

directory '.cache', %(
    owner => "server"
);

# or restarting of services

service-restart "web-app";

# or you can run a specific sparrow plugin
# by using task-run function:

task-run 'my task', 'plugin', %( foo => 'bar' );

# for example, to set git repository, 
# use git-base plugin:

task-run "set git", "git-base", %(
    email => 'melezhik@gmail.com',
    name  => 'Alexey Melezhik',
    config_scope => 'local',
    set_credential_cache => 'on'
);

Profiles

Profiles are predefined sets of Tomtit scenarios. To start using scenarios from profile you say:

tom --profile $profile

Once the command is executed the profile scenarios get installed to the base Tomtit directory.

To list available profiles say this:

tom --profile

To list profiles scenarios say this:

tom --list --profile $profile

You can install selected scenario from profile by using special notation:

tom --profile $profile@$scenario

For example to install commit scenario from git profile:

tom --profile git@commit

Portable profiles

Tomtit exposes API to create portable profiles as regular Raku modules.

You should create Raku module in Tomtit::Profile namespace with the our function profile-data, returning Hash with scenarios data.

For example:

unit module Tomtit::Profile::Pets:ver<0.0.1>;

our sub profile-data () {

    my %a is Map  = (
        cat   => (slurp %?RESOURCES<cat.raku>.Str),
        dog   => (slurp %?RESOURCES<dog.raku>.Str),
        fish  => (slurp %?RESOURCES<fish.raku>.Str)
    );

}

The above module defines Tomtit::Profile::Pets profile with 3 scenarios cat, dog, fish installed as module resources:

resources/
  cat.raku
  dog.raku
  fish.raku

Now we can install it as regular Raku module and use through tom:

zef install Tomtit::Profile::Pets

Once module is installed we can install related profile. Note that we should replace :: by - (*) symbols when referring to profile name.

tom --list --profile Tomtit-Profile-Pets

load portable profile Tomtit::Profile::Pets as Raku module ...
[profile scenarios]
Tomtit::Profile::Pets@cat       installed: False
Tomtit::Profile::Pets@dog       installed: False
Tomtit::Profile::Pets@fish      installed: False

tom --profile Tomtit-Profile-Pets

install Tomtit::Profile::Pets@cat ...
install Tomtit::Profile::Pets@dog ...
install Tomtit::Profile::Pets@fish ...

(*) Tomtit require such a mapping so that Bash completion could work correctly.

Removing scenarios

To remove installed scenario say this:

tom --remove $scenario

Edit scenario source code

Use --edit to create scenario from the scratch or to edit existed scenario source code:

tom --edit $scenario

Getting scenario source code

Use --cat command to print out scenario source code:

tom --cat $scenario

Use --lines flag to print out with line numbers.

Environments

.tom/env/config.raku:

{
    name => "Tomtit",
    who-are-you => "smart bird"

}

Run Tomtit.

It will pick the .tom/env/config.raku and read configuration from it, variables will be accessible as config Hash, inside Tomtit scenarios:

my $name = config<name>;
my $who-are-you = config<who-are-you>;

To define named configuration ( environment ), simply create .tom/env/config{$env}.raku file and refer to it through --env=$env parameter:

nano .tom/env/config.prod.raku

tom --env=prod ... other parameters here # will run with production configuration

You can run editor for environment configuration by using --edit option:

tom --env-edit test    # edit test enviroment configuration

tom --env-edit default # edit default configuration

You can activate environment by using --env-set parameter:

tom --env-set prod    # set prod environment as default
tom --env-set         # to list active (current) environment
tom --env-set default # to set current environment to default

To view environment configuration use --env-cat command:

tom --env-cat $env

You print out the list of all environments by using --env-list parameters:

tom --env-list

Tomtit cli configuration

You can set Tomtit configuration in ~/tom.yaml file:

# list of portable Tomtit profiles,
# will be available through Bash completion

profiles:

  - Tomtit-Foo
  - Tomtit-Bar
  - Tomtit-Bar-Baz

# you can also setup some Tomtit cli options here

options:

  quiet: true

Options

--verbose          # run scenario in verbose mode
--quiet,-q         # run scenario in less verbose mode
--color            # color output
--no_index_update  # don't update Sparrow repository index
--dump_task        # dump task code before execution, see SP6_DUMP_TASK_CODE Sparrow documentation

Example of ~/tom.yaml file:

options:
  no_index_update: true
  quiet: true

Bash completion

You can install Bash completion for tom cli.

tom --completion
source  ~/.tom_completion.sh

Development

git clone https://github.com/melezhik/Tomtit.git
zef install --/test .
zef install Tomty
tomty --all # run tests

See also

Author

Alexey Melezhik

Thanks to

God Who gives me inspiration in my work