[erebus.git] / README.md

Modular Python{2,3} IRC bot
===========================

Getting started
---------------
- `cp bot.config.example bot.config`
- `vim bot.config`
- Create a MySQL database, i.e. `CREATE DATABASE foo; GRANT ALL ON foo.* TO ...`
- `mysql <dump.sql`
- `./run.sh`

Install croncheck.sh in your crontab, if desired.  
`* * * * * /path/to/erebus/croncheck.sh`  
To suppress croncheck.sh from restarting the bot without removing from crontab, `touch dontstart`

Output will be placed in `logfile`, which is rotated to `oldlogs/`. (I strongly recommend `rm oldlogs/*` as a weekly crontab entry. `@weekly find /path/to/erebus/oldlogs/ -mtime 7 -execdir rm '{}' +`)

The bot targets both Python 2 and 3. However, it is generally only actively tested on Python 2.
If it's not working on Python 3 (or an included module isn't working on Python 3), please raise a bug.

Some modules require additional supporting materials, which can be found in `modules/contrib/`.


Module API
----------
The module API has largely remained backwards-compatible and likely will remain so into the future. However, it is still currently unstable, primarily because it's only tested with the included modules. If you find a change was introduced which breaks something you relied on, please raise a bug.

There is currently no documentation as to... well, anything. A good starter template for a new module is `modules/eval.py`. `modules/control.py` uses a significant subset of the API features available. `modules/foo.py` is intended as a demonstration module, and documents some of the major features.
Commit	Line	Data
7c7fddd2 J	1	Modular Python{2,3} IRC bot
7c7fddd2 J	2	===========================
a28e2ae9	3
7c7fddd2 J	4	Getting started
7c7fddd2 J	5	---------------
a28e2ae9	6	- `cp bot.config.example bot.config`
	7	- `vim bot.config`
	8	- Create a MySQL database, i.e. `CREATE DATABASE foo; GRANT ALL ON foo.* TO ...`
	9	- `mysql <dump.sql`
	10	- `./run.sh`
	11
	12	Install croncheck.sh in your crontab, if desired.
	13	`* * * * * /path/to/erebus/croncheck.sh`
	14	To suppress croncheck.sh from restarting the bot without removing from crontab, `touch dontstart`
	15
7c7fddd2	16	Output will be placed in `logfile`, which is rotated to `oldlogs/`. (I strongly recommend `rm oldlogs/*` as a weekly crontab entry. `@weekly find /path/to/erebus/oldlogs/ -mtime 7 -execdir rm '{}' +`)
a28e2ae9	17
	18	The bot targets both Python 2 and 3. However, it is generally only actively tested on Python 2.
	19	If it's not working on Python 3 (or an included module isn't working on Python 3), please raise a bug.
	20
	21	Some modules require additional supporting materials, which can be found in `modules/contrib/`.
	22
7c7fddd2	23
a28e2ae9	24	Module API
76dfe9af	25	----------
a28e2ae9	26	The module API has largely remained backwards-compatible and likely will remain so into the future. However, it is still currently unstable, primarily because it's only tested with the included modules. If you find a change was introduced which breaks something you relied on, please raise a bug.
	27
	28	There is currently no documentation as to... well, anything. A good starter template for a new module is `modules/eval.py`. `modules/control.py` uses a significant subset of the API features available. `modules/foo.py` is intended as a demonstration module, and documents some of the major features.