This guide explains how to create a setup for running and developing the bot. Whether you want to just run it, or also develop it and test your changes, this guide lists the steps.
Since one of the bot's goals is provide an introductory space for Haskell, it details all the steps of starting to work with Haskell and provides hints. Even if you're just starting, this guide is friendly and useful to follow.
Here is a quick summary of what the bot API offers. It is being developed and more components will probably be added.
If you already have the Haskell tools installed, you can skip this section.
The bot is written in Haskell, a functional programming language. A good place
to start learning it is the
Haskell Wikibook. The definition of
Haskell is published in the form of reports, the latest being
the Haskell 2010 Report. While
learning, and actually in general, a very useful resource to keep open in a
browser tab is the API reference of the
To work with Haskell you'll need 3 primary tools:
You'll need to install them both. Preferrably GHC 7.10.3 and a recent release of stack. If you use a Debian based distro, you can install GHC easily from a PPA. Trisquel should import it for you, so all you need to do is apt-get install.
For Parabola, check the versions supplied by the distro's packages. Instructions for more distros can be found online.
~/.cabal/bin:/opt/cabal/1.22/bin:/opt/ghc/7.10.3/bin to your PATH. For
example, add this to the bottom of your
# add haskell programs to PATH export PATH=~/.cabal/bin:/opt/cabal/1.22/bin:/opt/ghc/7.10.3/bin:$PATH
The Haskell community has:
You can either use a release version, or the latest development version.
The development version many require recent dependency versions which aren't available on Hackage yet. If building fails, it's probably because you need those recent versions. These commands will download the dependencies most likely to be needed. In the same way you can download more.
If you'll be using the release version, there is no need for this.
Install Darcs, a version control system. The bot itself is in a Git repository,
but some of these dependencies are in Darcs repositories. You can either
download their files using regular HTTP, e.g. with
wget) or use Darcs. Since
Darcs is a popular version control system for Haskell projects (and is itself
written in Haskell), the latter option is demonstrated below (just change the
Darcs specific lines if you chose the former option).
If your distro has a recent enough version (at least 2.8.4):
$ sudo apt-get install darcs
Otherwise install Darcs from Hackage/Stackage:
$ stack install darcs-2.10.3
Get the bot code:
$ git clone https://notabug.org/fr33domlover/funbot.git
You now have the latest development version. You can switch to the latest
release version (use
git tag --list to find out its number), e.g.:
$ git checkout 0.3
Before running the bot, you'll need to configure 3 places:
1. State data, stored in JSON files in
Create initial state data:
$ cp -r state-default state
Some features (like channel logs and quotes) place files in separate subdirectories.
$ mkdir state/chanlogs state/quotes
2. Configuration file
First, you'll need to set up postgresql. You'll need one user and one database, owned by that user. Setting this up will vary slightly by operating system.
Then, you should funbot's config file to match your database:
$ cp config/settings-default.yaml config/settings.yaml $ vim config/settings.yaml
3. Configuration, in a Haskell source file,
Most of the settings moved to
config/settings.yaml, but a few still remain in
Config.hs. They will soon move too.
If you make a git commit, make sure you don't commit your personal changes.
$ vim src/FunBot/Config.hs
You'll need to rebuild the bot for changes in Haskell files to take effect.
$ stack build
You can also customize the event matching and behavior definitions in
Now you can do things like running it, debugging it, exploring it in the REPL (i.e. interpreter).
To run the bot:
$ stack exec funbot
To load the source into the GHCi, the REPL, and play/explore it:
$ stack repl
For the explorers, there is an IRC server package in Haskell, hulk. You could run the bot against a locally running instance of the server.
The Git repository contains a shell script
run.sh you can run in a cron job.
There is also a
supervisord configuration file. See these files for details.
If you want to run the bot as a separate system user (and not as your own
user), the steps are:
.bashrc) and install the setup as described above. But you don't need:
git pullthem, build/install and relaunch (e.g.
pkill funbot && dist/build/funbot/funbot &)
There are basically 3 ways to contribute code:
The details follow.
The steps are:
The branch can be in:
This means access to pushing to the
master branch of the upstream repository.
Open an issue in NotABug with the patch file attached (or post a link to it, if you host it somewhere else).