If new perl prerequisites are necessary, you should update the prerequisite CPAN bundles as described below.

NOTE: It is highly desirable, but NOT necessary, to test the install procedure on a system which has not had the perl modules installed directly to the system (for instance installing to /home/user/honeyclient/lib so that they can be wiped out once you want to test installation via the Bundle). In order to acomplish this, you will first have to set the PERL5LIB environment variable to the custom install directory (in bash this would be "export PERL5LIB=/home/user/honeyclient/lib" and then also set the appropriate CPAN variables

makepl_arg         INSTALLDIRS=site LIB=/home/user/honeyclient/lib

and if you have Module::Build installed (untested) it would be either mbuild_arg or mbuild_install_arg.

Placement in a Bundle

Things which are used by HoneyClient::Util OR things which are used by both HoneyClient::Manager and HoneyClient::Agent should go into the Bundle::Honeyclient::Util CPAN bundle.

Expand the bundle in question. For instance

debian:/home/user/honeyclient/cpan/sources/authors/id/M/MI/MITREHC# tar xzvf Bundle-HoneyClient-Agent-1.0.1.tar.gz
Bundle-HoneyClient-Agent-1.0.1/
Bundle-HoneyClient-Agent-1.0.1/README
Bundle-HoneyClient-Agent-1.0.1/lib/
Bundle-HoneyClient-Agent-1.0.1/lib/Bundle/
Bundle-HoneyClient-Agent-1.0.1/lib/Bundle/HoneyClient/
Bundle-HoneyClient-Agent-1.0.1/lib/Bundle/HoneyClient/Agent.pm
Bundle-HoneyClient-Agent-1.0.1/.cvsignore
Bundle-HoneyClient-Agent-1.0.1/MANIFEST
Bundle-HoneyClient-Agent-1.0.1/t/
Bundle-HoneyClient-Agent-1.0.1/t/pod.t
Bundle-HoneyClient-Agent-1.0.1/t/boilerplate.t
Bundle-HoneyClient-Agent-1.0.1/t/00-load.t
Bundle-HoneyClient-Agent-1.0.1/t/pod-coverage.t
Bundle-HoneyClient-Agent-1.0.1/Changes
Bundle-HoneyClient-Agent-1.0.1/Makefile.PL

Edit the package list

debian:/home/user/honeyclient/cpan/sources/authors/id/M/MI/MITREHC# nano Bundle-HoneyClient-Agent-1.0.1/lib/Bundle/HoneyClient/Agent.pm

We are using indentation to indicate prerequisites. So for instance, the following

 Sub::Uplevel
 Test::Simple -- aka Test::Builder, Test::Builder::Tester, Test::More
Test::Exception

indicates that we want to install Test::Exception, but it depends on Test::Simple, and Sub::Uplevel. By putting them in the order of dependencies first, we can minimize the amount that a user is prompted, and use unknown prompts to be an early warning system is something is wrong with perl dependencies. This format also makes it easy to see which perl libraries are called directly by HoneyClient code (anything without an indent) and which are simply dependencies of dependencies. It is important to keep track of which are the base libraries which are used since they would be the minimum set necessary if someone was to try to manually install the HoneyClient perl prereques from cpan by letting it follow dependencies.

How to find dependencies

Finding and adding dependencies to the local cpan repository is pretty easy. But make sure you perform these steps on some machine which you didn't already install the prereq on!

Open up CPAN and make sure you are using the local honeyclient cpan repository as is now required in the setup guide. Also make sure your prerequisites_policy is not set to follow

cpan> o conf cpan_home
    cpan_home          /home/user/honeyclient/cpan

cpan> o conf urllist
    urllist
        file:///home/user/honeyclient/cpan

cpan> o conf prerequisites_policy
    prerequisites_policy ask

Now do "o conf init" and leave everything as its previous setting, but add an online repository. Now do "o conf install <packagename>". If it prompts you if you want to install prerequisites, hit ctrl-c a couple times to stop it. We're essentially doing a depth first search, so now instead do "o conf install <packagename>" on one of the prereqs and see if it requires anything. Be sure to write down each level of prerequisites in a temp file, indented as stated above, and shown in the bundle files…remember that prerequisites must be listed above their dependant packages! Eventually you can either stop because you run out of prereqs or because you have found a prereq which you can see is already listed in a Bundle. It won't hurt anything to accidentally include packages in the list to be installed twice, but if you get unlucky, it will be a package which always prompts the user, so to minimize this hassel, you should try to make sure there is as little duplication as possible.

Example:

cpan> install Data::Compare
<cut>
  CPAN.pm: Going to build D/DC/DCANTRELL/Data-Compare-1.18.tar.gz

Checking if your kit is complete...
Looks good
Warning: prerequisite File::Find::Rule 0.1 not found.
Writing Makefile for Data::Compare
---- Unsatisfied dependencies detected during [D/DC/DCANTRELL/Data-Compare-1.18.tar.gz] -----
    File::Find::Rule
Shall I follow them and prepend them to the queue
of modules we are processing right now? [yes]

hit ctrl-c a couple times. List so far:

 File::Find::Rule
Data::Compare

...
of modules we are processing right now? [yes] Caught SIGINT
Got another SIGINT

cpan> install File::Find::Rule
<cut>
Warning: prerequisite Number::Compare 0 not found.
Warning: prerequisite Text::Glob 0 not found.
Writing Makefile for File::Find::Rule
---- Unsatisfied dependencies detected during [R/RC/RCLAMP/File-Find-Rule-0.30.tar.gz] -----
    Number::Compare
    Text::Glob
Shall I follow them and prepend them to the queue
of modules we are processing right now? [yes]

hit ctrl-c a couple times. List so far:

  Number::Compare
  Text::Glob
 File::Find::Rule
Data::Compare

of modules we are processing right now? [yes] Caught SIGINT
Got another SIGINT

cpan> install Number::Compare
<cut>
  /usr/bin/make install  -- OK

cpan> install Text::Glob
<cut>
  /usr/bin/make install  -- OK

Final list to be added to the Bundle (in this case Agent)

  Number::Compare
  Text::Glob
 File::Find::Rule
Data::Compare

Then, to check the various tar.gz files which should have been installed by CPAN into the appropriate directories, do

svn status | grep authors 
...
?      cpan/sources/authors/id/D/DC
...
?      cpan/sources/authors/id/R/RC/RCLAMP/File-Find-Rule-0.30.tar.gz
?      cpan/sources/authors/id/R/RC/RCLAMP/Number-Compare-0.01.tar.gz
svn add  cpan/sources/authors/id/D/DC cpan/sources/authors/id/R/RC/RCLAMP/Number-Compare-0.01.tar.gz  ...

How to update the CPAN CHECKSUMS file

Once you're done updating the Bundle, you should tar.gz it back up, and update the checksums.

First make sure you have CPAN::Checksums installed

create the following code (if it's not already in honeyclient/bin/UpdateBundleChecksum.pl)

#!/usr/bin/perl

use CPAN::Checksums qw(updatedir);
my $success = updatedir($ARGV[0]);

Then call it as

./UpdateBundleChecksum.pl /home/user/honeyclient/cpan/sources/authors/id/M/MI/MITREHC

Then check your changes back in to svn.

How to test that the bundle was correctly updated

First remove the previously cached bundle list from ~/honeyclient/cpan/Bundle/HoneyClient/*.pm, for either Util, Manager, or Agent.pm. Also remove ~/honeyclient/cpan/Metadata.

Then open cpan and re-issue your "install Bundle::HoneyClient::Manager" type command. If it is successful you will either see a message saying that the package is already installed and up to date (if you already installed it) or your newly added package will be the only one which is being installed by the process, since all the other packages should be up to date.

For instance, when I added Filesys::DfPortable and then tested the package, I saw

cpan> install Bundle::HoneyClient::Manager
CPAN: Storable loaded ok
Going to read /home/user/hc1.0.2/cpan/Metadata
  Database was generated on Thu, 31 Jan 2008 10:30:47 GMT
CPAN: Digest::MD5 loaded ok
CPAN: Compress::Zlib loaded ok
Checksum for /home/user/honeyclient/cpan/sources/authors/id/M/MI/MITREHC/Bundle-HoneyClient-Manager-1.0.1.tar.gz ok
Scanning cache /home/user/honeyclient/cpan/build for sizes
Deleting from cache: /home/user/honeyclient/cpan/build/Test-Simple-0.74 (10.7>10.0 MB)
Deleting from cache: /home/user/honeyclient/cpan/build/Sub-Uplevel-0.18 (10.1>10.0 MB)
Bundle-HoneyClient-Manager-1.0.1/
Bundle-HoneyClient-Manager-1.0.1/README
Bundle-HoneyClient-Manager-1.0.1/lib/
Bundle-HoneyClient-Manager-1.0.1/lib/Bundle/
Bundle-HoneyClient-Manager-1.0.1/lib/Bundle/HoneyClient/
Bundle-HoneyClient-Manager-1.0.1/lib/Bundle/HoneyClient/Manager.pm
Bundle-HoneyClient-Manager-1.0.1/.cvsignore
Bundle-HoneyClient-Manager-1.0.1/MANIFEST
Bundle-HoneyClient-Manager-1.0.1/t/
Bundle-HoneyClient-Manager-1.0.1/t/pod.t
Bundle-HoneyClient-Manager-1.0.1/t/boilerplate.t
Bundle-HoneyClient-Manager-1.0.1/t/00-load.t
Bundle-HoneyClient-Manager-1.0.1/t/pod-coverage.t
Bundle-HoneyClient-Manager-1.0.1/Changes
Bundle-HoneyClient-Manager-1.0.1/Makefile.PL
ExtUtils::CBuilder is up to date.
...
YAML::XS is up to date.
Filesys::DfPortable is up to date.

because I had already installed it manually while testing.