Latest revision as of 23:56, 9 December 2013

Description

This page is meant as a how to guide for the beginner Ackis Module Programmer in the D programming language. The intention is to write this from a beginner level. No claims are made that this is the only way to approach writing an Ackis Module.

Setup

• Have a flavor of linux running
• Install build-essential, libmpfr-dev, and libgmp3-dev (required to build gdc)
• Install gdc for D2
  • Available via apt on debian systems
  • Install from source if necessary
• Install dub
  • Available from the dub github
  • Put the binary in your path
• Install libackis, kxml, libdjson, and libdmathexpr via "dub fetch <package>"

About each development component

• D is a programming language very similar to C++.
  • For example code see Ackis2.0#D_Implementation_by_Opticron
• GDC is a front end D interface for GCC. This will translate the D syntax into something the GCC compiler can understand.
• DSSS is a simple way to build your files. It will read through all of your 'import' lines in your code so that all you'll need to do is type "dsss build" in the same directory as your D program, and it will output your compiled program
• svn is a source control system. svn makes it easy to retrieve the libraries that others have written that you'll need in order to compile an ackis module.

Retrieving Dependent Libraries

• svn
  • In order for a D Ackis Module to compile, you're going to need some dependent libraries. The folders containing these libraries should be in the same directory as your D program's source code. You can retrieve these directories utilizing svn
    • svn co {link} {local directory}
    • Example Usage: svn co http://svn.dsource.org/projects/scrapple/trunk/tools/tools/ /myStuff/myDProgram/tools
    • All but one of the libraries needed to compile a D Ackis Module can be found at opticron's repository
    • The remaining library needed to compile a D Ackis Module is located here

Setting Up Ackis

Ackis Core

You will need to retrieve the ackis_core and client_dirc code from opticron's repository the same way you retrieved the supporting code for developing a module.

In the source code will be included a file: 'ackis.conf.sample'
Make a copy of this file and rename it to 'ackis.conf'

This is an optional line that you can add to your ackis.conf file. This line allows you to set a username and password for modules that will be authenticating to the ackis_core from an external machine. You can add as many of these as you'd like so that each module can have its own username and password.

 <user name="username" password="password"/>

You use this line to determine what port and address the core listens on. Address and port default to what is seen below, but both must be specified for a listener element.

 <listener port="16668" address="127.0.0.1"/>

This line is telling the Ackis Core to watch a module and restart it as necessary, but this feature is still under development. It should not be relied upon and is not necessary for the functioning of the core.

 <module location="mod_sample" name="sample" desc="Sample Module"/>

It may be helpful to build in debug mode in order to watch the interactions between the core and the components

 dsss build -debug=2

When switching to building binaries with debug enabled, it may be necessary to clean out the old built files before rebuilding:

 dsss clean

Ackis D IRC Client

Make a copy of 'dirc.conf.sample' and rename it to 'dirc.conf'

Reference the comments in this file for setting it up. This section of the configuration file allows channels to subscribe to events received from the core:

 <subscribe match="LinkSyn: .*"/>

Save your configuration file and compile

 dsss build

It may be helpful to compile in debug mode in order to watch and confirm the interactions between the components:

 dsss build -debug=2 -debug=libackis

Starting Your Ackis Module

For linux, if you would like your ackis module to start at boot time, you will need to add it to this file:

 /etc/rc.local

Development

Here is an example piece of code:

 // Hello World Module
 module mod_helloWorld;
 
 import libackis.ackiscomponent;
 
 int main (string[]argc) {
 	AckisComponent ackis = new AckisComponent("mod_helloWorld");
 	ackis.register("^helloWorld.*",&helloWorld);
 	ackis.regHelp("helloWorld","Have bot say hi to you.");
 	
       string user = "usernamegoeshere";
       string pass = "password goes here";
       
       ackis.setAuthCreds(user,pass);
       ackis.runProtocol();
 	return 0;
 }
 
 void helloWorld(AckisComponent ackis,string respid,string data,string type) {
   ackis.sendResponse(respid,"Hello World!");
 }

Breakdown of Code

 	ackis.register("^helloWorld.*",&helloWorld);
 	ackis.regHelp("helloWorld","Have bot say hi to you.");

The ".register" line is registering a callback. This is telling Ackis what function in your module to call when it sees a command (like '!helloWorld') in the channel.

The ".regHelp" is registering a specific help function built into Ackis, so that when the user types '!help helloWorld" Ackis will reply with your custom help message. In this example, the reply from Ackis would be "Have bot say hi to you."

       ackis.setAuthCreds(user,pass);

If your module is going to run on a different machine than the one the ackis_core is running on, you will need to include this line of code so that ackis_core knows to interact with your module.

       auto ackis = new AckisComponent("mod_X10","module","myaddress",myport,myuser,mypass);

Alternatively, use the line above when creating new AckisComponent.

       ackis.runProtocol();

The above line gives control to the ackisComponent class. Internally, this class is running a loop that does not exit unless the connection is lost, at which point the module exits. At the moment, this means that if connection to Ackis is lost, the running module will exit. Brainstorming is in process for a reconnection capability for future versions of the ackisComponent class. Omegix 16:20, 25 January 2010 (CST)

Other Useful AckisComponent Commands

 ackis.getVariable(respid,"user");

This will allow you to retrieve which user send the trigger command that your module has received.

Troubleshooting

Installation

• If "Error 256" shows up when compiling with dsss, it could be that the version of D is too old. Compile gdc from source.
  • This pay require you to compile gcc from source as well
    • Use "apt-get source gcc-4.6" to get the ubuntu specific source for gcc

find places for this on the wiki page

• Use this for configuring gdc prior to compiling
  • ../configure --enable-languages=d --disable-shared --with-bugurl="https://bitbucket.org/goshawk/gdc/issues" --enable-checking=release --enable-lto --enable-multilib

Notes from opticron

• 17:02:50 opticron | builds
• 17:02:56 opticron | good to go
• 17:03:14 opticron | look at the end of /etc/bash.bashrc
• 17:03:25 opticron | there are 3 lines that you need if you want to build properly
• 17:03:37 opticron | I forgot about them because I rarely setup on new systems