g-cpan Guide

1. Intro

g-cpan is a tool that generates and installs perl modules and bundles from CPAN "on-the-fly." It was originally proposed on the gentoo-user mailing list and filed as bug 3450.

2. Usage

See the table below for possible options to pass to g-cpan.

Code Listing 2.1: g-cpan Arguments

g-cpan needs at least one parameter from the list below. 
# g-cpan <OPTIONS> (PORTAGE OPTIONS)

Option	Description
-g,--generate	Generate ebuilds and drop them in the overlay, but never call portage. Useful for generating a tree of ebuilds without having permissions to portage. Write permission to the defined DISTFILES directory will still be needed.
-i,--install	Install the (list of) modules provided
-l,--list	List ebuilds that have been generated by g-cpan and reside in your overlay.
-L,--log	Log all output to /var/log/g-cpan/g-cpan.log and g-cpan.err
-s,--search	Search CPAN for the provided module.
--cpan_reload	Reload CPAN's index online
-u,--upgrade	Attempt to upgrade any ebuilds generated by g-cpan to newer versions. This option will create new ebuilds for those that exist in your overlay already. If a module name is given, it will attempt to only upgrade the requested module. If no arguments are given, all modules in your g-cpan overlay will be checked.
-v,--verbose	Enable verbose mode for more feedback on the step by step processes that g-cpan is running

Code Listing 2.2: g-cpan Portage Arguments

The following portage arguments can be passed to g-cpan. Please read
    the portage documentation for more information on how they work. The
    arguments are optional only.

Option	Description
-a,--ask	Pass the "ask" argument to portage. This will cause portage to prompt you to confirm your installation prior to issuing an emerge.
-b,--buildpkg	Tells emerge to build binary packages for all ebuilds processed in addition to actually merging the packages.
-B,--buildpkgonly	Creates binary packages for all ebuilds processed without actually merging the packages.
-p,--pretend	Create ebuilds as needed for the (list of) modules provided, but don't perform the actual emerge.

3. CPAN Configuration

When you run g-cpan, it will check for two configuration files. If you are root, it will check for the presense of an already configured CPAN under your perl install path. If CPAN is not configured, or you are not root, g-cpan will create a generic configuration for CPAN in ~/.cpan/CPAN/ called MyConfig.pm. You can modify this file as needed at any time.

Note: If you are upgrading to g-cpan-0.14 (or greater) from a previoous version, the MyConfig.pm that was generated in the old g-cpan's contained some mistakes. You may wish to save a backup of this file and let g-cpan regenerate it.

The CPAN configuration file is used for interacting with CPAN, determining what modules are available, what modules are needed, and performing all basic CPAN functions.

Versions of g-cpan prior to 0.14 performed all of the CPAN related work in ~/.cpan. As of 0.14, the downloading and exploration of the CPAN module for dependency information is stored in /var/tmp/g-cpan. This directory can be directly modified in the appropriate MyConfig.pm

4. g-cpan and Overlays

g-cpan is overlay "friendly." g-cpan will scan both the overlays provided in your make.conf as well as any you have set via environment variables, to help determine its course of action. If you have defined overlays, g-cpan will use the first overlay in your list that the user running it can write to. Any ebuilds generated by g-cpan will be stored in this overlay for future use (such as upgrading).

If no overlays are defined, or the user operating g-cpan cannot write to an overlay, then anything generated will be written to a temporary space and wiped on exit. Without an overlay to write to, certain functions will not be available, such as upgrading.

5. Caveats

g-cpan relies on your ACCEPT_KEYWORDS to generate ebuilds that your system will install. If you haven't set your ACCEPT_KEYWORDS in /etc/make.conf, it will default to the complete list of supported architectures when generating an ebuild. At this time, however, g-cpan cannot check the KEYWORDS for the ebuilds in portage that your requested module must depend on. It is therefore possible to generate ebuilds that you cannot emerge because the depending modules are not keyworded or unmasked for your architecture.
g-cpan has no way of handling truly interactive module installs. In the regular portage tree, that is something we work around with patches and sed statements. g-cpan does not have this luxury and may hang on an interactive module install.
g-cpan isn't going to know about any special environment variables or library paths that may be necessary to compile a particular module, for instance a module depending on database library paths. The best advise for this is to use the --generate option and modify the resulting ebuild yourself.

6. Bugs

Please post any bugs to http://bugs.gentoo.org or https://bugs.gentoo.org assigned to perl@gentoo.org.

7. Resources