Contribute your own Module

Contributing to Rex Modules is easy. There is a Github Repository that you can just clone and send pull requests.

You don't need to follow special style guidelines and if you have questions on how to implement something join us on irc.freenode.net / #rex.

A module skeleton (short way)

You can create a module skeleton with the rexify command:

bash# rexify Your::Module --create-module

This will create the directory structure Your/Module and all the initial files (as described below).

A module skeleton (long way)

First create a directory for your module:

bash# mkdir MyModule

Than create a file named __module__.pm inside this directory. This file is the base module file. If someone include your module it will load this file.

package MyModule;

use Rex -base;

task "mytask", sub {
   run "do-something";
};

1;

Now create a file named meta.yml. This file is needed for the indexer to index your module so that everyone can find it.

Name: MyModule
Description: My Simple Test Module
Author: your name 
License: The License (for example: Apache 2.0 or GPL)

Adding Files

If you want to add files to your Module, for example configuration files for a service like ntp.conf, you can add these files under the directory files.

bash# mkdir files
bash# touch files/ntp.conf

And than you can reference these files from within your module:

# upload ntp.conf to the server
file "/etc/ntp.conf",
   owner  => "root",
   group  => "root",
   source => "files/ntp.conf";

Templates

If you want to add templates to your Module, for example configuration files with variable content, you can add these templates under the directory templates.

bash# mkdir templates
bash# touch templates/ntp.conf.tpl

And than you can reference these files from within your module:

# upload ntp.conf to the server
file "/etc/ntp.conf",
   owner  => "root",
   group  => "root",
   content => template("templates/ntp.conf.tpl", var1 => "foo", var2 => "bar");

Documentation

Now add some documentation to your Module. For that open the file __module__.pm and go to the bottom of this file.

package MyModule;

use Rex -base;

task "mytask", sub {
   run "do-something";
};

1;

=pod

=head1 NAME

MyModule - Module to do some stuff

=head1 USAGE

Put it in your I<Rexfile>

 # your tasks
 task "one", sub {};
 task "two", sub {};
    
 require MyModule;

And call it:

 rex -H $host MyModule:mytask

Or, to use it as a library

 task "yourtask", sub {
    MyModule::mytask();
 };
   
 require MyModule;


Sending Pull Request

Now you can commit your module into your upstream repository at Github and send a pull request.

Fork me on GitHub