Willie tutorial, Part 1

#Willie Tutorial Part 1: Installation and first run

Important: This guide is written for version 4.0, which is soon to be released. The instructions in this guide will not all work on previous versions, or anything other than a clone of the current repository.

This tutorial is intended to give you an overview of all the features Willie has to offer. In this part, we'll start by getting Willie running, and then make a simple Hello, world! complete with proper documentation. This guide assumes you are running version 4.0 or higher of Willie. (You can find this by giving Willie the .version command.)

This guide assumes you have at least some familiarity with programming. You should know the basics of what functions are and stuff like that. Since Willie is written in Python, knowing Python will help, but if you've worked with most other languages you should be able to infer enough from the examples to get things done.

While this guide does cover a lot of what is available, there is much more than can be described here. The API documentation is available online, and serves as a useful reference.

Installing

There are a number of different places where you can get Willie. Since you're just starting out, we recommend that you download a stable version. On Fedora, you can do that with just sudo yum install willie, and on Arch you can install from the AUR (you'll have to Duck how to do that; I don't know the commands). On anything else, you can use pip install willie. (How to get pip will change based on your OS; on Linux, you can use your package manager. On Windows, Duck it.) Any of these methods will take care of installing Willie for you, and take care of any dependencies, so you can jump down to the next section.

You can also get the source in a .zip file. The latest stable version is available on our website. If you're familiar with git, you can clone our repository to get the latest code. With these methods, you have two options for running the bot. The first method is to simply run the willie.py file. We'll use the command willie in a few places further on in this tutorial; when you see that, just run ./willie.py instead. The second method has only been tested on Linux. You can run sudo ./setup.py install, which will install Willie. With this method, Willie will be installed just as it would from your package manager or pip, so you can then run it with willie.

Dependencies

Installing from a package manager or pip should take care of most of your dependencies. If you're not installing from one of these methods, or you're having problems (like errors when you start the bot), you should see this page to see what else you might need to do.

First run

To run Willie, just type the command willie in your terminal. The first time you run Willie, it will bring you through a quick setup wizard. Most of the questions should be pretty straightforward. When you see something in square brackets, that's the default setting, and you can just hit enter to keep it. When asked for the channels to conenct to, enter them one at a time, hitting enter after each one. This wizard doesn't cover every option, only the ones which are needed to get the bot running. We maintain a list of all the options for the core of the bot, if you want to make other tweaks.

Next, it will ask you about a settings database. You'll want to set this up, if you want to access a number of the cool features like per-user timezones. You have an option of sqlite, which should be available by default, and MySQL, which requires the MySQLdb Python module to be installed and a MySQL user and database you can write to (it can be running on your own machine, but doesn't have to be). The easiest option is sqlite; all you have to do is give it a valid filename, and it'll take care of creating the file and the database. If you request MySQL, it will ask you for the details for connecting to that database.

Finally, it will ask you about configuration settings for modules. This will automatically detect what modules you have available, and run their configuration utility if they have one. (We'll cover how to make those later on in this tutorial.) This page gives you a reference of what each option does.

Your configuration file will be stored in ~/.willie. The file will be called default.cfg by default. You can access the configuration wizard again by running willie -w. You can also get just the database config options with willie --configure-database and the module options with willie --configure-modules. You can specify another configuration file with willie -c filename. This works both for the configuration utility and for running the bot. This way, you can keep multiple different config files for different networks, for example. You can see a list of all these options by running willie -h or willie --help.

Once you've finished the configuration tool, Willie will automatically start, connect to the network, and join the channels you specified.