Commits

Fabrice Gabolde committed 47d50ee

Main documentation.

Comments (0)

Files changed (1)

+=encoding utf8
+
+=head1 NAME
+
+Alien::hg -- The Mercurial DVCS, packaged for the CPAN
+
+=head1 SYNOPSIS
+
+  use Alien::hg::ConfigData;
+  my $hg_binary = Alien::hg::ConfigData->config('which_hg');
+  system($hg_binary, 'commit');
+
+=head1 DESCRIPTION
+
+This distribution is a re-packaging of the Mercurial DVCS for the CPAN.
+
+After installing it, you should be able to get a valid path to an
+F<hg> binary, independently of how it got installed onto your system.
+
+=head2 OUR BUILD PROCESS
+
+There's basically three steps:
+
+=over 4
+
+=item 1. Guess whether F<hg> is already present.
+
+This step tries to find a binary called F<hg> in your PATH.  If it is
+present, it tries calling
+
+  hg version
+
+to determine if that's actually Mercurial or some other tool also
+called F<hg>.  If that works and a version number can be extracted
+from the output, the user is asked whether she would like to use that
+version or proceed with the installation of a brand-new Mercurial.
+
+If that binary is actually an L<Alien::hg> wrapper from a previous
+installation, answering "y" will lead to trouble.  The default is "n"
+("no, fetch and install a separate Mercurial").
+
+If no F<hg> binary has been found, the installation proceeds to the
+next step, no questions asked.
+
+=item 2. Fetch and install Mercurial.
+
+This only occurs if you answered "no" in the previous step, or if no
+F<hg> binary has been found.
+
+This step fetches the most recent stable release of Mercurial, for
+installation into a L<File::ShareDir>-compatible directory.  This step
+should B<never> overwrite a version of Mercurial that's been installed
+through regular means (manually from the tarball, or from your
+favorite package manager -- I mean your favorite package manager
+that's not a CPAN client).
+
+When this step is completed, the user is asked whether a wrapper
+around the new Mercurial install should be installed into her PATH.
+If that overwrites your previously installed Mercurial binary, you
+should probably answer "no" (but that should never happen for
+L<perlbrew|App::perlbrew> setups... you are using perlbrew, right?).
+The default is "n" (don't install the wrapper).
+
+=item 3. Install the wrapper.
+
+This only occurs if you answered "yes" in the previous step.  The
+wrapper is a tiny script that just C<exec>s the C<which_hg> key of
+L<Alien::hg::ConfigData>, which should be pointing at the new
+Mercurial if everything has gone OK.
+
+=back
+
+=head1 USAGE
+
+L<Alien::hg::ConfigData> is produced by L<Module::Build>, and the only
+value of interest in there should be:
+
+  my $hg = Alien::hg::ConfigData->config('which_hg');
+
+which is an absolute path to a working F<hg> binary (not the wrapper,
+the real Python one -- either the one you just installed, or the one
+you had installed before).
+
+=head1 METHODS
+
+There are none.  This is a documentation-only package.
+
+=head1 AUTHOR
+
+Fabrice Gabolde <fabrice.gabolde@uperto.com>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2013 by Fabrice Gabolde.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+Mercurial itself is copyrighted by Matt Mackall and others, and is
+licensed under the terms of the GPLv2+.