You are not logged in. Log in. Or Sign up.

NOTE: Federation is disabled on this instance!

You can test federation between the following instances:
Vervis @ dev.angeley.es
HomeSharersfr33domloverReposfunbotFilesmaster INSTALL.md

Belongs to project FunBot

[[ 🧙 fr33domlover ]] :: [📥 Inbox] [📤 Outbox] [🐤 Followers] [🐔 Following] [🏗 Projects] [🗃 Repositories] [🔁 Workflows] [🐛 Tickets]
[[ 🏗 funbot ]] :: [📥 Inbox] [📤 Outbox] [🐤 Followers] [🤝 Collaborators] [🐛 Tickets] [✋ Ticket claim requests] [🔁 Ticket workflow: dummy ] [No wiki] [✏ Edit]

An IRC bot for learning, fun and collaboration in the Freepost community.

[[ 🧙 fr33domlover ]] :: [📥 Inbox] [📤 Outbox] [🐤 Followers] [🐔 Following] [🏗 Projects] [🗃 Repositories] [🔁 Workflows] [🐛 Tickets]
[[ 🗃 funbot ]] :: [📥 Inbox] [📤 Outbox] [🐤 Followers] [🤝 Collaborators] [🛠 Commits]

Branches

  • master
  • Tags

  • 0.1.0.0
  • 0.2
  • 0.3
  • 0.4
  • 0.4.0.1
  • 0.5
  • master ::

    INSTALL.md

    Intro

    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 honts. Even if you’re just starting, this guide is friendly and useful to follow.

    Programming Interface

    Here is a quick summary of what the bot API offers. It is being developed and more components will probably be added.

    Haskell

    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 base package, here.

    To work with Haskell you’ll need 2 primary tools:

    1. GHC - a compiler, interpreter, package manager and more
    2. Cabal - project manager for installing packages and packaging your own

    You’ll need to install them both. Preferrably GHC 7.8.4 and cabal-install 1.22. If you use a Debian based distro, you can install them easily from a PPA. Trisquel should import them 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.

    Add ~/.cabal/bin:/opt/cabal/1.22/bin:/opt/ghc/7.8.4/bin to your PATH. For example, add this to the bottom of your .bashrc:

    # add haskell programs to PATH
    export PATH=~/.cabal/bin:/opt/cabal/1.22/bin:/opt/ghc/7.8.4/bin:$PATH

    The Haskell community has:

    There are 3 types of package repositories you can maintain using Cabal:

    Update your list of packages:

    $ cabal update

    Installation

    You can either use a release version, or the latest development version.

    Create a directory for the bot:

    $ mkdir /home/joe/bot
    $ cd /home/joe/bot

    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 (preferrably 2.8.5, maybe 2.8.4 will work too):

    $ sudo apt-get install darcs

    Otherwise install Darcs from Hackage:

    $ cabal install darcs-2.8.5

    Get dependency source repos if/as needed:

    $ darcs get http://hub.darcs.net/fr33domlover/irc-fun-messages/
    $ darcs get http://hub.darcs.net/fr33domlover/irc-fun-client/
    $ darcs get http://hub.darcs.net/fr33domlover/irc-fun-bot/
    $ darcs get http://hub.darcs.net/fr33domlover/settings/
    $ git clone https://notabug.org/fr33domlover/funbot-ext-events

    Get the bot itself:

    $ 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

    Now your bot directory should look like this:

    $ ls /home/joe/bot
    funbot
    funbot-ext-events
    irc-fun-bot
    irc-fun-client
    irc-fun-messages
    settings

    Create a sandbox:

    $ cd funbot
    $ cabal sandbox init

    In order for all the extra packages to work in the sandbox, add the local dependencies you downloaded (if any) as sources:

    $ cabal sandbox add-source ../irc-fun-messages
    $ cabal sandbox add-source ../irc-fun-client
    $ cabal sandbox add-source ../irc-fun-bot
    $ cabal sandbox add-source ../settings
    $ cabal sandbox add-source ../funbot-ext-events

    Run cabal install --only-dependencies and cabal build to build funbot and its dependencies in the sandbox.

    Configuration

    The bot has state data in JSON files and in a Haskell source file, src/FunBot/Config.hs.

    Create initial state data:

    $ cd funbot
    $ cp -r state-default state

    In the Config.hs file there are safe defaults you can use as-is, but you should probably at least change the bot’s nickname. See here for documentation of the config options.

    $ vim src/FunBot/Config.hs

    You’ll need to rebuild the bot for changes in that file to take effect.

    You can also customize the event matching and behavior definitions in src/Main.hs.

    If you make a git commit, make sure you don’t commit your personal changes to the configuration. In particular if you set a nickname password there!

    Rebuild the bot:

    $ cabal build

    Some features (like channel logs and quotes) place files in separate subdirectories.

    $ mkdir state/chanlogs state/quotes

    Running and Exploring

    Now you can do things like running it, debugging it, exploring it in the REPL (i.e. interpreter).

    To run the bot:

    $ cabal run

    You can also run the executable directly:

    $ dist/build/funbot/funbot

    To load the source into the GHCi, the REPL, and play/explore it:

    $ cabal 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.

    Deployment

    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:

    1. Create a Linux system user with its own home directory. For example, /var/lib/ircbot
    2. Edit its PATH (e.g. by creating minimal .profile and .bashrc) and install the setup as described above. But you don’t need:
    3. Switch to the system user in the terminal and run the bot. Edit the configuration source file (nickname, password, channels, etc.). Setup the cron job.
    4. When there are updates to the bot or its dependencies, darcs pull or git pull them, build/install and relaunch (e.g. pkill funbot && dist/build/funbot/funbot &)

    Collaboration

    There are basically 3 ways to contribute code:

    The details follow.

    Merge Requests

    The steps are:

    1. Create a branch with your changes
    2. Open an issue containing the URL of the branch

    The branch can be in:

    Direct Commits

    This means access to pushing to the master branch of the upstream repository. Ask fr33domlover.

    Patches

    Open an issue in NotABugwith the patch file attached (or post a link to it, if you host it somewhere else).

    [See repo JSON]