2012-09-07

Setup a plugin development environment for Err

Err makes your life as easy as possible to extend it. Here I present you a quick walk-through to get you started.

First, clone err from git. I assume you are somewhere in your work/projects directory

.
⚫  gbin@sal work % git clone git://github.com/gbin/err.git
Cloning into 'err'...
remote: Counting objects: 1742, done.
remote: Compressing objects: 100% (638/638), done.
remote: Total 1742 (delta 1177), reused 1626 (delta 1061)
Receiving objects: 100% (1742/1742), 897.87 KiB | 552 KiB/s, done.
Resolving deltas: 100% (1177/1177), done.
⚫  gbin@sal work % 

Cool now, just copy the config template and prepare a data directory:

.
⚫  gbin@sal work % cd err 
⚫  gbin@sal err % cp errbot/config-template.py config.py
⚫  gbin@sal err % mkdir data

Then change the config to point the data directory and the log to this newly created directory in your config.py :

.
BOT_LOG_FILE = './data/err.log' # or an absolute path
BOT_DATA_DIR = './data/'        # or an absolute path

You know what ? you can already start your bot instance in development mode :

.
⚫  gbin@sal err % ./scripts/err.py -T
INFO:Config check passed...
INFO:Activate internal commands
INFO:Activating all the plugins...
INFO:Activate plugin: Webserver
INFO:Activating Webserver with min_err_version = 1.6.4 and max_version = 1.6.4
INFO:Webserver is not configured. Forbid activation
INFO:Activate plugin: VersionChecker
INFO:Activating VersionChecker with min_err_version = 1.6.4 and max_version = 1.6.4
INFO:Activate plugin: ChatRoom
INFO:Activating ChatRoom with min_err_version = 1.6.4 and max_version = 1.6.4
INFO:
INFO:Notifying connection to all the plugins...
INFO:Callback_connect
INFO:Plugin activation done.
Talk to  me >>

Note : do a ctrl-C or ctrl-D to quit

If you want to get even fancier, do a -G instead of -T (provided you have installed pyside), if not the bot will tell you how to do that.

.
⚫  gbin@sal err % ./scripts/err.py -G

So now, let's get a template of a plugin and tell err to take it into consideration

go to your work / projects directory and for example clone the helloworld project

.
⚫  gbin@sal err % cd ..
⚫  gbin@sal work % git clone git://github.com/gbin/err-helloworld.git
Cloning into 'err-helloworld'...
remote: Counting objects: 7, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 7 (delta 1), reused 7 (delta 1)
Receiving objects: 100% (7/7), done.
Resolving deltas: 100% (1/1), done.

go back to your err directory and change the config.py to point to this template

.
BOT_EXTRA_PLUGIN_DIR = '../err-helloworld' # or an absolute path

From there you see that the plugin is loaded and works:

.
INFO:Config check passed...
INFO:Activate internal commands
INFO:Activating all the plugins...
INFO:Activate plugin: Webserver
INFO:Activating Webserver with min_err_version = 1.6.4 and max_version = 1.6.4
INFO:Webserver is not configured. Forbid activation
INFO:Activate plugin: VersionChecker
INFO:Activating VersionChecker with min_err_version = 1.6.4 and max_version = 1.6.4
INFO:Activate plugin: ChatRoom
INFO:Activating ChatRoom with min_err_version = 1.6.4 and max_version = 1.6.4
INFO:Activate plugin: HelloWorld
INFO:Activating HelloWorld with min_err_version = None and max_version = None
INFO:
INFO:Notifying connection to all the plugins...
INFO:Callback_connect
INFO:Plugin activation done.
Talk to  me >>!status
INFO:received command = status matching [status] with parameters []
Yes I am alive... 
With those plugins (L=Loaded, E=Error, B=Blacklisted/Unloaded), C=Needs to be configured) :
    [L] ChatRoom
    [L] HelloWorld
    [L] VersionChecker
    [C] Webserver
   Load 0.07, 0.24, 0.28
   GC 0->301 1->5 2->4
Talk to  me >>!hello
INFO:received command = hello matching [hello] with parameters []
Hello World !
Talk to  me >>!help hello
INFO:received command = help matching [help] with parameters [hello]
this command says hello

So now, you just have to rename everything to your plugin name, and get started !

For deeper information, go to the plugin development docs.

Note: You can run err.py under debugger without any problem. I personally use pycharm and it works really well. I might make another tutorial for it in the future.

Enjoy !