Perlba...nstall(3pm)

✨ Perlbal::Manual::Install 💖

okay bestie, welcome to the manual page for Perlbal::Manual::Install, from the User Contributed Perl Documentation collection (that's the 3pm section, iykyk). It's literally the "how do I get Perlbal on my machine" page, and it is giving very much "trust the process" energy. 🫶

---

🌸 VERSION

Perlbal 1.78. That's the version, periodt. 💅

---

🦋 DESCRIPTION

How to install Perlbal. That's it, that's the whole description. Short, sweet, iconic. 👑

---

🎀 Installing Perlbal for the impatient

okay so if you literally cannot wait even one more second, the speedrun route is the CPAN shell:

$ perl -MCPAN -e shell

cpan> install Perlbal

App::cpanminus is also super good at quickly installing Perlbal and all of its dependencies, no cap:

$ cpanm Perlbal IO::AIO Perlbal::XS::HTTPHeaders

...and that will give you an ideal Perlbal environment. chef's kiss. 💖

---

🌈 Installing Perlbal (with a little more detail)

So you need to have perl on the machine. If you don't have it yet, you can grab it from http://www.perl.org/. Go get it, bestie, it's free.

Having perl on the machine should give you access to the CPAN shell, which is one of several possible ways to install and upgrade Perl modules. Slay.

Start your CPAN shell:

$ perl -MCPAN -e shell

And now tell it to install Perlbal:

cpan> install Perlbal

In the end you should see a message stating "make install -- OK" 🎉 — and if that's not the case, please refer to the Troubleshooting section later in this document. We got you.

---

🧚 Installing Perlbal by hand (without using the CPAN shell)

Head to <http://search.cpan.org/dist/Perlbal/> and find the download link. Download the file and untar it:

$ tar zxvf Perlbal-X.XX.tar.gz

Note that X.XX stands for the version number. Replace that with the latest version you got. Don't be out here untarring X.XX for real, bestie, that's not a real version. 😭

Now you need to create the Makefile and run it; we're also going to run the tests before installing Perlbal:

$ cd Perlbal-X.XX.tar.gz

$ perl Makefile.PL

$ make

$ make test

$ sudo make install

---

⭐ Installing the latest development version

You can clone Perlbal's repository from github and install it by hand by following the next steps:

$ git clone http://github.com/perlbal/Perlbal.git

$ cd Perlbal

$ perl Makefile.PL

$ make

$ make test

$ sudo make install

main character energy, living on the edge with dev code. 👑

---

💜 Optional Dependencies and Asynchronous IO

It is very highly recommended that Perlbal::XS::HTTPHeaders is installed and enabled. Like, if you have poor performance, the very first thing to do is install Perlbal::XS::HTTPHeaders. First thing. Not the second thing. The first thing. 🔥

$ perl -MCPAN -e shell

cpan> install Perlbal::XS::HTTPHeaders

Enable it in your configuration:

XS enable headers

Perlbal checks for IO::AIO availability and uses it to perform asynchronous IO operations. If you're performing disk operations (e.g., using Perlbal as a web server), having IO::AIO will improve your response times. Faster = cuter, fr fr.

The only thing required in order to benefit from this feature is to install IO::AIO:

$ perl -MCPAN -e shell

cpan> install IO::AIO

If you don't have IO::AIO installed a warning message will be displayed when you start perlbal:

WARNING:  AIO mode disabled or not available.
          Perlbal will run slowly under load if you're doing any
          disk operations. (e.g. web_server mode).
          Install IO::AIO for better performance.

not the vibe check you wanna fail, bestie. install IO::AIO. 💅

---

🍓 Checking that Perlbal is successfully installed

Perlbal is shipped with some sample configuration files that reside in the conf directory (of the source).

You can give Perlbal a try by heading to the directory where the source is and using the following command:

$ sudo perlbal -c conf/webserver.conf

By pointing your browser at "localhost:80" you should now see Perlbal responding (showing you the contents of "/usr/share/doc"). Look at her go. 🌸

Note that the webserver.conf file sets up a Perlbal web server that listens on port 80. If you already have something listening on port 80 you need to either stop that service or change the port number on webserver.conf. Pick your fighter. ⚔️

Also note that if your machine doesn't have a "/usr/share/docs" directory you'll see an "ERROR: Directory not found for service docs" error message. Change the directory in the configuration file to something that exists.

---

💀 Troubleshooting

🙈 Prerequisites not found

If you're installing Perlbal by hand you may encounter some error messages describing how some prerequisites are not available:

user@machine:~/Perlbal-X.XX$ perl Makefile.PL
Checking if your kit is complete...
Looks good
Warning: prerequisite BSD::Resource 0 not found.
Warning: prerequisite Danga::Socket 1.44 not found.
Warning: prerequisite HTTP::Date 0 not found.
Warning: prerequisite HTTP::Response 0 not found.
Warning: prerequisite Sys::Syscall 0 not found.
Writing Makefile for Perlbal

This is perl's way of telling you that since you're installing Perlbal by hand you'll also need to install its prerequisites by hand. Your first choice is to download each of them separately and perform the same installation procedure for each. Unfortunately, they are all likely to have additional prerequisites. Recursively. 😭 it never ends.

Alternately, see the following Troubleshooting item: "No connection to the internet".

🌐 No connection to the internet

If you don't have a connection to the internet you can still install Perlbal, but you'll have to tranfer the source somehow to the machine.

Given that Perlbal has other module dependencies from CPAN (and those have their own dependencies too), here's a solution for this problem:

Step 1: On a machine with connection to the internet, install CPAN::Mini:

$ perl -MCPAN -e shell

cpan> install CPAN::Mini

Run "minicpan" to create a minimal CPAN mirror (it contains only the latest version of each module):

$ minicpan -l /home/user/minicpan/ -r http://cpan.org/

Now grab that directory and record it to something you can read on the other machine (e.g., a DVD, a hard drive). Physical media era, we love to see it. 💾

Once you're on that machine, you can run the CPAN shell and tell it to look for distributions on the local directory where you now have your own CPAN mirror:

$ perl -MCPAN -e shell

cpan> o conf urllist push file:///home/user/path/to/minicpan

cpan> install Perlbal

If you want "cpan" to record this change don't forget to commit:

cpan> o conf commit

🔥 No compiler available

If there's no compiler available on the machine you will probably see an error ending in something like:

Failed during this command:
 DORMANDO/Perlbal-X.XX.tar.gz : writemakefile NO '/usr/bin/perl Makefile.PL INSTALLDIRS=site' returned status -1

You need to install something like "gcc" (check <http://gcc.gnu.org/>).

After installing "gcc", when trying to install Perlbal again you may get another error message:

cpan> install Perlbal
Running install for module 'Perlbal'
Running make for D/DO/DORMANDO/Perlbal-X.XX.tar.gz
  Has already been unwrapped into directory /home/myself/.cpan/build/Perlbal-X.XX-GFko0J
  '/usr/bin/perl Makefile.PL INSTALLDIRS=site' returned status -1, won't make
Running make test
  Make had some problems, won't test
Running make install
  Make had some problems, won't install

This is the cpan shell assuming nothing changed in the system and skipping a few steps. You need to let it know you're willing to forget the past. therapy, but for cpan. 🫶

cpan> look Perlbal

$ rm -rf *

$ exit

ok bestie, heads up: that rm -rf * is literally what the page says to do, and it nukes everything in the directory you looked into. So make sure you are actually in that look directory before you send it. 💀

And now you can try installation again:

cpan> install Perlbal

---

🌟 SEE ALSO

Perlbal::Manual. Go read the whole family of pages, they're all iconic. ✨

---

and that's the page, bestie!! 🎀 you just read Perlbal::Manual::Install from Perlbal 1.78, and this whole thing came to you via the User Contributed Perl Documentation in section 3pm, on 2022-06-28, under perl v5.34.0. mwah. 💖✨👑