README

   1 NAME
   2     CPANPLUS::Dist::Gentoo - CPANPLUS backend generating Gentoo ebuilds.
   3
   4 VERSION
   5     Version 0.12
   6
   7 SYNOPSIS
   8         # Using default values from your make.conf
   9         cpan2dist --format=CPANPLUS::Dist::Gentoo --buildprereq Some::Module
  10
  11         # Specifying your own options
  12         cpan2dist --format=CPANPLUS::Dist::Gentoo \
  13                   --dist-opts overlay=/usr/local/portage \
  14                   --dist-opts distdir=/usr/portage/distfiles \
  15                   --dist-opts manifest=yes \
  16                   --dist-opts keywords=x86 \
  17                   --dist-opts header="# Begin" \
  18                   --dist-opts footer="# End" \
  19                   Any::Module You::Like
  20
  21 DESCRIPTION
  22     This module is a CPANPLUS backend that recursively generates Gentoo
  23     ebuilds for a given package in the default overlay, updates the
  24     manifest, and even emerges it (together with its dependencies) if the
  25     user requires it.
  26
  27     The generated ebuilds are placed into the "perl-gcpanp" category. They
  28     favour depending on a "virtual", on "perl-core", "dev-perl" or
  29     "perl-gcpan" (in that order) rather than "perl-gcpanp". Existing ebuilds
  30     will be searched into the main "PORTDIR" portage tree and then into the
  31     overlays listed in "PORTDIR_OVERLAY".
  32
  33 OPTIONS
  34     You can pass specific options to cpan2dist by using the "--dist-opts"
  35     command-line argument followed by a "key=value" pair, where "key" is the
  36     option name and "value" is what it is set to. "--dist-opts" can be used
  37     several times.
  38
  39     The valid option "key"s are :
  40
  41     *   "manifest"
  42
  43         A boolean that indicates whether the Manifest file should be
  44         generated by running "ebuild manifest" onto the generated ebuilds.
  45
  46         Defaults to "yes".
  47
  48     *   "overlay"
  49
  50         The path of the overlay in which the generated ebuilds will be
  51         written.
  52
  53         Defaults to the first overlay listed in "PORTDIR_OVERLAY" (as
  54         returned by "emerge --info") or /usr/local/portage if this variable
  55         is empty.
  56
  57     *   "distdir"
  58
  59         The directory where "ebuild" expects to find the source tarballs.
  60         You need write permissions on this directory.
  61
  62         Defaults to the value of "DISTDIR" (as returned by "emerge --info")
  63         or /usr/portage/distfiles if this variable is empty.
  64
  65     *   "keywords"
  66
  67         The valid "KEYWORDS" for the generated ebuilds.
  68
  69         Defaults to the value of "ACCEPT_KEYWORDS" (as returned by "emerge
  70         --info") or 'x86' if this variable is empty.
  71
  72     *   "header"
  73
  74         A chunk of text that is prepended to every ebuild.
  75
  76         Defaults to the generic Gentoo Foundation header.
  77
  78     *   "footer"
  79
  80         A chunk of text that is appended to every ebuild.
  81
  82         Defaults to nothing.
  83
  84     cpan2dist itself takes other options, most notably :
  85
  86     *   "--buildprereq" generates an ebuild for every dependency, even for
  87         those that are already up-to-date. Setting this option is
  88         recommended.
  89
  90     *   "--force" forcefully regenerates ebuilds even if they already exist.
  91
  92     *   "--install" installs the ebuilds after generating them.
  93
  94     *   "--skiptest" skips tests while building, which speeds up the
  95         building process.
  96
  97     *   "--verbose" shows a lot more information.
  98
  99     Please refer to cpan2dist documentation for a complete coverage of its
 100     abilities.
 101
 102 INSTALLATION
 103     Before installing this module, you should append "perl-gcpanp" to your
 104     /etc/portage/categories file.
 105
 106     You have two ways for installing this module :
 107
 108     *   Use the perl overlay located at
 109         <http://git.overlays.gentoo.org/gitweb/?p=proj/perl-overlay.git>. It
 110         contains an ebuild for CPANPLUS::Dist::Gentoo which will most likely
 111         be up-to-date given the reactivity of Gentoo's Perl herd.
 112
 113     *   Bootstrap an ebuild for CPANPLUS::Dist::Gentoo using itself.
 114
 115         First, make sure your system "perl" is 5.10 or greater, so that the
 116         CPANPLUS toolchain is available.
 117
 118             $ perl -v
 119             This is perl 5, version 12, subversion 2 (v5.12.2)...
 120
 121         "perl" 5.12 is the current stable Perl version in Gentoo. If you
 122         still have "perl" "5.8.x", you can upgrade it by running the
 123         following commands as root :
 124
 125             # emerge -tv ">=dev-lang/perl-5.10"
 126             # perl-cleaner --all
 127
 128         Then, fetch the CPANPLUS::Dist::Gentoo tarball :
 129
 130             $ cd /tmp
 131             $ wget http://search.cpan.org/CPAN/authors/id/V/VP/VPIT/CPANPLUS-Dist-Gentoo-0.12.tar.gz
 132
 133         Log in as root and unpack it in e.g. your home directory :
 134
 135             # cd
 136             # tar xzf /tmp/CPANPLUS-Dist-Gentoo-0.12.tar.gz
 137             # cd CPANPLUS-Dist-Gentoo-0.12
 138
 139         Bootstrap CPANPLUS::Dist::Gentoo using the bundled shell script
 140         "g-cpanp" :
 141
 142             # perl Makefile.PL
 143             # make
 144             # PERL5LIB=blib/lib samples/g-cpanp CPANPLUS::Dist::Gentoo
 145
 146         Finally, emerge the "CPANPLUS-Dist-Gentoo" ebuild you've just
 147         generated :
 148
 149             # emerge -tv CPANPLUS-Dist-Gentoo
 150
 151 METHODS
 152     This module inherits all the methods from CPANPLUS::Dist::Base. Please
 153     refer to its documentation for precise information on what's done at
 154     each step.
 155
 156   "meta"
 157     Returns the contents of the META.yml or META.json files as parsed by
 158     Parse::CPAN::Meta.
 159
 160   "intuit_license"
 161     Returns an array reference to a list of Gentoo licences identifiers
 162     under which the current distribution is released.
 163
 164   "update_manifest"
 165     Updates the Manifest file for the ebuild associated to the current dist
 166     object.
 167
 168   "ebuild_source"
 169     Returns the source of the ebuild for the current dist object, or "undef"
 170     when one of the dependencies couldn't be mapped to an existing ebuild.
 171
 172 DEPENDENCIES
 173     Gentoo (<http://gentoo.org>).
 174
 175     CPANPLUS, IPC::Cmd (core modules since 5.9.5), Parse::CPAN::Meta (since
 176     5.10.1).
 177
 178     Cwd, Carp (since perl 5), File::Path (5.001), File::Copy (5.002),
 179     File::Spec (5.00405), List::Util (5.007003).
 180
 181 SEE ALSO
 182     cpan2dist.
 183
 184     CPANPLUS::Dist::Base, CPANPLUS::Dist::Deb, CPANPLUS::Dist::Mdv.
 185
 186 AUTHOR
 187     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 188
 189     You can contact me by mail or on "irc.perl.org" (vincent).
 190
 191 BUGS
 192     Please report any bugs or feature requests to "bug-cpanplus-dist-gentoo
 193     at rt.cpan.org", or through the web interface at
 194     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPANPLUS-Dist-Gentoo>. I
 195     will be notified, and then you'll automatically be notified of progress
 196     on your bug as I make changes.
 197
 198 SUPPORT
 199     You can find documentation for this module with the perldoc command.
 200
 201         perldoc CPANPLUS::Dist::Gentoo
 202
 203 ACKNOWLEDGEMENTS
 204     The module was inspired by CPANPLUS::Dist::Deb and CPANPLUS::Dist::Mdv.
 205
 206     Kent Fredric, for testing and suggesting improvements.
 207
 208 COPYRIGHT & LICENSE
 209     Copyright 2008,2009,2010,2011,2012 Vincent Pit, all rights reserved.
 210
 211     This program is free software; you can redistribute it and/or modify it
 212     under the same terms as Perl itself.
 213