App-cpanminus
view release on metacpan or search on metacpan
lib/App/cpanminus/fatscript.pm view on Meta::CPAN
=head1 DESCRIPTION
cpanminus is a script to get, unpack, build and install modules from
CPAN and does nothing else.
It's dependency free (can bootstrap itself), requires zero
configuration, and stands alone. When running, it requires only 10MB
of RAM.
=head1 INSTALLATION
There are several ways to install cpanminus to your system.
=head2 Package management system
There are Debian packages, RPMs, FreeBSD ports, and packages for other
operation systems available. If you want to use the package management system,
search for cpanminus and use the appropriate command to install. This makes it
easy to install C<cpanm> to your system without thinking about where to
install, and later upgrade.
=head2 Installing to system perl
You can also use the latest cpanminus to install cpanminus itself:
curl -L https://cpanmin.us | perl - --sudo App::cpanminus
This will install C<cpanm> to your bin directory like
C</usr/local/bin> and you'll need the C<--sudo> option to write to
the directory, unless you configured C<INSTALL_BASE> with L<local::lib>.
=head2 Installing to local perl (perlbrew, plenv etc.)
If you have perl in your home directory, which is the case if you use
tools like L<perlbrew> or plenv, you don't need the C<--sudo> option, since
you're most likely to have a write permission to the perl's library
path. You can just do:
curl -L https://cpanmin.us | perl - App::cpanminus
to install the C<cpanm> executable to the perl's bin path, like
C<~/perl5/perlbrew/bin/cpanm>.
=head2 Downloading the standalone executable
You can also copy the standalone executable to whatever location you'd like.
cd ~/bin
curl -L https://cpanmin.us/ -o cpanm
chmod +x cpanm
This just works, but be sure to grab the new version manually when you
upgrade because C<--self-upgrade> might not work with this installation setup.
=head2 Troubleshoot: HTTPS warnings
When you run C<curl> commands above, you may encounter SSL handshake
errors or certification warnings. This is due to your HTTP client
(curl) being old, or SSL certificates installed on your system needs
to be updated.
You're recommended to update the software or system if you can. If
that is impossible or difficult, use the C<-k> option with curl.
=head1 DEPENDENCIES
perl 5.8.1 or later.
=over 4
=item *
'tar' executable (bsdtar or GNU tar version 1.22 are recommended) or Archive::Tar to unpack files.
=item *
C compiler, if you want to build XS modules.
=item *
make
=item *
Module::Build (core in 5.10)
=back
=head1 QUESTIONS
=head2 How does cpanm get/parse/update the CPAN index?
It queries the CPAN Meta DB site at L<http://cpanmetadb.plackperl.org/>.
The site is updated at least every hour to reflect the latest changes
from fast syncing mirrors. The script then also falls back to query the
module at L<http://metacpan.org/> using its search API.
Upon calling these API hosts, cpanm (1.6004 or later) will send the
local perl versions to the server in User-Agent string by default. You
can turn it off with C<--no-report-perl-version> option. Read more
about the option with L<cpanm>, and read more about the privacy policy
about this data collection at L<http://cpanmetadb.plackperl.org/#privacy>
Fetched files are unpacked in C<~/.cpanm> and automatically cleaned up
periodically. You can configure the location of this with the
C<PERL_CPANM_HOME> environment variable.
=head2 Where does this install modules to? Do I need root access?
It installs to wherever ExtUtils::MakeMaker and Module::Build are
configured to (via C<PERL_MM_OPT> and C<PERL_MB_OPT>).
By default, it installs to the site_perl directory that belongs to
your perl. You can see the locations for that by running C<perl -V>
and it will be likely something under C</opt/local/perl/...> if you're
using system perl, or under your home directory if you have built perl
yourself using perlbrew or plenv.
If you've already configured local::lib on your shell, cpanm respects
that settings and modules will be installed to your local perl5
directory.
At a boot time, cpanminus checks whether you have already configured
local::lib, or have a permission to install modules to the site_perl
directory. If neither, i.e. you're using system perl and do not run
cpanm as a root, it automatically sets up local::lib compatible
installation path in a C<perl5> directory under your home
directory.
To avoid this, run C<cpanm> either as a root user, with C<--sudo>
option, or with C<--local-lib> option.
=head2 cpanminus can't install the module XYZ. Is it a bug?
It is more likely a problem with the distribution itself. cpanminus
doesn't support or may have issues with distributions such as follows:
=over 4
=item *
Tests that require input from STDIN.
=item *
Build.PL or Makefile.PL that prompts for input even when
C<PERL_MM_USE_DEFAULT> is enabled.
=item *
Modules that have invalid numeric values as VERSION (such as C<1.1a>)
=back
lib/App/cpanminus/fatscript.pm view on Meta::CPAN
my %imports;
my($remove, $spec, @names, @allexports);
# negated first item implies starting with default set:
unshift @imports, ':DEFAULT' if $imports[0] =~ m/^!/;
foreach $spec (@imports){
$remove = $spec =~ s/^!//;
if ($spec =~ s/^://){
if ($spec eq 'DEFAULT'){
@names = @$exports;
}
elsif ($tagdata = $tagsref->{$spec}) {
@names = @$tagdata;
}
else {
warn qq["$spec" is not defined in %${pkg}::EXPORT_TAGS];
++$oops;
next;
}
}
elsif ($spec =~ m:^/(.*)/$:){
my $patn = $1;
@allexports = keys %$export_cache unless @allexports; # only do keys once
@names = grep(/$patn/, @allexports); # not anchored by default
}
else {
@names = ($spec); # is a normal symbol name
}
warn "Import ".($remove ? "del":"add").": @names "
if $Exporter::Verbose;
if ($remove) {
foreach $sym (@names) { delete $imports{$sym} }
}
else {
@imports{@names} = (1) x @names;
}
}
@imports = keys %imports;
}
my @carp;
foreach $sym (@imports) {
if (!$export_cache->{$sym}) {
if ($sym =~ m/^\d/) {
$pkg->VERSION($sym); # inherit from UNIVERSAL
# If the version number was the only thing specified
# then we should act as if nothing was specified:
if (@imports == 1) {
@imports = @$exports;
last;
}
# We need a way to emulate 'use Foo ()' but still
# allow an easy version check: "use Foo 1.23, ''";
if (@imports == 2 and !$imports[1]) {
@imports = ();
last;
}
} elsif ($sym !~ s/^&// || !$export_cache->{$sym}) {
# Last chance - see if they've updated EXPORT_OK since we
# cached it.
unless ($cache_is_current) {
%$export_cache = ();
_rebuild_cache ($pkg, $exports, $export_cache);
$cache_is_current = 1;
}
if (!$export_cache->{$sym}) {
# accumulate the non-exports
push @carp,
qq["$sym" is not exported by the $pkg module\n];
$oops++;
}
}
}
}
if ($oops) {
require Carp;
Carp::croak("@{carp}Can't continue after import errors");
}
}
else {
@imports = @$exports;
}
my($fail, $fail_cache) = (\@{"${pkg}::EXPORT_FAIL"},
$Exporter::FailCache{$pkg} ||= {});
if (@$fail) {
if (!%$fail_cache) {
# Build cache of symbols. Optimise the lookup by adding
# barewords twice... both with and without a leading &.
# (Technique could be applied to $export_cache at cost of memory)
my @expanded = map { /^\w/ ? ($_, '&'.$_) : $_ } @$fail;
warn "${pkg}::EXPORT_FAIL cached: @expanded" if $Exporter::Verbose;
@{$fail_cache}{@expanded} = (1) x @expanded;
}
my @failed;
foreach $sym (@imports) { push(@failed, $sym) if $fail_cache->{$sym} }
if (@failed) {
@failed = $pkg->export_fail(@failed);
foreach $sym (@failed) {
require Carp;
Carp::carp(qq["$sym" is not implemented by the $pkg module ],
"on this architecture");
}
if (@failed) {
require Carp;
Carp::croak("Can't continue after import errors");
}
}
}
warn "Importing into $callpkg from $pkg: ",
join(", ",sort @imports) if $Exporter::Verbose;
foreach $sym (@imports) {
# shortcut for the common case of no type character
(*{"${callpkg}::$sym"} = \&{"${pkg}::$sym"}, next)
lib/App/cpanminus/fatscript.pm view on Meta::CPAN
#pod
#pod $response = $http->post_form($url, $form_data);
#pod $response = $http->post_form($url, $form_data, \%options);
#pod
#pod This method executes a C<POST> request and sends the key/value pairs from a
#pod form data hash or array reference to the given URL with a C<content-type> of
#pod C<application/x-www-form-urlencoded>. If data is provided as an array
#pod reference, the order is preserved; if provided as a hash reference, the terms
#pod are sorted on key and value for consistency. See documentation for the
#pod C<www_form_urlencode> method for details on the encoding.
#pod
#pod The URL must have unsafe characters escaped and international domain names
#pod encoded. See C<request()> for valid options and a description of the response.
#pod Any C<content-type> header or content in the options hashref will be ignored.
#pod
#pod The C<success> field of the response will be true if the status code is 2XX.
#pod
#pod =cut
sub post_form {
my ($self, $url, $data, $args) = @_;
(@_ == 3 || @_ == 4 && ref $args eq 'HASH')
or Carp::croak(q/Usage: $http->post_form(URL, DATAREF, [HASHREF])/ . "\n");
my $headers = {};
while ( my ($key, $value) = each %{$args->{headers} || {}} ) {
$headers->{lc $key} = $value;
}
delete $args->{headers};
return $self->request('POST', $url, {
%$args,
content => $self->www_form_urlencode($data),
headers => {
%$headers,
'content-type' => 'application/x-www-form-urlencoded'
},
}
);
}
#pod =method mirror
#pod
#pod $response = $http->mirror($url, $file, \%options)
#pod if ( $response->{success} ) {
#pod print "$file is up to date\n";
#pod }
#pod
#pod Executes a C<GET> request for the URL and saves the response body to the file
#pod name provided. The URL must have unsafe characters escaped and international
#pod domain names encoded. If the file already exists, the request will include an
#pod C<If-Modified-Since> header with the modification timestamp of the file. You
#pod may specify a different C<If-Modified-Since> header yourself in the C<<
#pod $options->{headers} >> hash.
#pod
#pod The C<success> field of the response will be true if the status code is 2XX
#pod or if the status code is 304 (unmodified).
#pod
#pod If the file was modified and the server response includes a properly
#pod formatted C<Last-Modified> header, the file modification time will
#pod be updated accordingly.
#pod
#pod =cut
sub mirror {
my ($self, $url, $file, $args) = @_;
@_ == 3 || (@_ == 4 && ref $args eq 'HASH')
or Carp::croak(q/Usage: $http->mirror(URL, FILE, [HASHREF])/ . "\n");
if ( -e $file and my $mtime = (stat($file))[9] ) {
$args->{headers}{'if-modified-since'} ||= $self->_http_date($mtime);
}
my $tempfile = $file . int(rand(2**31));
require Fcntl;
sysopen my $fh, $tempfile, Fcntl::O_CREAT()|Fcntl::O_EXCL()|Fcntl::O_WRONLY()
or Carp::croak(qq/Error: Could not create temporary file $tempfile for downloading: $!\n/);
binmode $fh;
$args->{data_callback} = sub { print {$fh} $_[0] };
my $response = $self->request('GET', $url, $args);
close $fh
or Carp::croak(qq/Error: Caught error closing temporary file $tempfile: $!\n/);
if ( $response->{success} ) {
rename $tempfile, $file
or Carp::croak(qq/Error replacing $file with $tempfile: $!\n/);
my $lm = $response->{headers}{'last-modified'};
if ( $lm and my $mtime = $self->_parse_http_date($lm) ) {
utime $mtime, $mtime, $file;
}
}
$response->{success} ||= $response->{status} eq '304';
unlink $tempfile;
return $response;
}
#pod =method request
#pod
#pod $response = $http->request($method, $url);
#pod $response = $http->request($method, $url, \%options);
#pod
#pod Executes an HTTP request of the given method type ('GET', 'HEAD', 'POST',
#pod 'PUT', etc.) on the given URL. The URL must have unsafe characters escaped and
#pod international domain names encoded.
#pod
#pod If the URL includes a "user:password" stanza, they will be used for Basic-style
#pod authorization headers. (Authorization headers will not be included in a
#pod redirected request.) For example:
#pod
#pod $http->request('GET', 'http://Aladdin:open sesame@example.com/');
#pod
#pod If the "user:password" stanza contains reserved characters, they must
#pod be percent-escaped:
#pod
#pod $http->request('GET', 'http://john%40example.com:password@example.com/');
#pod
#pod A hashref of options may be appended to modify the request.
#pod
#pod Valid options are:
#pod
#pod =for :list
#pod * C<headers> —
lib/App/cpanminus/fatscript.pm view on Meta::CPAN
pseudo-HTTP status code of 599 and a reason of "Internal Exception". The
content field in the response will contain the text of the exception.
The C<keep_alive> parameter enables a persistent connection, but only to a
single destination scheme, host and port. Also, if any connection-relevant
attributes are modified, or if the process ID or thread ID change, the
persistent connection will be dropped. If you want persistent connections
across multiple destinations, use multiple HTTP::Tiny objects.
See L</SSL SUPPORT> for more on the C<verify_SSL> and C<SSL_options> attributes.
=head2 get|head|put|post|delete
$response = $http->get($url);
$response = $http->get($url, \%options);
$response = $http->head($url);
These methods are shorthand for calling C<request()> for the given method. The
URL must have unsafe characters escaped and international domain names encoded.
See C<request()> for valid options and a description of the response.
The C<success> field of the response will be true if the status code is 2XX.
=head2 post_form
$response = $http->post_form($url, $form_data);
$response = $http->post_form($url, $form_data, \%options);
This method executes a C<POST> request and sends the key/value pairs from a
form data hash or array reference to the given URL with a C<content-type> of
C<application/x-www-form-urlencoded>. If data is provided as an array
reference, the order is preserved; if provided as a hash reference, the terms
are sorted on key and value for consistency. See documentation for the
C<www_form_urlencode> method for details on the encoding.
The URL must have unsafe characters escaped and international domain names
encoded. See C<request()> for valid options and a description of the response.
Any C<content-type> header or content in the options hashref will be ignored.
The C<success> field of the response will be true if the status code is 2XX.
=head2 mirror
$response = $http->mirror($url, $file, \%options)
if ( $response->{success} ) {
print "$file is up to date\n";
}
Executes a C<GET> request for the URL and saves the response body to the file
name provided. The URL must have unsafe characters escaped and international
domain names encoded. If the file already exists, the request will include an
C<If-Modified-Since> header with the modification timestamp of the file. You
may specify a different C<If-Modified-Since> header yourself in the C<<
$options->{headers} >> hash.
The C<success> field of the response will be true if the status code is 2XX
or if the status code is 304 (unmodified).
If the file was modified and the server response includes a properly
formatted C<Last-Modified> header, the file modification time will
be updated accordingly.
=head2 request
$response = $http->request($method, $url);
$response = $http->request($method, $url, \%options);
Executes an HTTP request of the given method type ('GET', 'HEAD', 'POST',
'PUT', etc.) on the given URL. The URL must have unsafe characters escaped and
international domain names encoded.
If the URL includes a "user:password" stanza, they will be used for Basic-style
authorization headers. (Authorization headers will not be included in a
redirected request.) For example:
$http->request('GET', 'http://Aladdin:open sesame@example.com/');
If the "user:password" stanza contains reserved characters, they must
be percent-escaped:
$http->request('GET', 'http://john%40example.com:password@example.com/');
A hashref of options may be appended to modify the request.
Valid options are:
=over 4
=item *
C<headers> — A hashref containing headers to include with the request. If the value for a header is an array reference, the header will be output multiple times with each value in the array. These headers over-write any default headers.
=item *
C<content> — A scalar to include as the body of the request OR a code reference that will be called iteratively to produce the body of the request
=item *
C<trailer_callback> — A code reference that will be called if it exists to provide a hashref of trailing headers (only used with chunked transfer-encoding)
=item *
C<data_callback> — A code reference that will be called for each chunks of the response body received.
=back
The C<Host> header is generated from the URL in accordance with RFC 2616. It
is a fatal error to specify C<Host> in the C<headers> option. Other headers
may be ignored or overwritten if necessary for transport compliance.
If the C<content> option is a code reference, it will be called iteratively
to provide the content body of the request. It should return the empty
string or undef when the iterator is exhausted.
If the C<content> option is the empty string, no C<content-type> or
C<content-length> headers will be generated.
If the C<data_callback> option is provided, it will be called iteratively until
the entire response body is received. The first argument will be a string
containing a chunk of the response body, the second argument will be the
in-progress response hash reference, as described below. (This allows
lib/App/cpanminus/fatscript.pm view on Meta::CPAN
with local::lib, you can potentially delete a globally accessible version of a
module while installing the new version in a local place. Only combine "make
install UNINST=1" and local::lib if you understand these possible consequences.
=head1 LIMITATIONS
=over 4
=item * Directory names with spaces in them are not well supported by the perl
toolchain and the programs it uses. Pure-perl distributions should support
spaces, but problems are more likely with dists that require compilation. A
workaround you can do is moving your local::lib to a directory with spaces
B<after> you installed all modules inside your local::lib bootstrap. But be
aware that you can't update or install CPAN modules after the move.
=item * Rather basic shell detection. Right now anything with csh in its name is
assumed to be a C shell or something compatible, and everything else is assumed
to be Bourne, except on Win32 systems. If the C<SHELL> environment variable is
not set, a Bourne-compatible shell is assumed.
=item * Kills any existing PERL_MM_OPT or PERL_MB_OPT.
=item * Should probably auto-fixup CPAN config if not already done.
=item * On VMS and MacOS Classic (pre-OS X), local::lib loads L<File::Spec>.
This means any L<File::Spec> version installed in the local::lib will be
ignored by scripts using local::lib. A workaround for this is using
C<use lib "$local_lib/lib/perl5";> instead of using C<local::lib> directly.
=item * Conflicts with L<ExtUtils::MakeMaker>'s C<PREFIX> option.
C<local::lib> uses the C<INSTALL_BASE> option, as it has more predictable and
sane behavior. If something attempts to use the C<PREFIX> option when running
a F<Makefile.PL>, L<ExtUtils::MakeMaker> will refuse to run, as the two
options conflict. This can be worked around by temporarily unsetting the
C<PERL_MM_OPT> environment variable.
=item * Conflicts with L<Module::Build>'s C<--prefix> option. Similar to the
previous limitation, but any C<--prefix> option specified will be ignored.
This can be worked around by temporarily unsetting the C<PERL_MB_OPT>
environment variable.
=back
Patches very much welcome for any of the above.
=over 4
=item * On Win32 systems, does not have a way to write the created environment
variables to the registry, so that they can persist through a reboot.
=back
=head1 TROUBLESHOOTING
If you've configured local::lib to install CPAN modules somewhere in to your
home directory, and at some point later you try to install a module with C<cpan
-i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
/usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
you've somehow lost your updated ExtUtils::MakeMaker module.
To remedy this situation, rerun the bootstrapping procedure documented above.
Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
=head1 ENVIRONMENT
=over 4
=item SHELL
=item COMSPEC
local::lib looks at the user's C<SHELL> environment variable when printing out
commands to add to the shell configuration file.
On Win32 systems, C<COMSPEC> is also examined.
=back
=head1 SEE ALSO
=over 4
=item * L<Perl Advent article, 2011|http://perladvent.org/2011/2011-12-01.html>
=back
=head1 SUPPORT
IRC:
Join #local-lib on irc.perl.org.
=head1 AUTHOR
Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
auto_install fixes kindly sponsored by http://www.takkle.com/
=head1 CONTRIBUTORS
Patches to correctly output commands for csh style shells, as well as some
documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
Doc patches for a custom local::lib directory, more cleanups in the english
documentation and a L<german documentation|POD2::DE::local::lib> contributed by
Torsten Raudssus <torsten@raudssus.de>.
Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
things will install properly, submitted a fix for the bug causing problems with
writing Makefiles during bootstrapping, contributed an example program, and
submitted yet another fix to ensure that local::lib can install and bootstrap
properly. Many, many thanks!
pattern of Freenode IRC contributed the beginnings of the Troubleshooting
section. Many thanks!
( run in 0.673 second using v1.01-cache-2.11-cpan-0bb4e1dffa6 )