NAME
    CPANPLUS::Dist::Gentoo - CPANPLUS backend generating Gentoo ebuilds.

VERSION
    Version 0.12

SYNOPSIS
        # Using default values from your make.conf
        cpan2dist --format=CPANPLUS::Dist::Gentoo --buildprereq Some::Module

        # Specifying your own options
        cpan2dist --format=CPANPLUS::Dist::Gentoo \
                  --dist-opts overlay=/usr/local/portage \
                  --dist-opts distdir=/usr/portage/distfiles \
                  --dist-opts manifest=yes \
                  --dist-opts keywords=x86 \
                  --dist-opts header="# Begin" \
                  --dist-opts footer="# End" \
                  Any::Module You::Like

DESCRIPTION
    This module is a CPANPLUS backend that recursively generates Gentoo
    ebuilds for a given package in the default overlay, updates the
    manifest, and even emerges it (together with its dependencies) if the
    user requires it.

    The generated ebuilds are placed into the "perl-gcpanp" category. They
    favour depending on a "virtual", on "perl-core", "dev-perl" or
    "perl-gcpan" (in that order) rather than "perl-gcpanp". Existing ebuilds
    will be searched into the main "PORTDIR" portage tree and then into the
    overlays listed in "PORTDIR_OVERLAY".

OPTIONS
    You can pass specific options to cpan2dist by using the "--dist-opts"
    command-line argument followed by a "key=value" pair, where "key" is the
    option name and "value" is what it is set to. "--dist-opts" can be used
    several times.

    The valid option "key"s are :

    *   "manifest"

        A boolean that indicates whether the Manifest file should be
        generated by running "ebuild manifest" onto the generated ebuilds.

        Defaults to "yes".

    *   "overlay"

        The path of the overlay in which the generated ebuilds will be
        written.

        Defaults to the first overlay listed in "PORTDIR_OVERLAY" (as
        returned by "emerge --info") or /usr/local/portage if this variable
        is empty.

    *   "distdir"

        The directory where "ebuild" expects to find the source tarballs.
        You need write permissions on this directory.

        Defaults to the value of "DISTDIR" (as returned by "emerge --info")
        or /usr/portage/distfiles if this variable is empty.

    *   "keywords"

        The valid "KEYWORDS" for the generated ebuilds.

        Defaults to the value of "ACCEPT_KEYWORDS" (as returned by "emerge
        --info") or 'x86' if this variable is empty.

    *   "header"

        A chunk of text that is prepended to every ebuild.

        Defaults to the generic Gentoo Foundation header.

    *   "footer"

        A chunk of text that is appended to every ebuild.

        Defaults to nothing.

    cpan2dist itself takes other options, most notably :

    *   "--buildprereq" generates an ebuild for every dependency, even for
        those that are already up-to-date. Setting this option is
        recommended.

    *   "--force" forcefully regenerates ebuilds even if they already exist.

    *   "--install" installs the ebuilds after generating them.

    *   "--skiptest" skips tests while building, which speeds up the
        building process.

    *   "--verbose" shows a lot more information.

    Please refer to cpan2dist documentation for a complete coverage of its
    abilities.

INSTALLATION
    Before installing this module, you should append "perl-gcpanp" to your
    /etc/portage/categories file.

    You have two ways for installing this module :

    *   Use the perl overlay located at
        <http://git.overlays.gentoo.org/gitweb/?p=proj/perl-overlay.git>. It
        contains an ebuild for CPANPLUS::Dist::Gentoo which will most likely
        be up-to-date given the reactivity of Gentoo's Perl herd.

    *   Bootstrap an ebuild for CPANPLUS::Dist::Gentoo using itself.

        First, make sure your system "perl" is 5.10 or greater, so that the
        CPANPLUS toolchain is available.

            $ perl -v
            This is perl 5, version 12, subversion 2 (v5.12.2)...

        "perl" 5.12 is the current stable Perl version in Gentoo. If you
        still have "perl" "5.8.x", you can upgrade it by running the
        following commands as root :

            # emerge -tv ">=dev-lang/perl-5.10"
            # perl-cleaner --all

        Then, fetch the CPANPLUS::Dist::Gentoo tarball :

            $ cd /tmp
            $ wget http://search.cpan.org/CPAN/authors/id/V/VP/VPIT/CPANPLUS-Dist-Gentoo-0.12.tar.gz

        Log in as root and unpack it in e.g. your home directory :

            # cd
            # tar xzf /tmp/CPANPLUS-Dist-Gentoo-0.12.tar.gz
            # cd CPANPLUS-Dist-Gentoo-0.12

        Bootstrap CPANPLUS::Dist::Gentoo using the bundled shell script
        "g-cpanp" :

            # perl Makefile.PL
            # make
            # PERL5LIB=blib/lib samples/g-cpanp CPANPLUS::Dist::Gentoo

        Finally, emerge the "CPANPLUS-Dist-Gentoo" ebuild you've just
        generated :

            # emerge -tv CPANPLUS-Dist-Gentoo

METHODS
    This module inherits all the methods from CPANPLUS::Dist::Base. Please
    refer to its documentation for precise information on what's done at
    each step.

  "meta"
    Returns the contents of the META.yml or META.json files as parsed by
    Parse::CPAN::Meta.

  "intuit_license"
    Returns an array reference to a list of Gentoo licences identifiers
    under which the current distribution is released.

  "update_manifest"
    Updates the Manifest file for the ebuild associated to the current dist
    object.

  "ebuild_source"
    Returns the source of the ebuild for the current dist object, or "undef"
    when one of the dependencies couldn't be mapped to an existing ebuild.

DEPENDENCIES
    Gentoo (<http://gentoo.org>).

    CPANPLUS, IPC::Cmd (core modules since 5.9.5), Parse::CPAN::Meta (since
    5.10.1).

    Cwd, Carp (since perl 5), File::Path (5.001), File::Copy (5.002),
    File::Spec (5.00405), List::Util (5.007003).

SEE ALSO
    cpan2dist.

    CPANPLUS::Dist::Base, CPANPLUS::Dist::Deb, CPANPLUS::Dist::Mdv.

AUTHOR
    Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.

    You can contact me by mail or on "irc.perl.org" (vincent).

BUGS
    Please report any bugs or feature requests to "bug-cpanplus-dist-gentoo
    at rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPANPLUS-Dist-Gentoo>. I
    will be notified, and then you'll automatically be notified of progress
    on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc CPANPLUS::Dist::Gentoo

ACKNOWLEDGEMENTS
    The module was inspired by CPANPLUS::Dist::Deb and CPANPLUS::Dist::Mdv.

    Kent Fredric, for testing and suggesting improvements.

COPYRIGHT & LICENSE
    Copyright 2008,2009,2010,2011,2012 Vincent Pit, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

