Document options

[perl/modules/CPANPLUS-Dist-Gentoo.git] / lib / CPANPLUS / Dist / Gentoo.pm

diff --git a/lib/CPANPLUS/Dist/Gentoo.pm b/lib/CPANPLUS/Dist/Gentoo.pm
index 474dce6efcdc4ab6f054880ffcdcf31c8f702823..3d2e243b2a20de8a9e163ffce29dbd668774a6af 100644 (file)
--- a/lib/CPANPLUS/Dist/Gentoo.pm
+++ b/lib/CPANPLUS/Dist/Gentoo.pm
@@ -34,24 +34,110 @@ our $VERSION = '0.10';
 
 =head1 SYNOPSIS
 
+    # Using default values from your F<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="# Copyright 1999-2008 Gentoo Foundation" \
+              --dist-opts header="# Begin" \
               --dist-opts footer="# End" \
               Any::Module You::Like
 
 =head1 DESCRPITON
 
 This module is a CPANPLUS backend that recursively generates Gentoo ebuilds for a given package in the specified overlay (defaults to F</usr/local/portage>), updates the manifest, and even emerges it (together with its dependencies) if the user requires it.
-You need write permissions on the directory where Gentoo fetches its source files (usually F</usr/portage/distfiles>).
-The valid C<KEYWORDS> for the generated ebuilds are by default those given in C<ACCEPT_KEYWORDS>, but you can specify your own with the C<keywords> dist-option.
 
 The generated ebuilds are placed into the C<perl-gcpanp> category.
 They favour depending on a C<virtual>, on C<perl-core>, C<dev-perl> or C<perl-gcpan> (in that order) rather than C<perl-gcpanp>.
 
+=head1 OPTIONS
+
+You can pass specific options to L<cpan2dist> by using the C<--dist-opts> command-line argument followed by a C<key=value> pair, where C<key> is the option name and C<value> is what it is set to.
+C<--dist-opts> can be used several times.
+
+The valid option C<key>s are :
+
+=over 4
+
+=item *
+
+C<manifest>
+
+A boolean that indicates whether the F<Manifest> file should be generated by running C<ebuild manifest> onto the generated ebuilds.
+
+Defaults to C<yes>.
+
+=item *
+
+C<overlay>
+
+A string formatted as a space-delimited sequence of paths, that lists the different overlays in which existent ebuilds will be looked for.
+
+Defaults to the value of C<PORTDIR_OVERLAY> as returned by C<emerge --info> (usually F</usr/local/portage>).
+
+=item *
+
+C<distdir>
+
+The directory where C<ebuild> expects to find the source tarballs.
+You need write permissions on this directory.
+
+Defaults to the value of C<DISTDIR> as returned by C<emerge --info> (usually F</usr/portage/distfiles>).
+
+=item *
+
+C<keywords>
+
+The valid C<KEYWORDS> for the generated ebuilds.
+
+Defaults to the value of C<ACCEPT_KEYWORDS> as returned by C<emerge --info>.
+
+=item *
+
+C<header>
+
+A chunk of text that is prepended to every ebuild.
+
+Defaults to the generic Gentoo Foundation header.
+
+=item *
+
+C<footer>
+
+A chunk of text that is appended to every ebuild.
+
+Defaults to nothing.
+
+=back
+
+L<cpan2dist> itself takes other options, most notably :
+
+=over 4
+
+=item *
+
+C<--buildprereq> generates an ebuild for every dependency, even for those that are already up-to-date.
+
+=item *
+
+C<--force> forcefully regenerates ebuilds even if they already exist.
+
+=item *
+
+C<--skiptest> skips tests while building, which speeds up the building process.
+
+=item *
+
+C<--verbose> shows a lot more information.
+
+=back
+
+Please refer to L<cpan2dist> documentation for a complete coverage of its abilities.
+
 =head1 INSTALLATION
 
 Before installing this module, you should append C<perl-gcpanp> to your F</etc/portage/categories> file.
@@ -72,8 +158,7 @@ Bootstrap an ebuild for L<CPANPLUS::Dist::Gentoo> using itself.
 First, make sure your system C<perl> is C<5.10> or greater, so that the L<CPANPLUS> toolchain is available.
 
     $ perl -v
-    This is perl 5, version 12, subversion 2 (v5.12.2) built for x86_64-linux
-    ...
+    This is perl 5, version 12, subversion 2 (v5.12.2)...
 
 C<perl> C<5.12> is the current stable Perl version in Gentoo.
 If you still have C<perl> C<5.8.x>, you can upgrade it by running the following commands as root :
@@ -94,6 +179,8 @@ Log in as root and unpack it in e.g. your home directory :
 
 Bootstrap L<CPANPLUS::Dist::Gentoo> using the bundled shell script C<g-cpanp> :
 
+    # perl Makefile.PL
+    # make
     # PERL5LIB=blib/lib samples/g-cpanp CPANPLUS::Dist::Gentoo
 
 Finally, emerge the C<CPANPLUS-Dist-Gentoo> ebuild you've just generated :
@@ -160,6 +247,7 @@ sub format_available {
    }
   } else {
    __PACKAGE__->_abort($errmsg);
+   return $format_available = 0;
   }
  }