Local module overview

Local Modules

This document explains how my Local::* modules work together to manage the installation of CPAN modules.

The Goal

The goal is to treat all the PCs I manage equally. These PCs are:

• Home PC running Windows, with internet access

  Perl and all modules are installed on C:.

• Work PC running Windows, with intenet access

  Perl and all modules are installed on D:.

• Various work PCs running GNU/Linux, without internet access

Local::* Modules

The modules are:

• Local::Build
• Local::CheckDistro
• Local::Config
• Local::Run3

Download Directory

This setup assumes that, for a given machine, there is one download directory, specified in .htlocal.conf.

Also, after a module is installed, the distro is moved (archived) into a sub-directory of that download directory.

Directories

The directory structure is:

	download-dir/
		|
		+- auto/
		|
		+- manual/
		|
		+- mine/
		|
		+- misc/

The Process

• Download a distro (or put one of mine into the download dir)

  The download directory can be tarred up and shipped to a PC without internet access.

• Run a program which installs the module and archives the distro

  Archival into auto/manual/mine is handled by auto.pl/manual.pl/mine.pl.

  These programs all live in the download directory, and use Local::Build. They only differ in the name of the archive directory.

  Lastly, these programs can all install N modules in one run. This is how pre-requisites are handled.

  See Local::Build's examples/ for these programs, and for build.pl, report-install-errors.pl, and other stuff.

• Occasionally, report which versions have been downloaded/installed/not-yet-installed

  A sample: http://savage.net.au/Perl-modules/html/local-module-report.html

Downloading and Installation of CPAN modules

• Modules which must be installed manually go into download-dir/manual

  Sounds contradictory, I know.

  For a new install of Perl, manual installation of some modules is inescapable, but afterwards even those modules can often be upgraded via the installer program.

  Also, some modules (e.g.: Module::Signature) ask questions during installation (grrr).

  Lastly, some modules (e.g.: Algorithm::Diff) are shipped as zip files.

  Of course I try to keep this set of modules as small as possible.

• Generally, modules go into download-dir/auto
• My modules go into download-dir/mine
• Modules I download and unpack in order to investigate but not install go into download-dir/misc

Handling Dependencies

Before downloading I examine the META.yml or Makefile.PL of modules I've decided to install, and record the dependencies in a TreePad (see Resources) document. See:

http://savage.net.au/Perl-modules/dependency-report.html

Note: Indentation means the given module depends on the moudules with indented names.

There are problems with this process:

• Lack of automation

  This is something I put up with for the moment.

• Changes in dependencies

  For this, I edit the TreePad file before I download a new version of a module.

  This is not a common as you'd think, since I don't install every version of a module.

Another goal, of course, is to determine if any human intervention is required (e.g. Module::Signature), so (most) modules can be installed with a CGI script.

Knowing these dependencies allows me to use auto.pl etc to install a set of modules in one hit.

See also Module::Dependency for graphical output of dependency chains. Unfortunately, its programs indexer.plx and cgidepend.plx ignore uninstalled modules (which is to be expected of course).

Manage Configuration with Local::Config

Obviously there are many ways of managing configuration. Here's mine...

I use one tiny config file.

Windows Configuration File

	# Warning: Under MS-DOS, do not use:
	# home=d:\
	# because the trailing \ means continuation to Config::General.
	# Instead, use Path::Class to join components of a path.

	home=d:
	module_dir=d:\perl-modules
	dsn=dbi:mysql:module
	username=me
	password=seekrit

GNU/Linux Configuration File

	home=/home/ron
	module_dir=/home/ron/perl-modules
	dsn=dbi:mysql:module
	username=me
	password=seekrit

Manage the Config File with Local::Config

The config file is called .htlocal.conf.

The format of the name makes it easy for Apache to control access to it, if you decide to put this file into a web-accessible directory.

So, module Local::Config does no more than read .htlocal.conf using Config::General.

Manage Distros with Local::CheckDistro

Local::CheckDistro has-a Local::Config object, and hence finds the download dir.

After that, it simply provides info on the set of distros I'm dealing with.

For instance, if there a 2 distros (versions) of the same module in the download directory, croak.

Manage Running Programs and Capturing Output With Local::Run3

This module just wraps IPC::Run3::run3 and returns the input and outputs streams nicely formatted, so that the output can be parsed easily.

Manage Installation with Local::Build

This module does the major part of the work.

It's used as in manual.pl:

	#!/usr/bin/perl

	use lib 'as/required';
	use strict;
	use warnings;

	use Local::Build;
	use Local::Config;

	# ----------------

	my($config) = Local::Config::get_config();
	my($build)  = Local::Build -> new
	(
		install_dir      => $ENV{'INSTALL'}, # Unix only.
		post_install_dir => "$$config{'module_dir'}/manual",
		uninstall        => 0,
		verbose          => 1,
	);

	for (grep{! /^$/} map{s/^(.*?)#(.*)$/$1/; s/^\s+//; s/\s+$//; $_} <DATA>)
	{
		last if (/__END__/);

		$build -> install($_);
	}

	# Notes:
	# o If module B depends on module A, list A first, then B.

	__DATA__
	#Local::Config
	#Local::CheckDistro
	#Local::Run3
	Local::Build

If the output of this is redirected to manual.log, then we can check for errors with:

	shell>perl report-install-errors.pl manual.pl manual.log

where report-install-errors.pl is no more than:

	#!/usr/bin/perl

	use strict;
	use warnings;

	use Local::Build;

	# ---------------

	my($installer) = shift || die("Usage: $0 installer.pl log.txt");
	my($log_file)  = shift || die("Usage: $0 installer.pl log.txt");

	Local::Build -> new() -> report_install_errors($installer, $log_file);

Manage Building a Distro with Local::Build

	shell>perl build.pl

where build.pl is no more than:

	#!/usr/bin/perl

	use Local::Build;

	Local::Build -> new() -> build('Local::Application', '1.23');

Resources

This document: http://savage.net.au/Perl-modules/html/local-module-overview.html

Dependency report: http://savage.net.au/Perl-modules/html/local-dependency-report.html

What's installed: http://savage.net.au/Perl-modules/html/local-module-report.html

The must-have list of Perl modules: http://savage.net.au/Ron/html/new-pc.html

TreePad (a tree-structured editor): http://www.treepad.com/

My repository: http://savage.net.au/Perl-modules.html

http://savage.net.au/Perl-modules/html/Local/Build.html

http://savage.net.au/Perl-modules/html/Local/CheckDistro.html

http://savage.net.au/Perl-modules/html/Local/Config.html

http://savage.net.au/Perl-modules/html/Local/Run3.html

Author

This document was written by Ron Savage in 2006.

Home page: http://savage.net.au/index.html

Copyright

Australian copyright © 2006, Ron Savage. All rights reserved.

	All Programs of mine are 'OSI Certified Open Source Software';
	you can redistribute them and/or modify them under the terms of
	The Artistic License, a copy of which is available at:
	http://www.opensource.org/licenses/index.html