Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/melezhik/tomtit

Tomtit - Raku Task Runner
https://github.com/melezhik/tomtit

bash raku sparrow6 task-runner

Last synced: 20 days ago
JSON representation

Tomtit - Raku Task Runner

Host: GitHub
URL: https://github.com/melezhik/tomtit
Owner: melezhik
Created: 2019-05-03T21:11:43.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2024-01-04T08:43:47.000Z (11 months ago)
Last Synced: 2024-10-11T20:51:36.208Z (about 1 month ago)
Topics: bash, raku, sparrow6, task-runner
Language: Raku
Homepage:
Size: 376 KB
Stars: 5
Watchers: 3
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: Changes

Awesome Lists containing this project

README

# Tomtit

Tomtit - Raku Task Runner

# Build Status

[![SparkyCI](https://ci.sparrowhub.io/project/gh-melezhik-Tomty/badge?)](https://ci.sparrowhub.io)

# Install

```bash
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:

```bash
mkdir -p tasks/hello
```

`tasks/hello/task.bash`:

```bash
echo "hello world"
```

`.tomty/hello.raku`:

```raku
task-run "tasks/hello";
```

You can do _more_ then that, [read more](https://github.com/melezhik/Sparrow6/blob/master/documentation/development.md)
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`:

```bash
set -e
make
make test
sudo make install
```

`.tom/build.raku`:

```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](https://github.com/melezhik/Sparrow6/blob/master/documentation/dsl.md) provides
one with ready to use function for some standard automation tasks:

`.tom/example.raku`:

```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 => '[email protected]',
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:

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

our sub profile-data () {

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

}
```

The above module defines [Tomtit::Profile::Pets](https://github.com/melezhik/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

* Tomtit environments are configuration files, written on Raku and technically speaking are plain Raku Hashes

* Environment configuration files should be placed at `.tom/conf` directory:

.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;
my $who-are-you = config;

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:

```yaml
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

* [ake](https://github.com/Raku/ake) - a Raku make-a-like inspired by rake

# Author

Alexey Melezhik

# Thanks to

God Who gives me inspiration in my work