GitHub/pbot
3
0
Fork 0
mirror of https://github.com/pragma-/pbot.git synced 2024-11-25 13:29:29 +01:00
Code Issues Projects Releases Wiki Activity

doc: Update QuickStart with detailed information about installing Perl and CPAN modules

Browse Source
This commit is contained in:
Pragmatic Software 2021-07-14 18:33:35 -07:00
parent 381030ebd3
commit 80eb37f14c
2 changed files with 135 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
doc/QuickStart.md
View File

@ -1,40 +1,44 @@
# QuickStart # QuickStart
<!-- md-toc-begin --> <!-- md-toc-begin -->
* [Installation](#installation) * [QuickStart](#quickstart)
* [Installing Perl](#installing-perl) * [Installation](#installation)
* [Installing CPAN modules](#installing-cpan-modules) * [Installing Perl](#installing-perl)
* [re::engine::RE2](#reenginere2) * [Installing PBot](#installing-pbot)
* [Installing PBot](#installing-pbot) * [git (recommended)](#git-recommended)
* [git (recommended)](#git-recommended) * [Download zip archive](#download-zip-archive)
* [Download zip archive](#download-zip-archive) * [Initial Setup](#initial-setup)
* [Initial Setup](#initial-setup) * [Installing CPAN modules](#installing-cpan-modules)
* [Clone data-directory](#clone-data-directory) * [Installing cpanminus](#installing-cpanminus)
* [Configuration](#configuration) * [Installing and using local::lib](#installing-and-using-locallib)
* [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks) * [Using cpanminus](#using-cpanminus)
* [Libera.Chat](#liberachat) * [re::engine::RE2](#reenginere2)
* [IRCnet](#ircnet) * [Clone data-directory](#clone-data-directory)
* [Other networks](#other-networks) * [Configuration](#configuration)
* [Starting PBot](#starting-pbot) * [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks)
* [Usage](#usage) * [Libera.Chat](#liberachat)
* [rlwrap](#rlwrap) * [IRCnet](#ircnet)
* [Overriding directories](#overriding-directories) * [Other networks](#other-networks)
* [Overriding registry](#overriding-registry) * [Starting PBot](#starting-pbot)
* [First-time start-up](#first-time-start-up) * [Usage](#usage)
* [Using default settings](#using-default-settings) * [rlwrap](#rlwrap)
* [Using custom settings](#using-custom-settings) * [Overriding directories](#overriding-directories)
* [Custom recommended settings](#custom-recommended-settings) * [Overriding registry](#overriding-registry)
* [Custom recommended IRCnet/other network settings](#custom-recommended-ircnetother-network-settings) * [First-time start-up](#first-time-start-up)
* [Regular start-up](#regular-start-up) * [Using default settings](#using-default-settings)
* [Additional configuration](#additional-configuration) * [Using custom settings](#using-custom-settings)
* [Creating your bot owner admin account](#creating-your-bot-owner-admin-account) * [Custom recommended settings](#custom-recommended-settings)
* [Adding other users and admins](#adding-other-users-and-admins) * [Custom recommended IRCnet/other network settings](#custom-recommended-ircnetother-network-settings)
* [Adding channels](#adding-channels) * [Regular start-up](#regular-start-up)
* [Further Reading](#further-reading) * [Additional configuration](#additional-configuration)
* [Commands](#commands) * [Creating your bot owner admin account](#creating-your-bot-owner-admin-account)
* [Factoids](#factoids) * [Adding other users and admins](#adding-other-users-and-admins)
* [Plugins](#plugins) * [Adding channels](#adding-channels)
* [Modules](#modules) * [Further Reading](#further-reading)
* [Commands](#commands)
* [Factoids](#factoids)
* [Plugins](#plugins)
* [Modules](#modules)
<!-- md-toc-end --> <!-- md-toc-end -->
## Installation ## Installation
@ -44,22 +48,10 @@ PBot uses the [Perl programming language](https://www.perl.org/). Perl is usuall
part of a base Linux install. If you do not have Perl installed, please see your part of a base Linux install. If you do not have Perl installed, please see your
system's documentation to install it. system's documentation to install it.
### Installing CPAN modules If you do not have system administrator access, you can install Perl locally into
Some of PBot's features depend on the availability of Perl modules written by your home directory using, .e.g., [perlbrew](https://metacpan.org/pod/perlbrew),
third parties. To use such PBot features, the modules listed in the [`cpanfile`](../cpanfile) [plenv](https://metacpan.org/release/TOKUHIROM/App-plenv-v1.2.0/view/bin/plenv),
file need to be installed. [plx](https://metacpan.org/pod/App::plx), etc.
The CPAN modules may be installed with this command:
$ cpanm -n --installdeps . --with-all-features --without-feature compiler_vm_win32
#### re::engine::RE2
PBot uses the `re::engine::RE2` module for user-submitted regular expressions.
If you could not install it through CPAN, you must install it manually.
* https://github.com/google/re2
* https://github.com/dgl/re-engine-RE2/
### Installing PBot ### Installing PBot
@ -82,11 +74,89 @@ After git-cloning (or unpacking the ZIP archive) you should have a directory nam
Name | Description Name | Description
--- | --- --- | ---
[`lib/`](https://github.com/pragma-/pbot/tree/master/lib) | PBot source tree [`lib/`](../lib) | PBot source tree
[`script/`](https://github.com/pragma-/pbot/tree/master/script) | PBot executables [`script/`](../script) | PBot executables (e.g., [`script/pbot`](../script/pbot))
[`modules/`](https://github.com/pragma-/pbot/tree/master/modules) | External command-line executables invokable as PBot commands [`modules/`](../modules) | External command-line executables invokable as PBot commands
[`data/`](https://github.com/pragma-/pbot/tree/master/data) | Default data-directory [`data/`](../data) | Default data-directory
[`doc/`](https://github.com/pragma-/pbot/tree/master/doc) | Helpful documentation [`doc/`](../doc) | Helpful documentation
[`cpanfile`](../cpanfile) | CPAN dependencies file
There are a few one-time configuration things we must do to get PBot's environment
ready. Once the following steps are completed there is no need to do them again.
### Installing CPAN modules
Some of PBot's features depend on the availability of Perl modules written by
third parties. To use such PBot features, the modules listed in the [`cpanfile`](../cpanfile)
file need to be installed.
This can be a lengthly process as each module may itself have a certain amount of
dependencies and sub-dependencies. Perl is an extremely collaborative community!
Fortunately, you only need to install the CPAN modules once.
You must have `make`, `perl`, a C compiler, a C++ compiler, OpenSSL or LibreSSL
or equivalent, `libssl-dev`, and other such tools and libraries installed.
#### Installing cpanminus
The [cpanminus](https://metacpan.org/pod/App::cpanminus) tool is a fast and
lightweight way to install CPAN modules.
There are several ways to install cpanminus. If you have `wget` instead of `curl`,
then replace `curl -L` in the following commands with `wget -O -`.
* Option 1) Use your system package manager, e.g.:
$ apt install cpanminus
* Option 2) Install to `~/perl5` (if you used, e.g., perlbrew to install Perl):
$ curl -L https://cpanmin.us | perl - App::cpanminus
* Option 3) Download the `cpanm` executable directly to `~/bin`:
$ cd ~/bin
$ curl -L https://cpanmin.us/ -o cpanm
$ chmod +x cpanm
#### Installing and using local::lib
If you prefer to install the CPAN modules into `~/perl5` you can use [`local::lib`](https://metacpan.org/pod/local::lib).
If you installed Perl with, e.g., perlbrew or if you have system administrator privilege and prefer to install the CPAN modules
to the system Perl location, you may ignore this step.
The following command will install and set-up local::lib in `~/perl5`:
$ cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
#### Using cpanminus
Ensure you have set your current working directory to where you have git cloned
or unzipped PBot. There should be a [`cpanfile`](../cpanfile) in the current
directory, along with [`lib/`](../lib) and [`script/`](../script) directories.
$ cd pbot (or pbot-master)
The CPAN modules may be installed with (assuming you do not need Windows support):
$ cpanm -n --installdeps . --with-all-features --without-feature=compiler_vm_win32
If you want to install the bare minimum CPAN modules required for PBot's core functionality,
you can use the following command. But be aware that several plugins and modules may not
function.
$ cpanm -n --installdeps .
You may then choose to install the missing CPAN modules on a feature-by-feature basis using:
$ cpanm -n --installdeps . --with-feature=... --with-feature=...
where `...` is an optional PBot feature listed in PBot's [`cpanfile`](../cpanfile).
#### re::engine::RE2
PBot uses the `re::engine::RE2` module for user-submitted regular expressions.
If you could not install it through CPAN, you must install it manually.
* https://github.com/google/re2
* https://github.com/dgl/re-engine-RE2/
### Clone data-directory ### Clone data-directory
PBot uses a data-directory to store all its configuration settings and data. You must PBot uses a data-directory to store all its configuration settings and data. You must
@ -96,7 +166,6 @@ will become quite confused with each other and things will break horribly.
Here we clone the data-directory for two PBot instances, naming them after the Here we clone the data-directory for two PBot instances, naming them after the
IRC network they will connect to: IRC network they will connect to:
$ cd pbot (or pbot-master)
$ cp -r data libera $ cp -r data libera
$ cp -r data ircnet $ cp -r data ircnet
@ -274,8 +343,12 @@ This will create a user account named `Bob` with the `botowner` [user-capability
all channels. Note the wildcard replacing `some` in `some.domain.com`. Now as long as all channels. Note the wildcard replacing `some` in `some.domain.com`. Now as long as
your connected hostmask matches your user account hostmask, you will be recognized. your connected hostmask matches your user account hostmask, you will be recognized.
It is very important that user account hostmasks are defined as strictly or as narrowly
as possible to match only the person it is intended for. Ideally, the user would have a
NickServ account, a user-cloak given by the staff of the IRC server or a unique DNS name.
In your own IRC client, connected using the hostmask we just added, type the In your own IRC client, connected using the hostmask we just added, type the
following command: following command, in a private `/query` or `/msg`:
my password my password

7
doc/README.md
View File

@ -6,12 +6,15 @@
* [QuickStart](QuickStart.md#quickstart) * [QuickStart](QuickStart.md#quickstart)
* [Installation](QuickStart.md#installation) * [Installation](QuickStart.md#installation)
* [Installing Perl](QuickStart.md#installing-perl) * [Installing Perl](QuickStart.md#installing-perl)
* [Installing CPAN modules](QuickStart.md#installing-cpan-modules)
* [re::engine::RE2](QuickStart.md#reenginere2)
* [Installing PBot](QuickStart.md#installing-pbot) * [Installing PBot](QuickStart.md#installing-pbot)
* [git (recommended)](QuickStart.md#git-recommended) * [git (recommended)](QuickStart.md#git-recommended)
* [Download zip archive](QuickStart.md#download-zip-archive) * [Download zip archive](QuickStart.md#download-zip-archive)
* [Initial Setup](QuickStart.md#initial-setup) * [Initial Setup](QuickStart.md#initial-setup)
* [Installing CPAN modules](QuickStart.md#installing-cpan-modules)
* [Installing cpanminus](QuickStart.md#installing-cpanminus)
* [Installing and using local::lib](QuickStart.md#installing-and-using-locallib)
* [Using cpanminus](QuickStart.md#using-cpanminus)
* [re::engine::RE2](QuickStart.md#reenginere2)
* [Clone data-directory](QuickStart.md#clone-data-directory) * [Clone data-directory](QuickStart.md#clone-data-directory)
* [Configuration](QuickStart.md#configuration) * [Configuration](QuickStart.md#configuration)
* [Recommended settings for IRC Networks](QuickStart.md#recommended-settings-for-irc-networks) * [Recommended settings for IRC Networks](QuickStart.md#recommended-settings-for-irc-networks)