mgv has asked for the wisdom of the Perl Monks concerning the following question:

This is a combined SOPW/Meditation.

I have written and published to the CPAN a Perl program that has both a web and a CLI interface. I'd like to advertise the CLI interface in the web interface. To do this, I'd have to write some generic instructions for installing a module (App::MyProgram) from the CPAN.

I'm thinking of multiple possibilities: sudo cpan App::MyProgram, cpanm --sudo App::MyProgram (maybe with instructions for installing cpanm), possibly some talk about local::lib, possibly special instructions for Windows users. I am aware of tachyon's A Guide to Installing Modules, but it primarily talks about installing a module from a tarball instead of installing a module straight from the CPAN.

Therefore, What is a best practice piece of HTML that would enlighten a Perl-ignorant user on how to install a Perl module from the CPAN?

This problem gave me an idea. I could build a website that would contain detailed instructions for installing a module from the CPAN. Then I could add to my website's footer <a href="https://install-perl-module.com/App::MyProgram">Install App::MyProgram</a> and users would get the instructions, with copy-able commands that have the correct module name. User-agent sniffing could be used to show OS-specific instructions, and the website would show multiple ways to install the module, sorted by easiness/recommendedness.

Would anyone else find a website like this useful?

Replies are listed 'Best First'.
Re: "Best practice" instructions for installing modules
by 1nickt (Canon) on Aug 23, 2015 at 17:22 UTC

    Usually instructions on how to install a module are given in INSTALL or README.

    If you use Dist::Zilla to build your distribution, and include Dist::Zilla::Plugin::InstallGuide's [InstallGuide] directive in your dist.ini, it will create an INSTALL file automagically, the contents of which look as shown below. Note that you can easily make your own version of such a plugin to customize the instructions.

    This is the Perl distribution CMS-Drupal.

Installing CMS-Drupal is straightforward.

## Installation with cpanm

If you have cpanm, you only need one line:

    % cpanm CMS::Drupal

If you are installing into a system-wide directory, you may need to pa
+ss the
"-S" flag to cpanm, which uses sudo to install the module:

    % cpanm -S CMS::Drupal

## Installing with the CPAN shell

Alternatively, if your CPAN shell is set up, you should just be able t
+o do:

    % cpan CMS::Drupal

## Manual installation

As a last resort, you can manually install it. Download the tarball, u
+ntar it,
then build it:

    % perl Makefile.PL
    % make && make test

Then install it:

    % make install

If you are installing into a system-wide directory, you may need to ru
+n:

    % sudo make install

## Documentation

CMS-Drupal documentation is available as POD.
You can run perldoc from a shell to read the documentation:

    % perldoc CMS::Drupal

    [download]
    The way forward always starts with a minimal test.
[reply]
[d/l]
[select]

      Thanks for mentioning this module, I haven't heard of it. The README/INSTALL file is not relevant in my situation (as potential users are unlikely to see/read it).

      The instructions you pasted look insufficient for newbies. For example, don't you need to set up local::lib before/when installing with cpanm (without -S) or cpan as non-root?

      At this point I think I'd just suggest sudo cpan App::MyProgram, as it seems to be the most frictionless way to install a module (since the CPAN shell is usually already installed, as tye pointed out below). This however isn't enough for Windows users (for whom I should provide a link to Strawberry Perl) and users who don't have root access.

      Any opinions on the usefulness of the website I described in the second part of my article?

[reply]
[d/l]
[select]
Re: "Best practice" instructions for installing modules (bin/cpan)
by tye (Sage) on Aug 23, 2015 at 20:38 UTC

    For this scenario, I'd document using the cpan command to install the module as that is what is most likely to come with Perl.

    - tye        

[reply]

Back to Seekers of Perl Wisdom