Enforce the right version of the perl dependency whenever possible

[perl/modules/CPANPLUS-Dist-Gentoo.git] / README

diff --git a/README b/README
index 05c6e8d3b416ab41e16cff6bf054328b9f9c3892..d62db4dbd627737d222d5a644c2e3e024861cd37 100644 (file)
--- a/README
+++ b/README
@@ -2,37 +2,125 @@ NAME
     CPANPLUS::Dist::Gentoo - CPANPLUS backend generating Gentoo ebuilds.
 
 VERSION
     CPANPLUS::Dist::Gentoo - CPANPLUS backend generating Gentoo ebuilds.
 
 VERSION

-    Version 0.01
+    Version 0.09

 
 SYNOPSIS
         cpan2dist --format=CPANPLUS::Dist::Gentoo \
                   --dist-opts overlay=/usr/local/portage \
                   --dist-opts distdir=/usr/portage/distfiles \
                   --dist-opts manifest=yes \
 
 SYNOPSIS
         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 footer="# End" \

                   Any::Module You::Like
 
 DESCRPITON
     This module is a CPANPLUS backend that recursively generates Gentoo
     ebuilds for a given package in the specified overlay (defaults to
                   Any::Module You::Like
 
 DESCRPITON
     This module is a CPANPLUS backend that recursively generates Gentoo
     ebuilds for a given package in the specified overlay (defaults to

-    "/usr/local/portage"), update the manifest, and even emerge it (together
+    /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
     with its dependencies) if the user requires it. You need write
     permissions on the directory where Gentoo fetches its source files

-    (usually "/usr/portage/distfiles").
+    (usually /usr/portage/distfiles). The valid "KEYWORDS" for the generated
+    ebuilds are by default those given in "ACCEPT_KEYWORDS", but you can
+    specify your own with the "keywords" dist-option.

 
 

-    The generated ebuilds are placed into the section "perl-cpanp". They
-    favour depending on "perl-core" or "dev-perl" rather than "perl-cpanp".
+    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".
+
+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.
+
+    *   Bootstrap an ebuild for CPANPLUS::Dist::Gentoo using itself. Note
+        that if your Gentoo system "perl" is "5.8.x", CPANPLUS and its
+        dependencies are not installed and not even available in the main
+        portage tree. So you need to bootstrap them as well.
+
+        First, fetch tarballs for CPANPLUS and CPANPLUS::Dist::Gentoo :
+
+            $ cd /tmp
+            $ wget http://search.cpan.org/CPAN/authors/id/K/KA/KANE/CPANPLUS-0.88.tar.gz
+            $ wget http://search.cpan.org/CPAN/authors/id/V/VP/VPIT/CPANPLUS-Dist-Gentoo-0.09.tar.gz
+
+        Log in as root and unpack them in e.g. your home directory :
+
+            # cd
+            # tar xzf /tmp/CPANPLUS-0.88.tar.gz
+            # tar xzf /tmp/CPANPLUS-Dist-Gentoo-0.09.tar.gz
+
+        Set up environment variables so that the toolchain is temporarily
+        available :
+
+            # export OLDPATH=$PATH
+            # export PATH=/root/CPANPLUS-0.88/bin:$PATH
+            # export PERL5LIB=/root/CPANPLUS-Dist-Gentoo-0.09/blib/lib:/root/CPANPLUS-0.88/lib:/root/CPANPLUS-0.88/inc/bundle
+
+        Make sure you don't have an old ".cpanplus" configuration visible :
+
+            # [ -d /root/.cpanplus ] && mv /root/.cpanplus{,.bak}
+
+        Bootstrap CPANPLUS :
+
+            # cd /root/CPANPLUS-Dist-Gentoo-0.09
+            # samples/g-cpanp CPANPLUS
+
+        Reset the environment :
+
+            # export PATH=$OLDPATH
+            # unset PERL5LIB OLDPATH
+
+        Emerge CPANPLUS with the ebuilds you've just generated :
+
+            # emerge -tv CPANPLUS
+
+        As of september 2009, "podlators" and "ExtUtils-MakeMaker" may fail
+        to emerge due to collisions. You can work around this by disabling
+        the "protect-owned" "FEATURE" for them :
+
+            # FEATURES="-protect-owned" emerge podlators
+            # FEATURES="-protect-owned" emerge ExtUtils-MakeMaker
+
+        You may need to run each of these commands two times for them to
+        succeed.
+
+        At this point, you can bootstrap CPANPLUS::Dist::Gentoo using the
+        system CPANPLUS :
+
+            # PERL5LIB=/root/CPANPLUS-Dist-Gentoo-0.09/blib/lib samples/g-cpanp CPANPLUS::Dist::Gentoo
+            # emerge -tv CPANPLUS-Dist-Gentoo

 
 METHODS
 
 METHODS

-    All the methods are inherited from CPANPLUS::Dist::Base. Please refer to
-    its perldoc for precise information on what's done at each step.
+    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.
+
+  "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>).
 
 
 DEPENDENCIES
     Gentoo (<http://gentoo.org>).
 

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

 
 

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

 
 SEE ALSO
     cpan2dist.
 
 SEE ALSO
     cpan2dist.


@@ -42,6 +130,8 @@ SEE ALSO
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
 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
 BUGS
     Please report any bugs or feature requests to "bug-cpanplus-dist-gentoo
     at rt.cpan.org", or through the web interface at


@@ -55,11 +145,12 @@ SUPPORT
         perldoc CPANPLUS::Dist::Gentoo
 
 ACKNOWLEDGEMENTS
         perldoc CPANPLUS::Dist::Gentoo
 
 ACKNOWLEDGEMENTS

-    The module is to some extend cargo-culted from CPANPLUS::Dist::Deb and
-    CPANPLUS::Dist::Mdv.
+    The module was inspired by CPANPLUS::Dist::Deb and CPANPLUS::Dist::Mdv.
+
+    Kent Fredric, for testing and suggesting improvements.

 
 COPYRIGHT & LICENSE
 
 COPYRIGHT & LICENSE

-    Copyright 2008 Vincent Pit, all rights reserved.
+    Copyright 2008-2009 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.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.