diff options
author | Karl Berry <karl@freefriends.org> | 2016-04-05 22:27:26 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2016-04-05 22:27:26 +0000 |
commit | b56b320b5e2515160073fa1b469514002688fe11 (patch) | |
tree | 965a7100c5e45fca8ec803d22b8b6ce14fca4633 /Master/tlpkg/tlperl/lib/CPAN | |
parent | d26c206452d2e285c3bbf949f34011e4a55fd8f9 (diff) |
tlperl 5.22.1 from siep
git-svn-id: svn://tug.org/texlive/trunk@40252 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/CPAN')
22 files changed, 4929 insertions, 968 deletions
diff --git a/Master/tlpkg/tlperl/lib/CPAN/Distribution.pm b/Master/tlpkg/tlperl/lib/CPAN/Distribution.pm index 9a0870717da..092b781ac2e 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Distribution.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Distribution.pm @@ -4,12 +4,37 @@ package CPAN::Distribution; use strict; use Cwd qw(chdir); use CPAN::Distroprefs; -use CPAN::Meta::Requirements 2; use CPAN::InfoObj; use File::Path (); @CPAN::Distribution::ISA = qw(CPAN::InfoObj); use vars qw($VERSION); -$VERSION = "2.02"; +$VERSION = "2.04"; + +# no prepare, because prepare is not a command on the shell command line +# TODO: clear instance cache on reload +my %instance; +for my $method (qw(get make test install)) { + no strict 'refs'; + for my $prefix (qw(pre post)) { + my $hookname = sprintf "%s_%s", $prefix, $method; + *$hookname = sub { + my($self) = @_; + for my $plugin (@{$CPAN::Config->{plugin_list}}) { + my($plugin_proper,$args) = split /=/, $plugin, 2; + $args = "" unless defined $args; + if ($CPAN::META->has_inst($plugin_proper)){ + my @args = split /,/, $args; + $instance{$plugin} ||= $plugin_proper->new(@args); + if ($instance{$plugin}->can($hookname)) { + $instance{$plugin}->$hookname($self); + } + } else { + $CPAN::Frontend->mydie("Plugin '$plugin_proper' not found"); + } + } + }; + } +} # Accessors sub cpan_comment { @@ -180,6 +205,7 @@ sub color_cmd_tmps { return if exists $self->{incommandcolor} && $color==1 && $self->{incommandcolor}==$color; + $CPAN::MAX_RECURSION||=0; # silence 'once' warnings if ($depth>=$CPAN::MAX_RECURSION) { die(CPAN::Exception::RecursiveDependency->new($ancestors)); } @@ -187,11 +213,10 @@ sub color_cmd_tmps { my $prereq_pm = $self->prereq_pm; if (defined $prereq_pm) { # XXX also optional_req & optional_breq? -- xdg, 2012-04-01 + # A: no, optional deps may recurse -- ak, 2014-05-07 PREREQ: for my $pre ( keys %{$prereq_pm->{requires}||{}}, keys %{$prereq_pm->{build_requires}||{}}, - keys %{$prereq_pm->{opt_requires}||{}}, - keys %{$prereq_pm->{opt_build_requires}||{}} ) { next PREREQ if $pre eq "perl"; my $premo; @@ -332,6 +357,8 @@ sub shortcut_get { sub get { my($self) = @_; + $self->pre_get(); + $self->debug("checking goto id[$self->{ID}]") if $CPAN::DEBUG; if (my $goto = $self->prefs->{goto}) { return $self->goto($goto); @@ -379,6 +406,9 @@ sub get { } return unless $self->patch; $self->store_persistent_state; + + $self->post_get(); + return 1; # success } @@ -648,6 +678,11 @@ sub parse_meta_yml { } $self->debug(sprintf("yaml[%s]", $early_yaml || 'UNDEF')) if $CPAN::DEBUG; $self->debug($early_yaml) if $CPAN::DEBUG && $early_yaml; + if (!ref $early_yaml or ref $early_yaml ne "HASH"){ + # fix rt.cpan.org #95271 + $CPAN::Frontend->mywarn("The content of '$yaml' is not a HASH reference. Cannot use it.\n"); + return {}; + } return $early_yaml || undef; } @@ -804,8 +839,16 @@ sub store_persistent_state { "will not store persistent state\n"); return; } - unless ( Cwd::realpath(File::Spec->catdir($dir, File::Spec->updir()) ) - eq Cwd::realpath($CPAN::Config->{build_dir} ) ) { + # self-build-dir + my $sbd = Cwd::realpath( + File::Spec->catdir($dir, File::Spec->updir ()) + ); + # config-build-dir + my $cbd = Cwd::realpath( + # the catdir is a workaround for bug https://rt.cpan.org/Ticket/Display.html?id=101283 + File::Spec->catdir($CPAN::Config->{build_dir}, File::Spec->curdir()) + ); + unless ($sbd eq $cbd) { $CPAN::Frontend->mywarnonce("Directory '$dir' not below $CPAN::Config->{build_dir}, ". "will not store persistent state\n"); return; @@ -1835,8 +1878,8 @@ sub prepare { $self->debug("Changed directory to $builddir") if $CPAN::DEBUG; - local $ENV{PERL_AUTOINSTALL} = $ENV{PERL_AUTOINSTALL}; - local $ENV{PERL_EXTUTILS_AUTOINSTALL} = $ENV{PERL_EXTUTILS_AUTOINSTALL}; + local $ENV{PERL_AUTOINSTALL} = $ENV{PERL_AUTOINSTALL} || ''; + local $ENV{PERL_EXTUTILS_AUTOINSTALL} = $ENV{PERL_EXTUTILS_AUTOINSTALL} || ''; $self->choose_MM_or_MB or return; @@ -1856,8 +1899,8 @@ sub prepare { if ($self->prefs->{pl}) { $pl_commandline = $self->prefs->{pl}{commandline}; } - local $ENV{PERL} = $ENV{PERL}; - local $ENV{PERL5_CPAN_IS_EXECUTING} = $ENV{PERL5_CPAN_IS_EXECUTING}; + local $ENV{PERL} = defined $ENV{PERL}? $ENV{PERL} : $^X; + local $ENV{PERL5_CPAN_IS_EXECUTING} = $ENV{PERL5_CPAN_IS_EXECUTING} || ''; local $ENV{PERL_MM_USE_DEFAULT} = 1 if $CPAN::Config->{use_prompt_default}; local $ENV{NONINTERACTIVE_TESTING} = 1 if $CPAN::Config->{use_prompt_default}; if ($pl_commandline) { @@ -2036,6 +2079,8 @@ sub shortcut_make { sub make { my($self) = @_; + $self->pre_make(); + $self->debug("checking goto id[$self->{ID}]") if $CPAN::DEBUG; if (my $goto = $self->prefs->{goto}) { return $self->goto($goto); @@ -2119,10 +2164,10 @@ is part of the perl-%s distribution. To install that, you need to run my %env; while (my($k,$v) = each %ENV) { - next unless defined $v; - $env{$k} = $v; + next if defined $v; + $env{$k} = ''; } - local %ENV = %env; + local @ENV{keys %env} = values %env; my $satisfied = eval { $self->satisfy_requires }; return $self->goodbye($@) if $@; return unless $satisfied ; @@ -2130,12 +2175,19 @@ is part of the perl-%s distribution. To install that, you need to run delete $self->{force_update}; return; } + + # need to chdir again, because $self->satisfy_requires might change the directory + unless (chdir $builddir) { + $CPAN::Frontend->mywarn("Couldn't chdir to '$builddir': $!"); + return; + } + my $system; my $make_commandline; if ($self->prefs->{make}) { $make_commandline = $self->prefs->{make}{commandline}; } - local $ENV{PERL} = $ENV{PERL}; + local $ENV{PERL} = defined $ENV{PERL}? $ENV{PERL} : $^X; local $ENV{PERL_MM_USE_DEFAULT} = 1 if $CPAN::Config->{use_prompt_default}; local $ENV{NONINTERACTIVE_TESTING} = 1 if $CPAN::Config->{use_prompt_default}; if ($make_commandline) { @@ -2200,6 +2252,9 @@ is part of the perl-%s distribution. To install that, you need to run $CPAN::Frontend->mywarn(" $system -- NOT OK\n"); } $self->store_persistent_state; + + $self->post_make(); + return !! $system_ok; } @@ -2733,6 +2788,8 @@ sub _feature_depends { sub prereqs_for_slot { my($self,$slot) = @_; my($prereq_pm); + $CPAN::META->has_usable("CPAN::Meta::Requirements") + or die "CPAN::Meta::Requirements not available"; my $merged = CPAN::Meta::Requirements->new; my $prefs_depends = $self->prefs->{depends}||{}; my $feature_depends = $self->_feature_depends(); @@ -2795,6 +2852,8 @@ sub unsat_prereq { my($self,$slot) = @_; my($merged_hash,$prereq_pm) = $self->prereqs_for_slot($slot); my(@need); + $CPAN::META->has_usable("CPAN::Meta::Requirements") + or die "CPAN::Meta::Requirements not available"; my $merged = CPAN::Meta::Requirements->from_string_hash($merged_hash); my @merged = $merged->required_modules; CPAN->debug("all merged_prereqs[@merged]") if $CPAN::DEBUG; @@ -3145,8 +3204,9 @@ sub prereq_pm { return; } # no Makefile/Build means configuration aborted, so don't look for prereqs - return unless -f File::Spec->catfile($self->{build_dir},'Makefile') - || -f File::Spec->catfile($self->{build_dir},'Build'); + my $makefile = File::Spec->catfile($self->{build_dir}, $^O eq 'VMS' ? 'descrip.mms' : 'Makefile'); + my $buildfile = File::Spec->catfile($self->{build_dir}, $^O eq 'VMS' ? 'Build.com' : 'Build'); + return unless -f $makefile || -f $buildfile; CPAN->debug(sprintf "writemakefile[%s]modulebuild[%s]", $self->{writemakefile}||"", $self->{modulebuild}||"", @@ -3166,6 +3226,7 @@ sub prereq_pm { # XXX assemble optional_req && optional_breq from recommends/suggests # depending on corresponding policies -- xdg, 2012-04-01 + CPAN->use_inst("CPAN::Meta::Requirements"); my $opt_runtime = CPAN::Meta::Requirements->new; my $opt_build = CPAN::Meta::Requirements->new; if ( $CPAN::Config->{recommends_policy} ) { @@ -3413,6 +3474,8 @@ sub _exe_files { sub test { my($self) = @_; + $self->pre_test(); + $self->debug("checking goto id[$self->{ID}]") if $CPAN::DEBUG; if (my $goto = $self->prefs->{goto}) { return $self->goto($goto); @@ -3591,6 +3654,8 @@ sub test { } $self->store_persistent_state; + $self->post_test(); + return $self->{force_update} ? 1 : !! $tests_ok; } @@ -3815,6 +3880,8 @@ sub shortcut_install { sub install { my($self) = @_; + $self->pre_install(); + $self->debug("checking goto id[$self->{ID}]") if $CPAN::DEBUG; if (my $goto = $self->prefs->{goto}) { return $self->goto($goto); @@ -3867,7 +3934,6 @@ sub install { $install_directive, $CPAN::Config->{mbuild_install_arg}, ); - } else { my($make_install_make_command) = $self->_make_install_make_command(); $system = sprintf("%s install %s", @@ -3911,8 +3977,7 @@ sub install { local $ENV{PERL_MM_USE_DEFAULT} = 1 if $CPAN::Config->{use_prompt_default}; local $ENV{NONINTERACTIVE_TESTING} = 1 if $CPAN::Config->{use_prompt_default}; - my($pipe) = FileHandle->new("$system $stderr |") || Carp::croak -("Can't execute $system: $!"); + my($pipe) = FileHandle->new("$system $stderr |") || Carp::croak("Can't execute $system: $!"); my($makeout) = ""; while (<$pipe>) { print $_; # intentionally NOT use Frontend->myprint because it @@ -3954,6 +4019,9 @@ sub install { } delete $self->{force_update}; $self->store_persistent_state; + + $self->post_install(); + return !! $close_ok; } diff --git a/Master/tlpkg/tlperl/lib/CPAN/FirstTime.pm b/Master/tlpkg/tlperl/lib/CPAN/FirstTime.pm index d1a8eef2607..918e009a2bc 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/FirstTime.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/FirstTime.pm @@ -10,7 +10,7 @@ use File::Path (); use File::Spec (); use CPAN::Mirrors (); use vars qw($VERSION $auto_config); -$VERSION = "5.5306"; +$VERSION = "5.5307"; =head1 NAME @@ -198,6 +198,7 @@ alternatives can be configured according to the following table: cwd Cwd::cwd getcwd Cwd::getcwd fastcwd Cwd::fastcwd + getdcwd Cwd::getdcwd backtickcwd external command cwd Preferred method for determining the current working directory? @@ -1134,6 +1135,17 @@ sub init { } # + #= how plugins work + # + + # XXX MISSING: my_array_prompt to be used with plugins. We did something like this near + # git log -p fd68f8f5e33f4cecea4fdb7abc5ee19c12f138f0..test-notest-test-dependency + # Need to do similar steps for plugin_list. As long as we do not support it here, people + # must use the cpan shell prompt to write something like + # o conf plugin_list push CPAN::Plugin::Specfile=dir,/tmp/foo-20141013,... + # o conf commit + + # #= how FTP works # @@ -1144,7 +1156,7 @@ sub init { # my_prompt_loop(getcwd => 'cwd', $matcher, - 'cwd|getcwd|fastcwd|backtickcwd'); + 'cwd|getcwd|fastcwd|getdcwd|backtickcwd'); # #= the CPAN shell itself (prompt, color) diff --git a/Master/tlpkg/tlperl/lib/CPAN/HTTP/Credentials.pm b/Master/tlpkg/tlperl/lib/CPAN/HTTP/Credentials.pm index 097c67d0ed7..96a98800928 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/HTTP/Credentials.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/HTTP/Credentials.pm @@ -4,11 +4,11 @@ package CPAN::HTTP::Credentials; use strict; use vars qw($USER $PASSWORD $PROXY_USER $PROXY_PASSWORD); -$CPAN::HTTP::Credentials::VERSION = $CPAN::HTTP::Credentials::VERSION = "1.9600"; +$CPAN::HTTP::Credentials::VERSION = $CPAN::HTTP::Credentials::VERSION = "1.9601"; sub clear_credentials { - _clear_non_proxy_credentials(); - _clear_proxy_credentials(); + clear_non_proxy_credentials(); + clear_proxy_credentials(); } sub clear_non_proxy_credentials { diff --git a/Master/tlpkg/tlperl/lib/CPAN/HandleConfig.pm b/Master/tlpkg/tlperl/lib/CPAN/HandleConfig.pm index a138128bdfe..e596cbcd6c5 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/HandleConfig.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/HandleConfig.pm @@ -12,7 +12,7 @@ CPAN::HandleConfig - internal configuration handling for CPAN.pm =cut -$VERSION = "5.5005"; # see also CPAN::Config::VERSION at end of file +$VERSION = "5.5006"; # see also CPAN::Config::VERSION at end of file %can = ( commit => "Commit changes to disk", @@ -88,6 +88,7 @@ $VERSION = "5.5005"; # see also CPAN::Config::VERSION at end of file "patch", "patches_dir", "perl5lib_verbosity", + "plugin_list", "prefer_external_tar", "prefer_installer", "prefs_dir", @@ -153,7 +154,7 @@ sub edit { # one day I used randomize_urllist for a boolean, so we must # list them explicitly --ak if (0) { - } elsif ($o =~ /^(wait_list|urllist|dontload_list)$/) { + } elsif ($o =~ /^(wait_list|urllist|dontload_list|plugin_list)$/) { # # ARRAYS @@ -768,7 +769,7 @@ sub prefs_lookup { use strict; use vars qw($AUTOLOAD $VERSION); - $VERSION = "5.5005"; + $VERSION = "5.5006"; # formerly CPAN::HandleConfig was known as CPAN::Config sub AUTOLOAD { ## no critic diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta.pm index 3ab0111844a..2a78691906b 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta.pm @@ -2,55 +2,56 @@ use 5.006; use strict; use warnings; package CPAN::Meta; -our $VERSION = '2.140640'; # VERSION - -# =head1 SYNOPSIS -# -# use v5.10; -# use strict; -# use warnings; -# use CPAN::Meta; -# use Module::Load; -# -# my $meta = CPAN::Meta->load_file('META.json'); -# -# printf "testing requirements for %s version %s\n", -# $meta->name, -# $meta->version; -# -# my $prereqs = $meta->effective_prereqs; -# -# for my $phase ( qw/configure runtime build test/ ) { -# say "Requirements for $phase:"; -# my $reqs = $prereqs->requirements_for($phase, "requires"); -# for my $module ( sort $reqs->required_modules ) { -# my $status; -# if ( eval { load $module unless $module eq 'perl'; 1 } ) { -# my $version = $module eq 'perl' ? $] : $module->VERSION; -# $status = $reqs->accepts_module($module, $version) -# ? "$version ok" : "$version not ok"; -# } else { -# $status = "missing" -# }; -# say " $module ($status)"; -# } -# } -# -# =head1 DESCRIPTION -# -# Software distributions released to the CPAN include a F<META.json> or, for -# older distributions, F<META.yml>, which describes the distribution, its -# contents, and the requirements for building and installing the distribution. -# The data structure stored in the F<META.json> file is described in -# L<CPAN::Meta::Spec>. -# -# CPAN::Meta provides a simple class to represent this distribution metadata (or -# I<distmeta>), along with some helpful methods for interrogating that data. -# -# The documentation below is only for the methods of the CPAN::Meta object. For -# information on the meaning of individual fields, consult the spec. -# -# =cut + +our $VERSION = '2.150001'; + +#pod =head1 SYNOPSIS +#pod +#pod use v5.10; +#pod use strict; +#pod use warnings; +#pod use CPAN::Meta; +#pod use Module::Load; +#pod +#pod my $meta = CPAN::Meta->load_file('META.json'); +#pod +#pod printf "testing requirements for %s version %s\n", +#pod $meta->name, +#pod $meta->version; +#pod +#pod my $prereqs = $meta->effective_prereqs; +#pod +#pod for my $phase ( qw/configure runtime build test/ ) { +#pod say "Requirements for $phase:"; +#pod my $reqs = $prereqs->requirements_for($phase, "requires"); +#pod for my $module ( sort $reqs->required_modules ) { +#pod my $status; +#pod if ( eval { load $module unless $module eq 'perl'; 1 } ) { +#pod my $version = $module eq 'perl' ? $] : $module->VERSION; +#pod $status = $reqs->accepts_module($module, $version) +#pod ? "$version ok" : "$version not ok"; +#pod } else { +#pod $status = "missing" +#pod }; +#pod say " $module ($status)"; +#pod } +#pod } +#pod +#pod =head1 DESCRIPTION +#pod +#pod Software distributions released to the CPAN include a F<META.json> or, for +#pod older distributions, F<META.yml>, which describes the distribution, its +#pod contents, and the requirements for building and installing the distribution. +#pod The data structure stored in the F<META.json> file is described in +#pod L<CPAN::Meta::Spec>. +#pod +#pod CPAN::Meta provides a simple class to represent this distribution metadata (or +#pod I<distmeta>), along with some helpful methods for interrogating that data. +#pod +#pod The documentation below is only for the methods of the CPAN::Meta object. For +#pod information on the meaning of individual fields, consult the spec. +#pod +#pod =cut use Carp qw(carp croak); use CPAN::Meta::Feature; @@ -61,22 +62,22 @@ use Parse::CPAN::Meta 1.4414 (); BEGIN { *_dclone = \&CPAN::Meta::Converter::_dclone } -# =head1 STRING DATA -# -# The following methods return a single value, which is the value for the -# corresponding entry in the distmeta structure. Values should be either undef -# or strings. -# -# =for :list -# * abstract -# * description -# * dynamic_config -# * generated_by -# * name -# * release_status -# * version -# -# =cut +#pod =head1 STRING DATA +#pod +#pod The following methods return a single value, which is the value for the +#pod corresponding entry in the distmeta structure. Values should be either undef +#pod or strings. +#pod +#pod =for :list +#pod * abstract +#pod * description +#pod * dynamic_config +#pod * generated_by +#pod * name +#pod * release_status +#pod * version +#pod +#pod =cut BEGIN { my @STRING_READERS = qw( @@ -95,20 +96,20 @@ BEGIN { } } -# =head1 LIST DATA -# -# These methods return lists of string values, which might be represented in the -# distmeta structure as arrayrefs or scalars: -# -# =for :list -# * authors -# * keywords -# * licenses -# -# The C<authors> and C<licenses> methods may also be called as C<author> and -# C<license>, respectively, to match the field name in the distmeta structure. -# -# =cut +#pod =head1 LIST DATA +#pod +#pod These methods return lists of string values, which might be represented in the +#pod distmeta structure as arrayrefs or scalars: +#pod +#pod =for :list +#pod * authors +#pod * keywords +#pod * licenses +#pod +#pod The C<authors> and C<licenses> methods may also be called as C<author> and +#pod C<license>, respectively, to match the field name in the distmeta structure. +#pod +#pod =cut BEGIN { my @LIST_READERS = qw( @@ -132,20 +133,20 @@ BEGIN { sub authors { $_[0]->author } sub licenses { $_[0]->license } -# =head1 MAP DATA -# -# These readers return hashrefs of arbitrary unblessed data structures, each -# described more fully in the specification: -# -# =for :list -# * meta_spec -# * resources -# * provides -# * no_index -# * prereqs -# * optional_features -# -# =cut +#pod =head1 MAP DATA +#pod +#pod These readers return hashrefs of arbitrary unblessed data structures, each +#pod described more fully in the specification: +#pod +#pod =for :list +#pod * meta_spec +#pod * resources +#pod * provides +#pod * no_index +#pod * prereqs +#pod * optional_features +#pod +#pod =cut BEGIN { my @MAP_READERS = qw( @@ -169,16 +170,16 @@ BEGIN { } } -# =head1 CUSTOM DATA -# -# A list of custom keys are available from the C<custom_keys> method and -# particular keys may be retrieved with the C<custom> method. -# -# say $meta->custom($_) for $meta->custom_keys; -# -# If a custom key refers to a data structure, a deep clone is returned. -# -# =cut +#pod =head1 CUSTOM DATA +#pod +#pod A list of custom keys are available from the C<custom_keys> method and +#pod particular keys may be retrieved with the C<custom> method. +#pod +#pod say $meta->custom($_) for $meta->custom_keys; +#pod +#pod If a custom key refers to a data structure, a deep clone is returned. +#pod +#pod =cut sub custom_keys { return grep { /^x_/i } keys %{$_[0]}; @@ -191,29 +192,29 @@ sub custom { return $value; } -# =method new -# -# my $meta = CPAN::Meta->new($distmeta_struct, \%options); -# -# Returns a valid CPAN::Meta object or dies if the supplied metadata hash -# reference fails to validate. Older-format metadata will be up-converted to -# version 2 if they validate against the original stated specification. -# -# It takes an optional hashref of options. Valid options include: -# -# =over -# -# =item * -# -# lazy_validation -- if true, new will attempt to convert the given metadata -# to version 2 before attempting to validate it. This means than any -# fixable errors will be handled by CPAN::Meta::Converter before validation. -# (Note that this might result in invalid optional data being silently -# dropped.) The default is false. -# -# =back -# -# =cut +#pod =method new +#pod +#pod my $meta = CPAN::Meta->new($distmeta_struct, \%options); +#pod +#pod Returns a valid CPAN::Meta object or dies if the supplied metadata hash +#pod reference fails to validate. Older-format metadata will be up-converted to +#pod version 2 if they validate against the original stated specification. +#pod +#pod It takes an optional hashref of options. Valid options include: +#pod +#pod =over +#pod +#pod =item * +#pod +#pod lazy_validation -- if true, new will attempt to convert the given metadata +#pod to version 2 before attempting to validate it. This means than any +#pod fixable errors will be handled by CPAN::Meta::Converter before validation. +#pod (Note that this might result in invalid optional data being silently +#pod dropped.) The default is false. +#pod +#pod =back +#pod +#pod =cut sub _new { my ($class, $struct, $options) = @_; @@ -254,15 +255,15 @@ sub new { return $self; } -# =method create -# -# my $meta = CPAN::Meta->create($distmeta_struct, \%options); -# -# This is same as C<new()>, except that C<generated_by> and C<meta-spec> fields -# will be generated if not provided. This means the metadata structure is -# assumed to otherwise follow the latest L<CPAN::Meta::Spec>. -# -# =cut +#pod =method create +#pod +#pod my $meta = CPAN::Meta->create($distmeta_struct, \%options); +#pod +#pod This is same as C<new()>, except that C<generated_by> and C<meta-spec> fields +#pod will be generated if not provided. This means the metadata structure is +#pod assumed to otherwise follow the latest L<CPAN::Meta::Spec>. +#pod +#pod =cut sub create { my ($class, $struct, $options) = @_; @@ -274,19 +275,19 @@ sub create { return $self; } -# =method load_file -# -# my $meta = CPAN::Meta->load_file($distmeta_file, \%options); -# -# Given a pathname to a file containing metadata, this deserializes the file -# according to its file suffix and constructs a new C<CPAN::Meta> object, just -# like C<new()>. It will die if the deserialized version fails to validate -# against its stated specification version. -# -# It takes the same options as C<new()> but C<lazy_validation> defaults to -# true. -# -# =cut +#pod =method load_file +#pod +#pod my $meta = CPAN::Meta->load_file($distmeta_file, \%options); +#pod +#pod Given a pathname to a file containing metadata, this deserializes the file +#pod according to its file suffix and constructs a new C<CPAN::Meta> object, just +#pod like C<new()>. It will die if the deserialized version fails to validate +#pod against its stated specification version. +#pod +#pod It takes the same options as C<new()> but C<lazy_validation> defaults to +#pod true. +#pod +#pod =cut sub load_file { my ($class, $file, $options) = @_; @@ -304,14 +305,14 @@ sub load_file { return $self; } -# =method load_yaml_string -# -# my $meta = CPAN::Meta->load_yaml_string($yaml, \%options); -# -# This method returns a new CPAN::Meta object using the first document in the -# given YAML string. In other respects it is identical to C<load_file()>. -# -# =cut +#pod =method load_yaml_string +#pod +#pod my $meta = CPAN::Meta->load_yaml_string($yaml, \%options); +#pod +#pod This method returns a new CPAN::Meta object using the first document in the +#pod given YAML string. In other respects it is identical to C<load_file()>. +#pod +#pod =cut sub load_yaml_string { my ($class, $yaml, $options) = @_; @@ -326,14 +327,14 @@ sub load_yaml_string { return $self; } -# =method load_json_string -# -# my $meta = CPAN::Meta->load_json_string($json, \%options); -# -# This method returns a new CPAN::Meta object using the structure represented by -# the given JSON string. In other respects it is identical to C<load_file()>. -# -# =cut +#pod =method load_json_string +#pod +#pod my $meta = CPAN::Meta->load_json_string($json, \%options); +#pod +#pod This method returns a new CPAN::Meta object using the structure represented by +#pod the given JSON string. In other respects it is identical to C<load_file()>. +#pod +#pod =cut sub load_json_string { my ($class, $json, $options) = @_; @@ -348,15 +349,15 @@ sub load_json_string { return $self; } -# =method load_string -# -# my $meta = CPAN::Meta->load_string($string, \%options); -# -# If you don't know if a string contains YAML or JSON, this method will use -# L<Parse::CPAN::Meta> to guess. In other respects it is identical to -# C<load_file()>. -# -# =cut +#pod =method load_string +#pod +#pod my $meta = CPAN::Meta->load_string($string, \%options); +#pod +#pod If you don't know if a string contains YAML or JSON, this method will use +#pod L<Parse::CPAN::Meta> to guess. In other respects it is identical to +#pod C<load_file()>. +#pod +#pod =cut sub load_string { my ($class, $string, $options) = @_; @@ -371,27 +372,27 @@ sub load_string { return $self; } -# =method save -# -# $meta->save($distmeta_file, \%options); -# -# Serializes the object as JSON and writes it to the given file. The only valid -# option is C<version>, which defaults to '2'. On Perl 5.8.1 or later, the file -# is saved with UTF-8 encoding. -# -# For C<version> 2 (or higher), the filename should end in '.json'. L<JSON::PP> -# is the default JSON backend. Using another JSON backend requires L<JSON> 2.5 or -# later and you must set the C<$ENV{PERL_JSON_BACKEND}> to a supported alternate -# backend like L<JSON::XS>. -# -# For C<version> less than 2, the filename should end in '.yml'. -# L<CPAN::Meta::Converter> is used to generate an older metadata structure, which -# is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may -# set the C<$ENV{PERL_YAML_BACKEND}> to a supported alternative backend, though -# this is not recommended due to subtle incompatibilities between YAML parsers on -# CPAN. -# -# =cut +#pod =method save +#pod +#pod $meta->save($distmeta_file, \%options); +#pod +#pod Serializes the object as JSON and writes it to the given file. The only valid +#pod option is C<version>, which defaults to '2'. On Perl 5.8.1 or later, the file +#pod is saved with UTF-8 encoding. +#pod +#pod For C<version> 2 (or higher), the filename should end in '.json'. L<JSON::PP> +#pod is the default JSON backend. Using another JSON backend requires L<JSON> 2.5 or +#pod later and you must set the C<$ENV{PERL_JSON_BACKEND}> to a supported alternate +#pod backend like L<JSON::XS>. +#pod +#pod For C<version> less than 2, the filename should end in '.yml'. +#pod L<CPAN::Meta::Converter> is used to generate an older metadata structure, which +#pod is serialized to YAML. CPAN::Meta::YAML is the default YAML backend. You may +#pod set the C<$ENV{PERL_YAML_BACKEND}> to a supported alternative backend, though +#pod this is not recommended due to subtle incompatibilities between YAML parsers on +#pod CPAN. +#pod +#pod =cut sub save { my ($self, $file, $options) = @_; @@ -419,32 +420,32 @@ sub save { return 1; } -# =method meta_spec_version -# -# This method returns the version part of the C<meta_spec> entry in the distmeta -# structure. It is equivalent to: -# -# $meta->meta_spec->{version}; -# -# =cut +#pod =method meta_spec_version +#pod +#pod This method returns the version part of the C<meta_spec> entry in the distmeta +#pod structure. It is equivalent to: +#pod +#pod $meta->meta_spec->{version}; +#pod +#pod =cut sub meta_spec_version { my ($self) = @_; return $self->meta_spec->{version}; } -# =method effective_prereqs -# -# my $prereqs = $meta->effective_prereqs; -# -# my $prereqs = $meta->effective_prereqs( \@feature_identifiers ); -# -# This method returns a L<CPAN::Meta::Prereqs> object describing all the -# prereqs for the distribution. If an arrayref of feature identifiers is given, -# the prereqs for the identified features are merged together with the -# distribution's core prereqs before the CPAN::Meta::Prereqs object is returned. -# -# =cut +#pod =method effective_prereqs +#pod +#pod my $prereqs = $meta->effective_prereqs; +#pod +#pod my $prereqs = $meta->effective_prereqs( \@feature_identifiers ); +#pod +#pod This method returns a L<CPAN::Meta::Prereqs> object describing all the +#pod prereqs for the distribution. If an arrayref of feature identifiers is given, +#pod the prereqs for the identified features are merged together with the +#pod distribution's core prereqs before the CPAN::Meta::Prereqs object is returned. +#pod +#pod =cut sub effective_prereqs { my ($self, $features) = @_; @@ -459,17 +460,18 @@ sub effective_prereqs { return $prereq->with_merged_prereqs(\@other); } -# =method should_index_file -# -# ... if $meta->should_index_file( $filename ); -# -# This method returns true if the given file should be indexed. It decides this -# by checking the C<file> and C<directory> keys in the C<no_index> property of -# the distmeta structure. -# -# C<$filename> should be given in unix format. -# -# =cut +#pod =method should_index_file +#pod +#pod ... if $meta->should_index_file( $filename ); +#pod +#pod This method returns true if the given file should be indexed. It decides this +#pod by checking the C<file> and C<directory> keys in the C<no_index> property of +#pod the distmeta structure. Note that neither the version format nor +#pod C<release_status> are considered. +#pod +#pod C<$filename> should be given in unix format. +#pod +#pod =cut sub should_index_file { my ($self, $filename) = @_; @@ -486,15 +488,16 @@ sub should_index_file { return 1; } -# =method should_index_package -# -# ... if $meta->should_index_package( $package ); -# -# This method returns true if the given package should be indexed. It decides -# this by checking the C<package> and C<namespace> keys in the C<no_index> -# property of the distmeta structure. -# -# =cut +#pod =method should_index_package +#pod +#pod ... if $meta->should_index_package( $package ); +#pod +#pod This method returns true if the given package should be indexed. It decides +#pod this by checking the C<package> and C<namespace> keys in the C<no_index> +#pod property of the distmeta structure. Note that neither the version format nor +#pod C<release_status> are considered. +#pod +#pod =cut sub should_index_package { my ($self, $package) = @_; @@ -510,14 +513,14 @@ sub should_index_package { return 1; } -# =method features -# -# my @feature_objects = $meta->features; -# -# This method returns a list of L<CPAN::Meta::Feature> objects, one for each -# optional feature described by the distribution's metadata. -# -# =cut +#pod =method features +#pod +#pod my @feature_objects = $meta->features; +#pod +#pod This method returns a list of L<CPAN::Meta::Feature> objects, one for each +#pod optional feature described by the distribution's metadata. +#pod +#pod =cut sub features { my ($self) = @_; @@ -529,15 +532,15 @@ sub features { return @features; } -# =method feature -# -# my $feature_object = $meta->feature( $identifier ); -# -# This method returns a L<CPAN::Meta::Feature> object for the optional feature -# with the given identifier. If no feature with that identifier exists, an -# exception will be raised. -# -# =cut +#pod =method feature +#pod +#pod my $feature_object = $meta->feature( $identifier ); +#pod +#pod This method returns a L<CPAN::Meta::Feature> object for the optional feature +#pod with the given identifier. If no feature with that identifier exists, an +#pod exception will be raised. +#pod +#pod =cut sub feature { my ($self, $ident) = @_; @@ -548,18 +551,18 @@ sub feature { return CPAN::Meta::Feature->new($ident, $f); } -# =method as_struct -# -# my $copy = $meta->as_struct( \%options ); -# -# This method returns a deep copy of the object's metadata as an unblessed hash -# reference. It takes an optional hashref of options. If the hashref contains -# a C<version> argument, the copied metadata will be converted to the version -# of the specification and returned. For example: -# -# my $old_spec = $meta->as_struct( {version => "1.4"} ); -# -# =cut +#pod =method as_struct +#pod +#pod my $copy = $meta->as_struct( \%options ); +#pod +#pod This method returns a deep copy of the object's metadata as an unblessed hash +#pod reference. It takes an optional hashref of options. If the hashref contains +#pod a C<version> argument, the copied metadata will be converted to the version +#pod of the specification and returned. For example: +#pod +#pod my $old_spec = $meta->as_struct( {version => "1.4"} ); +#pod +#pod =cut sub as_struct { my ($self, $options) = @_; @@ -571,24 +574,24 @@ sub as_struct { return $struct; } -# =method as_string -# -# my $string = $meta->as_string( \%options ); -# -# This method returns a serialized copy of the object's metadata as a character -# string. (The strings are B<not> UTF-8 encoded.) It takes an optional hashref -# of options. If the hashref contains a C<version> argument, the copied metadata -# will be converted to the version of the specification and returned. For -# example: -# -# my $string = $meta->as_string( {version => "1.4"} ); -# -# For C<version> greater than or equal to 2, the string will be serialized as -# JSON. For C<version> less than 2, the string will be serialized as YAML. In -# both cases, the same rules are followed as in the C<save()> method for choosing -# a serialization backend. -# -# =cut +#pod =method as_string +#pod +#pod my $string = $meta->as_string( \%options ); +#pod +#pod This method returns a serialized copy of the object's metadata as a character +#pod string. (The strings are B<not> UTF-8 encoded.) It takes an optional hashref +#pod of options. If the hashref contains a C<version> argument, the copied metadata +#pod will be converted to the version of the specification and returned. For +#pod example: +#pod +#pod my $string = $meta->as_string( {version => "1.4"} ); +#pod +#pod For C<version> greater than or equal to 2, the string will be serialized as +#pod JSON. For C<version> less than 2, the string will be serialized as YAML. In +#pod both cases, the same rules are followed as in the C<save()> method for choosing +#pod a serialization backend. +#pod +#pod =cut sub as_string { my ($self, $options) = @_; @@ -641,7 +644,7 @@ CPAN::Meta - the distribution metadata for a CPAN dist =head1 VERSION -version 2.140640 +version 2.150001 =head1 SYNOPSIS @@ -799,7 +802,8 @@ distribution's core prereqs before the CPAN::Meta::Prereqs object is returned. This method returns true if the given file should be indexed. It decides this by checking the C<file> and C<directory> keys in the C<no_index> property of -the distmeta structure. +the distmeta structure. Note that neither the version format nor +C<release_status> are considered. C<$filename> should be given in unix format. @@ -809,7 +813,8 @@ C<$filename> should be given in unix format. This method returns true if the given package should be indexed. It decides this by checking the C<package> and C<namespace> keys in the C<no_index> -property of the distmeta structure. +property of the distmeta structure. Note that neither the version format nor +C<release_status> are considered. =head2 features @@ -1020,6 +1025,8 @@ Ricardo Signes <rjbs@cpan.org> =head1 CONTRIBUTORS +=for stopwords Ansgar Burchardt Avar Arnfjord Bjarmason Christopher J. Madsen Chuck Adams Cory G Watson Damyan Ivanov Eric Wilhelm Graham Knop Gregor Hermann Karen Etheridge Kenichi Ishigaki Ken Williams Lars Dieckow Leon Timmermans majensen Mark Fowler Matt S Trout Michael G. Schwern mohawk2 moznion Olaf Alders Olivier Mengue Randy Sims + =over 4 =item * @@ -1052,6 +1059,10 @@ Eric Wilhelm <ewilhelm@cpan.org> =item * +Graham Knop <haarg@haarg.org> + +=item * + Gregor Hermann <gregoa@debian.org> =item * @@ -1060,11 +1071,11 @@ Karen Etheridge <ether@cpan.org> =item * -Ken Williams <kwilliams@cpan.org> +Kenichi Ishigaki <ishigaki@cpan.org> =item * -Kenichi Ishigaki <ishigaki@cpan.org> +Ken Williams <kwilliams@cpan.org> =item * @@ -1076,14 +1087,30 @@ Leon Timmermans <leont@cpan.org> =item * +majensen <maj@fortinbras.us> + +=item * + Mark Fowler <markf@cpan.org> =item * +Matt S Trout <mst@shadowcat.co.uk> + +=item * + Michael G. Schwern <mschwern@cpan.org> =item * +mohawk2 <mohawk2@users.noreply.github.com> + +=item * + +moznion <moznion@gmail.com> + +=item * + Olaf Alders <olaf@wundersolutions.com> =item * diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/Converter.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/Converter.pm index 1bb4431f2b2..8b32b1360ab 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta/Converter.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/Converter.pm @@ -2,31 +2,46 @@ use 5.006; use strict; use warnings; package CPAN::Meta::Converter; -our $VERSION = '2.140640'; # VERSION -# =head1 SYNOPSIS -# -# my $struct = decode_json_file('META.json'); -# -# my $cmc = CPAN::Meta::Converter->new( $struct ); -# -# my $new_struct = $cmc->convert( version => "2" ); -# -# =head1 DESCRIPTION -# -# This module converts CPAN Meta structures from one form to another. The -# primary use is to convert older structures to the most modern version of -# the specification, but other transformations may be implemented in the -# future as needed. (E.g. stripping all custom fields or stripping all -# optional fields.) -# -# =cut +our $VERSION = '2.150001'; + +#pod =head1 SYNOPSIS +#pod +#pod my $struct = decode_json_file('META.json'); +#pod +#pod my $cmc = CPAN::Meta::Converter->new( $struct ); +#pod +#pod my $new_struct = $cmc->convert( version => "2" ); +#pod +#pod =head1 DESCRIPTION +#pod +#pod This module converts CPAN Meta structures from one form to another. The +#pod primary use is to convert older structures to the most modern version of +#pod the specification, but other transformations may be implemented in the +#pod future as needed. (E.g. stripping all custom fields or stripping all +#pod optional fields.) +#pod +#pod =cut use CPAN::Meta::Validator; use CPAN::Meta::Requirements; -use version 0.88 (); use Parse::CPAN::Meta 1.4400 (); -use List::Util 1.33 qw/all/; + +# To help ExtUtils::MakeMaker bootstrap CPAN::Meta::Requirements on perls +# before 5.10, we fall back to the EUMM bundled compatibility version module if +# that's the only thing available. This shouldn't ever happen in a normal CPAN +# install of CPAN::Meta::Requirements, as version.pm will be picked up from +# prereqs and be available at runtime. + +BEGIN { + eval "use version ()"; ## no critic + if ( my $err = $@ ) { + eval "use ExtUtils::MakeMaker::version" or die $err; ## no critic + } +} + +# Perl 5.10.0 didn't have "is_qv" in version.pm +*_is_qv = version->can('is_qv') ? sub { $_[0]->is_qv } : sub { exists $_[0]->{qv} }; sub _dclone { my $ref = shift; @@ -36,12 +51,14 @@ sub _dclone { # right thing for typical things that might be there, like version objects, # Path::Class objects, etc. no warnings 'once'; - local *UNIVERSAL::TO_JSON = sub { return "$_[0]" }; - - my $backend = Parse::CPAN::Meta->json_backend(); - return $backend->new->utf8->decode( - $backend->new->utf8->allow_blessed->convert_blessed->encode($ref) - ); + no warnings 'redefine'; + local *UNIVERSAL::TO_JSON = sub { "$_[0]" }; + + my $json = Parse::CPAN::Meta->json_backend()->new + ->utf8 + ->allow_blessed + ->convert_blessed; + $json->decode($json->encode($ref)) } my %known_specs = ( @@ -247,11 +264,11 @@ sub _downgrade_license { } elsif( ref $element eq 'ARRAY' ) { if ( @$element > 1) { - if ( all { $is_open_source{ $license_downgrade_map{lc $_} || 'unknown' } } @$element ) { - return 'open_source'; + if (grep { !$is_open_source{ $license_downgrade_map{lc $_} || 'unknown' } } @$element) { + return 'unknown'; } else { - return 'unknown'; + return 'open_source'; } } elsif ( @$element == 1 ) { @@ -303,11 +320,11 @@ sub _no_index_1_2 { # common mistake: files -> file if ( exists $no_index->{files} ) { - $no_index->{file} = delete $no_index->{file}; + $no_index->{file} = delete $no_index->{files}; } # common mistake: modules -> module if ( exists $no_index->{modules} ) { - $no_index->{module} = delete $no_index->{module}; + $no_index->{module} = delete $no_index->{modules}; } return _convert($no_index, $no_index_spec_1_2); } @@ -331,11 +348,11 @@ sub _no_index_directory { } # common mistake: files -> file if ( exists $element->{files} ) { - $element->{file} = delete $element->{file}; + $element->{file} = delete $element->{files}; } # common mistake: modules -> module if ( exists $element->{modules} ) { - $element->{module} = delete $element->{module}; + $element->{module} = delete $element->{modules}; } my $spec = $version == 2 ? $no_index_spec_2 : $no_index_spec_1_3; return _convert($element, $spec); @@ -362,7 +379,7 @@ sub _clean_version { # XXX check defined $v and not just $v because version objects leak memory # in boolean context -- dagolden, 2012-02-03 if ( defined $v ) { - return $v->is_qv ? $v->normal : $element; + return _is_qv($v) ? $v->normal : $element; } else { return 0; @@ -372,8 +389,8 @@ sub _clean_version { sub _bad_version_hook { my ($v) = @_; $v =~ s{[a-z]+$}{}; # strip trailing alphabetics - my $vobj = eval { version->parse($v) }; - return defined($vobj) ? $vobj : version->parse(0); # or give up + my $vobj = eval { version->new($v) }; + return defined($vobj) ? $vobj : version->new(0); # or give up } sub _version_map { @@ -682,7 +699,7 @@ sub _resources_1_2 { my (undef, undef, $meta) = @_; my $resources = $meta->{resources} || {}; if ( $meta->{license_url} && ! $resources->{license} ) { - $resources->{license} = $meta->license_url + $resources->{license} = $meta->{license_url} if _is_urlish($meta->{license_url}); } return unless keys %$resources; @@ -740,12 +757,15 @@ sub _provides { } sub _convert { - my ($data, $spec, $to_version) = @_; + my ($data, $spec, $to_version, $is_fragment) = @_; my $new_data = {}; for my $key ( keys %$spec ) { next if $key eq ':custom' || $key eq ':drop'; next unless my $fcn = $spec->{$key}; + if ( $is_fragment && $key eq 'generated_by' ) { + $fcn = \&_keep; + } die "spec for '$key' is not a coderef" unless ref $fcn && ref $fcn eq 'CODE'; my $new_value = $fcn->($data->{$key}, $key, $data, $to_version); @@ -1230,27 +1250,80 @@ my %cleanup = ( }, ); +# for a given field in a spec version, what fields will it feed +# into in the *latest* spec (i.e. v2); meta-spec omitted because +# we always expect a meta-spec to be generated +my %fragments_generate = ( + '2' => { + 'abstract' => 'abstract', + 'author' => 'author', + 'generated_by' => 'generated_by', + 'license' => 'license', + 'name' => 'name', + 'version' => 'version', + 'dynamic_config' => 'dynamic_config', + 'release_status' => 'release_status', + 'keywords' => 'keywords', + 'no_index' => 'no_index', + 'optional_features' => 'optional_features', + 'provides' => 'provides', + 'resources' => 'resources', + 'description' => 'description', + 'prereqs' => 'prereqs', + }, + '1.4' => { + 'abstract' => 'abstract', + 'author' => 'author', + 'generated_by' => 'generated_by', + 'license' => 'license', + 'name' => 'name', + 'version' => 'version', + 'build_requires' => 'prereqs', + 'conflicts' => 'prereqs', + 'distribution_type' => 'distribution_type', + 'dynamic_config' => 'dynamic_config', + 'keywords' => 'keywords', + 'no_index' => 'no_index', + 'optional_features' => 'optional_features', + 'provides' => 'provides', + 'recommends' => 'prereqs', + 'requires' => 'prereqs', + 'resources' => 'resources', + 'configure_requires' => 'prereqs', + }, +); +# this is not quite true but will work well enough +# as 1.4 is a superset of earlier ones +$fragments_generate{$_} = $fragments_generate{'1.4'} for qw/1.3 1.2 1.1 1.0/; + #--------------------------------------------------------------------------# # Code #--------------------------------------------------------------------------# -# =method new -# -# my $cmc = CPAN::Meta::Converter->new( $struct ); -# -# The constructor should be passed a valid metadata structure but invalid -# structures are accepted. If no meta-spec version is provided, version 1.0 will -# be assumed. -# -# =cut +#pod =method new +#pod +#pod my $cmc = CPAN::Meta::Converter->new( $struct ); +#pod +#pod The constructor should be passed a valid metadata structure but invalid +#pod structures are accepted. If no meta-spec version is provided, version 1.0 will +#pod be assumed. +#pod +#pod Optionally, you can provide a C<default_version> argument after C<$struct>: +#pod +#pod my $cmc = CPAN::Meta::Converter->new( $struct, default_version => "1.4" ); +#pod +#pod This is only needed when converting a metadata fragment that does not include a +#pod C<meta-spec> field. +#pod +#pod =cut sub new { - my ($class,$data) = @_; + my ($class,$data,%args) = @_; # create an attributes hash my $self = { 'data' => $data, - 'spec' => _extract_spec_version($data), + 'spec' => _extract_spec_version($data, $args{default_version}), }; # create the object @@ -1258,11 +1331,11 @@ sub new { } sub _extract_spec_version { - my ($data) = @_; + my ($data, $default) = @_; my $spec = $data->{'meta-spec'}; # is meta-spec there and valid? - return "1.0" unless defined $spec && ref $spec eq 'HASH'; # before meta-spec? + return( $default || "1.0" ) unless defined $spec && ref $spec eq 'HASH'; # before meta-spec? # does the version key look like a valid version? my $v = $spec->{version}; @@ -1274,72 +1347,75 @@ sub _extract_spec_version { # otherwise, use heuristics: look for 1.x vs 2.0 fields return "2" if exists $data->{prereqs}; return "1.4" if exists $data->{configure_requires}; - return "1.2"; # when meta-spec was first defined + return( $default || "1.2" ); # when meta-spec was first defined } -# =method convert -# -# my $new_struct = $cmc->convert( version => "2" ); -# -# Returns a new hash reference with the metadata converted to a different form. -# C<convert> will die if any conversion/standardization still results in an -# invalid structure. -# -# Valid parameters include: -# -# =over -# -# =item * -# -# C<version> -- Indicates the desired specification version (e.g. "1.0", "1.1" ... "1.4", "2"). -# Defaults to the latest version of the CPAN Meta Spec. -# -# =back -# -# Conversion proceeds through each version in turn. For example, a version 1.2 -# structure might be converted to 1.3 then 1.4 then finally to version 2. The -# conversion process attempts to clean-up simple errors and standardize data. -# For example, if C<author> is given as a scalar, it will converted to an array -# reference containing the item. (Converting a structure to its own version will -# also clean-up and standardize.) -# -# When data are cleaned and standardized, missing or invalid fields will be -# replaced with sensible defaults when possible. This may be lossy or imprecise. -# For example, some badly structured META.yml files on CPAN have prerequisite -# modules listed as both keys and values: -# -# requires => { 'Foo::Bar' => 'Bam::Baz' } -# -# These would be split and each converted to a prerequisite with a minimum -# version of zero. -# -# When some mandatory fields are missing or invalid, the conversion will attempt -# to provide a sensible default or will fill them with a value of 'unknown'. For -# example a missing or unrecognized C<license> field will result in a C<license> -# field of 'unknown'. Fields that may get an 'unknown' include: -# -# =for :list -# * abstract -# * author -# * license -# -# =cut +#pod =method convert +#pod +#pod my $new_struct = $cmc->convert( version => "2" ); +#pod +#pod Returns a new hash reference with the metadata converted to a different form. +#pod C<convert> will die if any conversion/standardization still results in an +#pod invalid structure. +#pod +#pod Valid parameters include: +#pod +#pod =over +#pod +#pod =item * +#pod +#pod C<version> -- Indicates the desired specification version (e.g. "1.0", "1.1" ... "1.4", "2"). +#pod Defaults to the latest version of the CPAN Meta Spec. +#pod +#pod =back +#pod +#pod Conversion proceeds through each version in turn. For example, a version 1.2 +#pod structure might be converted to 1.3 then 1.4 then finally to version 2. The +#pod conversion process attempts to clean-up simple errors and standardize data. +#pod For example, if C<author> is given as a scalar, it will converted to an array +#pod reference containing the item. (Converting a structure to its own version will +#pod also clean-up and standardize.) +#pod +#pod When data are cleaned and standardized, missing or invalid fields will be +#pod replaced with sensible defaults when possible. This may be lossy or imprecise. +#pod For example, some badly structured META.yml files on CPAN have prerequisite +#pod modules listed as both keys and values: +#pod +#pod requires => { 'Foo::Bar' => 'Bam::Baz' } +#pod +#pod These would be split and each converted to a prerequisite with a minimum +#pod version of zero. +#pod +#pod When some mandatory fields are missing or invalid, the conversion will attempt +#pod to provide a sensible default or will fill them with a value of 'unknown'. For +#pod example a missing or unrecognized C<license> field will result in a C<license> +#pod field of 'unknown'. Fields that may get an 'unknown' include: +#pod +#pod =for :list +#pod * abstract +#pod * author +#pod * license +#pod +#pod =cut sub convert { my ($self, %args) = @_; my $args = { %args }; my $new_version = $args->{version} || $HIGHEST; + my $is_fragment = $args->{is_fragment}; my ($old_version) = $self->{spec}; my $converted = _dclone($self->{data}); if ( $old_version == $new_version ) { - $converted = _convert( $converted, $cleanup{$old_version}, $old_version ); - my $cmv = CPAN::Meta::Validator->new( $converted ); - unless ( $cmv->is_valid ) { - my $errs = join("\n", $cmv->errors); - die "Failed to clean-up $old_version metadata. Errors:\n$errs\n"; + $converted = _convert( $converted, $cleanup{$old_version}, $old_version, $is_fragment ); + unless ( $args->{is_fragment} ) { + my $cmv = CPAN::Meta::Validator->new( $converted ); + unless ( $cmv->is_valid ) { + my $errs = join("\n", $cmv->errors); + die "Failed to clean-up $old_version metadata. Errors:\n$errs\n"; + } } return $converted; } @@ -1349,11 +1425,13 @@ sub convert { next if $vers[$i] > $old_version; last if $vers[$i+1] < $new_version; my $spec_string = "$vers[$i+1]-from-$vers[$i]"; - $converted = _convert( $converted, $down_convert{$spec_string}, $vers[$i+1] ); - my $cmv = CPAN::Meta::Validator->new( $converted ); - unless ( $cmv->is_valid ) { - my $errs = join("\n", $cmv->errors); - die "Failed to downconvert metadata to $vers[$i+1]. Errors:\n$errs\n"; + $converted = _convert( $converted, $down_convert{$spec_string}, $vers[$i+1], $is_fragment ); + unless ( $args->{is_fragment} ) { + my $cmv = CPAN::Meta::Validator->new( $converted ); + unless ( $cmv->is_valid ) { + my $errs = join("\n", $cmv->errors); + die "Failed to downconvert metadata to $vers[$i+1]. Errors:\n$errs\n"; + } } } return $converted; @@ -1364,23 +1442,51 @@ sub convert { next if $vers[$i] < $old_version; last if $vers[$i+1] > $new_version; my $spec_string = "$vers[$i+1]-from-$vers[$i]"; - $converted = _convert( $converted, $up_convert{$spec_string}, $vers[$i+1] ); - my $cmv = CPAN::Meta::Validator->new( $converted ); - unless ( $cmv->is_valid ) { - my $errs = join("\n", $cmv->errors); - die "Failed to upconvert metadata to $vers[$i+1]. Errors:\n$errs\n"; + $converted = _convert( $converted, $up_convert{$spec_string}, $vers[$i+1], $is_fragment ); + unless ( $args->{is_fragment} ) { + my $cmv = CPAN::Meta::Validator->new( $converted ); + unless ( $cmv->is_valid ) { + my $errs = join("\n", $cmv->errors); + die "Failed to upconvert metadata to $vers[$i+1]. Errors:\n$errs\n"; + } } } return $converted; } } +#pod =method upgrade_fragment +#pod +#pod my $new_struct = $cmc->upgrade_fragment; +#pod +#pod Returns a new hash reference with the metadata converted to the latest version +#pod of the CPAN Meta Spec. No validation is done on the result -- you must +#pod validate after merging fragments into a complete metadata document. +#pod +#pod Available since version 2.141170. +#pod +#pod =cut + +sub upgrade_fragment { + my ($self) = @_; + my ($old_version) = $self->{spec}; + my %expected = + map {; $_ => 1 } + grep { defined } + map { $fragments_generate{$old_version}{$_} } + keys %{ $self->{data} }; + my $converted = $self->convert( version => $HIGHEST, is_fragment => 1 ); + for my $key ( keys %$converted ) { + next if $key =~ /^x_/i || $key eq 'meta-spec'; + delete $converted->{$key} unless $expected{$key}; + } + return $converted; +} + 1; # ABSTRACT: Convert CPAN distribution metadata structures -__END__ - =pod =encoding UTF-8 @@ -1391,7 +1497,7 @@ CPAN::Meta::Converter - Convert CPAN distribution metadata structures =head1 VERSION -version 2.140640 +version 2.150001 =head1 SYNOPSIS @@ -1419,6 +1525,13 @@ The constructor should be passed a valid metadata structure but invalid structures are accepted. If no meta-spec version is provided, version 1.0 will be assumed. +Optionally, you can provide a C<default_version> argument after C<$struct>: + + my $cmc = CPAN::Meta::Converter->new( $struct, default_version => "1.4" ); + +This is only needed when converting a metadata fragment that does not include a +C<meta-spec> field. + =head2 convert my $new_struct = $cmc->convert( version => "2" ); @@ -1476,6 +1589,16 @@ license =back +=head2 upgrade_fragment + + my $new_struct = $cmc->upgrade_fragment; + +Returns a new hash reference with the metadata converted to the latest version +of the CPAN Meta Spec. No validation is done on the result -- you must +validate after merging fragments into a complete metadata document. + +Available since version 2.141170. + =head1 BUGS Please report any bugs or feature using the CPAN Request Tracker. @@ -1507,3 +1630,8 @@ This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut + +__END__ + + +# vim: ts=2 sts=2 sw=2 et: diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/Feature.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/Feature.pm index f97cc652e83..4bfbb19b4c7 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta/Feature.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/Feature.pm @@ -2,28 +2,29 @@ use 5.006; use strict; use warnings; package CPAN::Meta::Feature; -our $VERSION = '2.140640'; # VERSION + +our $VERSION = '2.150001'; use CPAN::Meta::Prereqs; -# =head1 DESCRIPTION -# -# A CPAN::Meta::Feature object describes an optional feature offered by a CPAN -# distribution and specified in the distribution's F<META.json> (or F<META.yml>) -# file. -# -# For the most part, this class will only be used when operating on the result of -# the C<feature> or C<features> methods on a L<CPAN::Meta> object. -# -# =method new -# -# my $feature = CPAN::Meta::Feature->new( $identifier => \%spec ); -# -# This returns a new Feature object. The C<%spec> argument to the constructor -# should be the same as the value of the C<optional_feature> entry in the -# distmeta. It must contain entries for C<description> and C<prereqs>. -# -# =cut +#pod =head1 DESCRIPTION +#pod +#pod A CPAN::Meta::Feature object describes an optional feature offered by a CPAN +#pod distribution and specified in the distribution's F<META.json> (or F<META.yml>) +#pod file. +#pod +#pod For the most part, this class will only be used when operating on the result of +#pod the C<feature> or C<features> methods on a L<CPAN::Meta> object. +#pod +#pod =method new +#pod +#pod my $feature = CPAN::Meta::Feature->new( $identifier => \%spec ); +#pod +#pod This returns a new Feature object. The C<%spec> argument to the constructor +#pod should be the same as the value of the C<optional_feature> entry in the +#pod distmeta. It must contain entries for C<description> and C<prereqs>. +#pod +#pod =cut sub new { my ($class, $identifier, $spec) = @_; @@ -37,28 +38,28 @@ sub new { bless \%guts => $class; } -# =method identifier -# -# This method returns the feature's identifier. -# -# =cut +#pod =method identifier +#pod +#pod This method returns the feature's identifier. +#pod +#pod =cut sub identifier { $_[0]{identifier} } -# =method description -# -# This method returns the feature's long description. -# -# =cut +#pod =method description +#pod +#pod This method returns the feature's long description. +#pod +#pod =cut sub description { $_[0]{description} } -# =method prereqs -# -# This method returns the feature's prerequisites as a L<CPAN::Meta::Prereqs> -# object. -# -# =cut +#pod =method prereqs +#pod +#pod This method returns the feature's prerequisites as a L<CPAN::Meta::Prereqs> +#pod object. +#pod +#pod =cut sub prereqs { $_[0]{prereqs} } @@ -78,7 +79,7 @@ CPAN::Meta::Feature - an optional feature provided by a CPAN distribution =head1 VERSION -version 2.140640 +version 2.150001 =head1 DESCRIPTION diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/History.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/History.pm index 1ebf3893390..3d7e5585199 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta/History.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/History.pm @@ -3,7 +3,8 @@ use 5.006; use strict; use warnings; package CPAN::Meta::History; -our $VERSION = '2.140640'; # VERSION + +our $VERSION = '2.150001'; 1; @@ -21,7 +22,7 @@ CPAN::Meta::History - history of CPAN Meta Spec changes =head1 VERSION -version 2.140640 +version 2.150001 =head1 DESCRIPTION diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_0.pod b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_0.pod new file mode 100644 index 00000000000..1052c3eb440 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_0.pod @@ -0,0 +1,238 @@ +=for :stopwords DOAP RDF + +=head1 NAME + +CPAN::Meta::History::Meta_1_0 - Version 1.0 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.0 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Conversion from the original HTML to POD format + +=item * + +Include list of valid licenses from L<Module::Build> 0.17 rather than +linking to the module. + +=back + +=head1 DESCRIPTION + +This document describes version 1.0 of the F<META.yml> specification. + +The META.yml file describes important properties of contributed Perl +distributions such as the ones found on L<CPAN|http://www.cpan.org>. It is +typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>. + +The fields in the F<META.yml> file are meant to be helpful to people +maintaining module collections (like CPAN), for people writing +installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to +know some stuff about a distribution before downloading it and starting to +install it. + +=head1 Format + +F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format. The +reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in +L<this thread|http://archive.develooper.com/makemaker@perl.org/msg00405.html> +on the MakeMaker mailing list. + +The first line of a F<META.yml> file should be a valid L<YAML document header|http://www.yaml.org/spec/#.Document> +like C<"--- #YAML:1.0"> + +=head1 Fields + +The rest of the META.yml file is one big YAML +L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->, +whose keys are described here. + +=over 4 + +=item name + +Example: C<Module-Build> + +The name of the distribution. Often created by taking the "main +module" in the distribution and changing "::" to "-". Sometimes it's +completely different, however, as in the case of the +L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution. + +=item version + +Example: C<0.16> + +The version of the distribution to which the META.yml file refers. + +=item license + +Example: C<perl> + +The license under which this distribution may be used and +redistributed. + +Must be one of the following licenses: + +=over 4 + +=item perl + +The distribution may be copied and redistributed under the same terms as perl +itself (this is by far the most common licensing option for modules on CPAN). +This is a dual license, in which the user may choose between either the GPL or +the Artistic license. + +=item gpl + +The distribution is distributed under the terms of the Gnu General Public +License (L<http://www.opensource.org/licenses/gpl-license.php>). + +=item lgpl + +The distribution is distributed under the terms of the Gnu Lesser General +Public License (L<http://www.opensource.org/licenses/lgpl-license.php>). + +=item artistic + +The distribution is licensed under the Artistic License, as specified by the +Artistic file in the standard perl distribution. + +=item bsd + +The distribution is licensed under the BSD License +(L<http://www.opensource.org/licenses/bsd-license.php>). + +=item open_source + +The distribution is licensed under some other Open Source Initiative-approved +license listed at L<http://www.opensource.org/licenses/>. + +=item unrestricted + +The distribution is licensed under a license that is B<not> approved by +L<www.opensource.org|http://www.opensource.org> but that allows distribution +without restrictions. + +=item restrictive + +The distribution may not be redistributed without special permission from the +author and/or copyright holder. + +=back + +=item distribution_type + +Example: C<module> + +What kind of stuff is contained in this distribution. Most things on +CPAN are C<module>s (which can also mean a collection of +modules), but some things are C<script>s. + +=item requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution requires for proper +operation. The keys are the module names, and the values are version +specifications as described in the L<Module::Build|documentation for Module::Build's "requires" parameter>. + +I<Note: the exact nature of the fancy specifications like +C<< ">= 1.2, != 1.5, < 2.0" >> is subject to +change. Advance notice will be given here. The simple specifications +like C<"1.2"> will not change in format.> + +=item recommends + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution recommends for enhanced +operation. + +=item build_requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules required for building and/or testing of +this distribution. These dependencies are not required after the +module is installed. + +=item conflicts + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules that cannot be installed while this +distribution is installed. This is a pretty uncommon situation. + +=item dynamic_config + +Example: C<0> + +A boolean flag indicating whether a F<Build.PL> or +F<Makefile.PL> (or similar) must be executed, or whether this +module can be built, tested and installed solely from consulting its +metadata file. The main reason to set this to a true value if that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently L<Module::Build> doesn't actually do anything with +this flag - it's probably going to be up to higher-level tools like +L<CPAN|CPAN.pm> to do something useful with it. It can potentially +bring lots of security, packaging, and convenience improvements. + +=item generated_by + +Example: C<Module::Build version 0.16> + +Indicates the tool that was used to create this F<META.yml> file. It's +good form to include both the name of the tool and its version, but +this field is essentially opaque, at least for the moment. + +=back + +=head1 Related Projects + +=over 4 + +=item DOAP + +An RDF vocabulary to describe software projects. L<http://usefulinc.com/doap>. + +=back + +=head1 History + +=over 4 + +=item * + +B<March 14, 2003> (Pi day) - created version 1.0 of this document. + +=item * + +B<May 8, 2003> - added the "dynamic_config" field, which was missing from the +initial version. + +=back diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_1.pod b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_1.pod new file mode 100644 index 00000000000..69f34115189 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_1.pod @@ -0,0 +1,300 @@ +=for :stopwords Ingy READMEs WTF licensure + +=head1 NAME + +CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.1 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Conversion from the original HTML to POD format + +=item * + +Include list of valid licenses from L<Module::Build> 0.18 rather than +linking to the module. + +=back + +=head1 DESCRIPTION + +This document describes version 1.1 of the F<META.yml> specification. + +The F<META.yml> file describes important properties of contributed Perl +distributions such as the ones found on L<CPAN|http://www.cpan.org>. It is +typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>. + +The fields in the F<META.yml> file are meant to be helpful to people +maintaining module collections (like CPAN), for people writing +installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to +know some stuff about a distribution before downloading it and starting to +install it. + +=head1 Format + +F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format. The +reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in +L<this thread|http://archive.develooper.com/makemaker@perl.org/msg00405.html> +on the MakeMaker mailing list. + +The first line of a F<META.yml> file should be a valid L<YAML document header|http://www.yaml.org/spec/#.Document> +like C<"--- #YAML:1.0"> + +=head1 Fields + +The rest of the META.yml file is one big YAML +L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->, +whose keys are described here. + +=over 4 + +=item name + +Example: C<Module-Build> + +The name of the distribution. Often created by taking the "main +module" in the distribution and changing "::" to "-". Sometimes it's +completely different, however, as in the case of the +L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution. + +=item version + +Example: C<0.16> + +The version of the distribution to which the META.yml file refers. +This is a mandatory field. + +The version is essentially an arbitrary string, but I<must> be +only ASCII characters, and I<strongly should> be of the format +integer-dot-digit-digit, i.e. C<25.57>, optionally followed by +underscore-digit-digit, i.e. C<25.57_04>. + +The standard tools that deal with module distribution (PAUSE, CPAN, +etc.) form an identifier for each distribution by joining the 'name' +and 'version' attributes with a dash (C<->) character. Tools +who are prepared to deal with distributions that have no version +numbers generally omit the dash as well. + +=item license + +Example: C<perl> + +a descriptive term for the licenses ... not authoritative, but must +be consistent with licensure statements in the READMEs, documentation, etc. + +The license under which this distribution may be used and +redistributed. + +Must be one of the following licenses: + +=over 4 + +=item perl + +The distribution may be copied and redistributed under the same terms as perl +itself (this is by far the most common licensing option for modules on CPAN). +This is a dual license, in which the user may choose between either the GPL or +the Artistic license. + +=item gpl + +The distribution is distributed under the terms of the Gnu General Public +License (L<http://www.opensource.org/licenses/gpl-license.php>). + +=item lgpl + +The distribution is distributed under the terms of the Gnu Lesser General +Public License (L<http://www.opensource.org/licenses/lgpl-license.php>). + +=item artistic + +The distribution is licensed under the Artistic License, as specified by the +Artistic file in the standard perl distribution. + +=item bsd + +The distribution is licensed under the BSD License +(L<http://www.opensource.org/licenses/bsd-license.php>). + +=item open_source + +The distribution is licensed under some other Open Source Initiative-approved +license listed at L<http://www.opensource.org/licenses/>. + +=item unrestricted + +The distribution is licensed under a license that is B<not> approved by +L<www.opensource.org|http://www.opensource.org> but that allows distribution +without restrictions. + +=item restrictive + +The distribution may not be redistributed without special permission from the +author and/or copyright holder. + +=back + +=item license_uri + +This should contain a URI where the exact terms of the license may be found. + +(change "unrestricted" to "redistributable"?) + +=item distribution_type + +Example: C<module> + +What kind of stuff is contained in this distribution. Most things on +CPAN are C<module>s (which can also mean a collection of +modules), but some things are C<script>s. + +This field is basically meaningless, and tools (like Module::Build or +MakeMaker) will likely stop generating it in the future. + +=item private + +WTF is going on here? + +index_ignore: any application that indexes the contents of +distributions (PAUSE, search.cpan.org) ought to ignore the items +(packages, files, directories, namespace hierarchies). + +=item requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution requires for proper +operation. The keys are the module names, and the values are version +specifications as described in the L<Module::Build|documentation for Module::Build's "requires" parameter>. + +I<Note: the exact nature of the fancy specifications like +C<< ">= 1.2, != 1.5, < 2.0" >> is subject to +change. Advance notice will be given here. The simple specifications +like C<"1.2"> will not change in format.> + +=item recommends + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution recommends for enhanced +operation. + +=item build_requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules required for building and/or testing of +this distribution. These dependencies are not required after the +module is installed. + +=item conflicts + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules that cannot be installed while this +distribution is installed. This is a pretty uncommon situation. + +- possibly separate out test-time prereqs, complications include: can +tests be meaningfully preserved for later running? are test-time +prereqs in addition to build-time, or exclusive? + +- make official location for installed *distributions*, which can +contain tests, etc. + +=item dynamic_config + +Example: C<0> + +A boolean flag indicating whether a F<Build.PL> or +F<Makefile.PL> (or similar) must be executed, or whether this +module can be built, tested and installed solely from consulting its +metadata file. The main reason to set this to a true value if that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently L<Module::Build> doesn't actually do anything with +this flag - it's probably going to be up to higher-level tools like +L<CPAN|CPAN.pm> to do something useful with it. It can potentially +bring lots of security, packaging, and convenience improvements. + +=item generated_by + +Example: C<Module::Build version 0.16> + +Indicates the tool that was used to create this F<META.yml> file. It's +good form to include both the name of the tool and its version, but +this field is essentially opaque, at least for the moment. + +=back + +=head2 Ingy's suggestions + +=over 4 + +=item short_description + +add as field, containing abstract, maximum 80 characters, suggested minimum 40 characters + +=item description + +long version of abstract, should add? + +=item maturity + +alpha, beta, gamma, mature, stable + +=item author_id, owner_id + +=item categorization, keyword, chapter_id + +=item URL for further information + +could default to search.cpan.org on PAUSE + +=item namespaces + +can be specified for single elements by prepending +dotted-form, i.e. "com.example.my_application.my_property". Default +namespace for META.yml is probably "org.cpan.meta_author" or +something. Precedent for this is Apple's Carbon namespaces, I think. + +=back + +=head1 History + +=over 4 + +=item * + +B<March 14, 2003> (Pi day) - created version 1.0 of this document. + +=item * + +B<May 8, 2003> - added the "dynamic_config" field, which was missing from the +initial version. + +=back diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_2.pod b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_2.pod new file mode 100644 index 00000000000..69cd5bb5861 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_2.pod @@ -0,0 +1,711 @@ +=for :stopwords MailingList RWS subcontext + +=head1 NAME + +CPAN::Meta::History::Meta_1_2 - Version 1.2 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.2 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Various spelling corrections + +=item * + +Include list of valid licenses from L<Module::Build> 0.2611 rather than +linking to the module. + +=back + +=head1 SYNOPSIS + + --- #YAML:1.0 + name: Module-Build + abstract: Build and install Perl modules + version: 0.20 + author: + - Ken Williams <kwilliams@cpan.org> + license: perl + distribution_type: module + requires: + Config: 0 + Cwd: 0 + Data::Dumper: 0 + ExtUtils::Install: 0 + File::Basename: 0 + File::Compare: 0 + File::Copy: 0 + File::Find: 0 + File::Path: 0 + File::Spec: 0 + IO::File: 0 + perl: 5.005_03 + recommends: + Archive::Tar: 1.00 + ExtUtils::Install: 0.3 + ExtUtils::ParseXS: 2.02 + Pod::Text: 0 + YAML: 0.35 + build_requires: + Test: 0 + urls: + license: http://dev.perl.org/licenses/ + meta-spec: + version: 1.2 + url: http://module-build.sourceforge.net/META-spec-v1.2.html + generated_by: Module::Build version 0.20 + +=head1 DESCRIPTION + +This document describes version 1.2 of the F<META.yml> specification. + +The F<META.yml> file describes important properties of contributed +Perl distributions such as the ones found on CPAN. It is typically +created by tools like Module::Build, Module::Install, and +ExtUtils::MakeMaker. + +The fields in the F<META.yml> file are meant to be helpful for people +maintaining module collections (like CPAN), for people writing +installation tools (like CPAN.pm or CPANPLUS), or just for people who +want to know some stuff about a distribution before downloading it and +starting to install it. + +I<Note: The latest stable version of this specification can always be +found at L<http://module-build.sourceforge.net/META-spec-current.html>, +and the latest development version (which may include things that +won't make it into the stable version can always be found at +L<http://module-build.sourceforge.net/META-spec-blead.html>.> + +=head1 FORMAT + +F<META.yml> files are written in the YAML format (see +L<http://www.yaml.org/>). + +See the following links to learn why we chose YAML instead of, say, +XML or Data::Dumper: + +=over 4 + +=item * + +Module::Build design plans + +L<http://nntp.x.perl.org/group/perl.makemaker/406> + +=item * + +Not keen on YAML + +L<http://nntp.x.perl.org/group/perl.module-authors/1353> + +=item * + +META Concerns + +L<http://nntp.x.perl.org/group/perl.module-authors/1385> + +=back + +=head1 TERMINOLOGY + +=over 4 + +=item distribution + +This is the primary object described by the F<META.yml> +specification. In the context of this document it usually refers to a +collection of modules, scripts, and/or documents that are distributed +for other developers to use. + +=item module + +This refers to a reusable library of code typically contained in a +single file. Currently, we primarily talk of perl modules, but this +specification should be open enough to apply to other languages as +well (ex. python, ruby). + +=back + +=head1 VERSION SPECIFICATIONS + +Some fields require a version specification (ex. L<"requires">, +L<"recommends">, L<"build_requires">, etc.). This section details the +version specifications that are currently supported. + +If a single version is listed, then that version is considered to be +the minimum version supported. + +If 0 is given as the version number, then any version is supported. + +Additionally, for more complicated requirements, the specification +supports a list of versions, each of which may be optionally preceded +by a relational operator. + +Supported operators include E<lt> (less than), E<lt>= (less than or +equal), E<gt> (greater than), E<gt>= (greater than or equal), == (equal), and != +(not equal). + +If a list is given then it is evaluated from left to right so that any +specifications in the list that conflict with a previous specification +are overridden by the later. + +Examples: + + >= 1.2, != 1.5, < 2.0 + +Any version from version 1.2 onward, except version 1.5, that also +precedes version 2.0. + +=head1 HEADER + +The first line of a F<META.yml> file should be a valid YAML document +header like C<"--- #YAML:1.0">. + +=head1 FIELDS + +The rest of the F<META.yml> file is one big YAML mapping whose keys +are described here. + +=head2 meta-spec + +Example: + + meta-spec: + version: 1.2 + url: http://module-build.sourceforge.net/META-spec-v1.2.html + +(Spec 1.1) [required] {URL} This field indicates the location of the +version of the META.yml specification used. + +=head2 name + +Example: + + name: Module-Build + +(Spec 1.0) [required] {string} The name of the distribution which is often +created by taking the "main module" in the distribution and changing +"::" to "-". Sometimes it's completely different, however, as in the +case of the libwww-perl distribution (see +L<http://search.cpan.org/author/GAAS/libwww-perl/>). + +=head2 version + +Example: + + version: 0.20 + +(Spec 1.0) [required] {version} The version of the distribution to which the +F<META.yml> file refers. + +=head2 abstract + +Example: + + abstract: Build and install Perl modules. + +(Spec 1.1) [required] {string} A short description of the purpose of the +distribution. + +=head2 author + +Example: + + author: + - Ken Williams <kwilliams@cpan.org> + +(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the +distribution. The preferred form is author-name <email-address>. + +=head2 license + +Example: + + license: perl + +(Spec 1.0) [required] {string} The license under which this distribution may be +used and redistributed. + +Must be one of the following licenses: + +=over 4 + +=item perl + +The distribution may be copied and redistributed under the same terms as perl +itself (this is by far the most common licensing option for modules on CPAN). +This is a dual license, in which the user may choose between either the GPL or +the Artistic license. + +=item gpl + +The distribution is distributed under the terms of the Gnu General Public +License (L<http://www.opensource.org/licenses/gpl-license.php>). + +=item lgpl + +The distribution is distributed under the terms of the Gnu Lesser General +Public License (L<http://www.opensource.org/licenses/lgpl-license.php>). + +=item artistic + +The distribution is licensed under the Artistic License, as specified by the +Artistic file in the standard perl distribution. + +=item bsd + +The distribution is licensed under the BSD License +(L<http://www.opensource.org/licenses/bsd-license.php>). + +=item open_source + +The distribution is licensed under some other Open Source Initiative-approved +license listed at L<http://www.opensource.org/licenses/>. + +=item unrestricted + +The distribution is licensed under a license that is B<not> approved by +L<www.opensource.org|http://www.opensource.org> but that allows distribution +without restrictions. + +=item restrictive + +The distribution may not be redistributed without special permission from the +author and/or copyright holder. + +=back + +=head2 distribution_type + +Example: + + distribution_type: module + +(Spec 1.0) [optional] {string} What kind of stuff is contained in this +distribution. Most things on CPAN are C<module>s (which can also mean +a collection of modules), but some things are C<script>s. + +Unfortunately this field is basically meaningless, since many +distributions are hybrids of several kinds of things, or some new +thing, or subjectively different in focus depending on who's using +them. Tools like Module::Build and MakeMaker will likely stop +generating this field. + +=head2 requires + +Example: + + requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution requires for proper operation. The keys are the module +names, and the values are version specifications as described in +L<Module::Build> for the "requires" parameter. + +=head2 recommends + +Example: + + recommends: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution recommends for enhanced operation. + +I<ALTERNATIVE: It may be desirable to present to the user which +features depend on which modules so they can make an informed +decision about which recommended modules to install.> + +Example: + + optional_features: + - foo: + description: Provides the ability to blah. + requires: + Data::Dumper: 0 + File::Find: 1.03 + - bar: + description: This feature is not available on this platform. + excludes_os: MSWin32 + +I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features +which are made available when its requirements are met. For each +feature a description is provided along with any of L<"requires">, +L<"build_requires">, L<"conflicts">, L<"requires_packages">, +L<"requires_os">, and L<"excludes_os"> which have the same meaning in +this subcontext as described elsewhere in this document.> + +=head2 build_requires + +Example: + + build_requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules +required for building and/or testing of this distribution. These +dependencies are not required after the module is installed. + +=head2 conflicts + +Example: + + conflicts: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that +cannot be installed while this distribution is installed. This is a +pretty uncommon situation. + +=head2 dynamic_config + +Example: + + dynamic_config: 0 + +(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> +or F<Makefile.PL> (or similar) must be executed when building this +distribution, or whether it can be built, tested and installed solely +from consulting its +metadata file. The main reason to set this to a true value if that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently Module::Build doesn't actually do anything with this flag +- it's probably going to be up to higher-level tools like CPAN +to do something useful with it. It can potentially bring lots of +security, packaging, and convenience improvements. + +If this field is omitted, it defaults to 1 (true). + +=head2 private + +I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to +L</"no_index">. See below. + +=head2 provides + +Example: + + provides: + Foo::Bar: + file: lib/Foo/Bar.pm + version: 0.27_02 + Foo::Bar::Blah: + file: lib/Foo/Bar/Blah.pm + Foo::Bar::Baz: + file: lib/Foo/Bar/Baz.pm + version: 0.3 + +(Spec 1.1) [optional] {map} A YAML mapping that describes all packages +provided by this distribution. This information can be (and, in some +cases, is) used by distribution and automation mechanisms like PAUSE, +CPAN, and search.cpan.org to build indexes saying in which +distribution various packages can be found. + +When using tools like C<Module::Build> that can generate the +C<provides> mapping for your distribution automatically, make sure you +examine what it generates to make sure it makes sense - indexers will +usually trust the C<provides> field if it's present, rather than +scanning through the distribution files themselves to figure out +packages and versions. This is a good thing, because it means you can +use the C<provides> field to tell the indexers precisely what you want +indexed about your distribution, rather than relying on them to +essentially guess what you want indexed. + +=head2 no_index + +Example: + + no_index: + file: + - My/Module.pm + dir: + - My/Private + package: + - My::Module::Stuff + namespace: + - My::Module::Stuff + +(Spec 1.1) [optional] {map} A YAML mapping that describes any files, +directories, packages, and namespaces that are private +(i.e. implementation artifacts) that are not of interest to searching +and indexing tools. This is useful when no C<provides> field is +present. + +I<(Note: I'm not actually sure who looks at this field, or exactly +what they do with it. This spec could be off in some way from actual +usage.)> + +=head3 file + +(Spec 1.1) [optional] Exclude any listed file(s). + +=head3 dir + +(Spec 1.1) [optional] Exclude anything below the listed +directory(ies). + +=head3 package + +(Spec 1.1) [optional] Exclude the listed package(s). + +=head3 namespace + +(Spec 1.1) [optional] Excludes anything below the listed namespace(s), +but I<not> the listed namespace(s) its self. + +=head2 keywords + +Example: + + keywords: + - make + - build + - install + +(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe +this distribution. + +=head2 resources + +Example: + + resources: + license: http://dev.perl.org/licenses/ + homepage: http://sourceforge.net/projects/module-build + bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build + MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general + +(Spec 1.1) [optional] {map} A mapping of any URL resources related to +this distribution. All-lower-case keys, such as C<homepage>, +C<license>, and C<bugtracker>, are reserved by this specification, as +they have "official" meanings defined here in this specification. If +you'd like to add your own "special" entries (like the "MailingList" +entry above), use at least one upper-case letter. + +The current set of official keys is: + +=over 2 + +=item homepage + +The official home of this project on the web. + +=item license + +An URL for an official statement of this distribution's license. + +=item bugtracker + +An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. + +=back + + +=head2 generated_by + +Example: + + generated_by: Module::Build version 0.20 + +(Spec 1.0) [required] {string} Indicates the tool that was used to create this +F<META.yml> file. It's good form to include both the name of the tool +and its version, but this field is essentially opaque, at least for +the moment. If F<META.yml> was generated by hand, it is suggested that +the author be specified here. + +[Note: My F<meta_stats.pl> script which I use to gather statistics +regarding F<META.yml> usage prefers the form listed above, i.e. it +splits on /\s+version\s+/ taking the first field as the name of the +tool that generated the file and the second field as version of that +tool. RWS] + +=head1 SEE ALSO + +CPAN, L<http://www.cpan.org/> + +CPAN.pm, L<http://search.cpan.org/author/ANDK/CPAN/> + +CPANPLUS, L<http://search.cpan.org/author/KANE/CPANPLUS/> + +Data::Dumper, L<http://search.cpan.org/author/ILYAM/Data-Dumper/> + +ExtUtils::MakeMaker, L<http://search.cpan.org/author/MSCHWERN/ExtUtils-MakeMaker/> + +Module::Build, L<http://search.cpan.org/author/KWILLIAMS/Module-Build/> + +Module::Install, L<http://search.cpan.org/author/KWILLIAMS/Module-Install/> + +XML, L<http://www.w3.org/XML/> + +YAML, L<http://www.yaml.org/> + +=head1 HISTORY + +=over 4 + +=item March 14, 2003 (Pi day) + +=over 2 + +=item * + +Created version 1.0 of this document. + +=back + +=item May 8, 2003 + +=over 2 + +=item * + +Added the L</"dynamic_config"> field, which was missing from the initial +version. + +=back + +=item November 13, 2003 + +=over 2 + +=item * + +Added more YAML rationale articles. + +=item * + +Fixed existing link to YAML discussion thread to point to new +L<http://nntp.x.perl.org/group/> site. + +=item * + +Added and deprecated the L<"private"> field. + +=item * + +Added L<"abstract">, L<"configure">, L<"requires_packages">, +L<"requires_os">, L<"excludes_os">, and L<"no_index"> fields. + +=item * + +Bumped version. + +=back + +=item November 16, 2003 + +=over 2 + +=item * + +Added L<"generation">, L<"authored_by"> fields. + +=item * + +Add alternative proposal to the L<"recommends"> field. + +=item * + +Add proposal for a L<"requires_build_tools"> field. + +=back + +=item December 9, 2003 + +=over 2 + +=item * + +Added link to latest version of this specification on CPAN. + +=item * + +Added section L<"VERSION SPECIFICATIONS">. + +=item * + +Chang name from Module::Build::META-spec to CPAN::META::Specification. + +=item * + +Add proposal for L<"auto_regenerate"> field. + +=back + +=item December 15, 2003 + +=over 2 + +=item * + +Add L<"index"> field as a compliment to L<"no_index"> + +=item * + +Add L<"keywords"> field as a means to aid searching distributions. + +=item * + +Add L<"TERMINOLOGY"> section to explain certain terms that may be +ambiguous. + +=back + +=item July 26, 2005 + +=over 2 + +=item * + +Removed a bunch of items (generation, requires_build_tools, +requires_packages, configure, requires_os, excludes_os, +auto_regenerate) that have never actually been supported, but were +more like records of brainstorming. + +=item * + +Changed C<authored_by> to C<author>, since that's always been what +it's actually called in actual F<META.yml> files. + +=item * + +Added the "==" operator to the list of supported version-checking +operators. + +=item * + +Noted that the C<distribution_type> field is basically meaningless, +and shouldn't really be used. + +=item * + +Clarified C<dynamic_config> a bit. + +=back + +=item August 23, 2005 + +=over 2 + +=item * + +Removed the name C<CPAN::META::Specification>, since that implies a +module that doesn't actually exist. + +=back + +=back diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_3.pod b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_3.pod new file mode 100644 index 00000000000..deff28dc828 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_3.pod @@ -0,0 +1,734 @@ +=for :stopwords MailingList PODs RWS subcontext + +=head1 NAME + +CPAN::Meta::History::Meta_1_3 - Version 1.3 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.3 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Various spelling corrections + +=item * + +Include list of valid licenses from L<Module::Build> 0.2805 rather than +linking to the module. + +=back + +=head1 SYNOPSIS + + --- #YAML:1.0 + name: Module-Build + abstract: Build and install Perl modules + version: 0.20 + author: + - Ken Williams <kwilliams@cpan.org> + license: perl + distribution_type: module + requires: + Config: 0 + Cwd: 0 + Data::Dumper: 0 + ExtUtils::Install: 0 + File::Basename: 0 + File::Compare: 0 + File::Copy: 0 + File::Find: 0 + File::Path: 0 + File::Spec: 0 + IO::File: 0 + perl: 5.005_03 + recommends: + Archive::Tar: 1.00 + ExtUtils::Install: 0.3 + ExtUtils::ParseXS: 2.02 + Pod::Text: 0 + YAML: 0.35 + build_requires: + Test: 0 + urls: + license: http://dev.perl.org/licenses/ + meta-spec: + version: 1.3 + url: http://module-build.sourceforge.net/META-spec-v1.3.html + generated_by: Module::Build version 0.20 + +=head1 DESCRIPTION + +This document describes version 1.3 of the F<META.yml> specification. + +The F<META.yml> file describes important properties of contributed +Perl distributions such as the ones found on CPAN. It is typically +created by tools like Module::Build, Module::Install, and +ExtUtils::MakeMaker. + +The fields in the F<META.yml> file are meant to be helpful for people +maintaining module collections (like CPAN), for people writing +installation tools (like CPAN.pm or CPANPLUS), or just for people who +want to know some stuff about a distribution before downloading it and +starting to install it. + +I<Note: The latest stable version of this specification can always be +found at L<http://module-build.sourceforge.net/META-spec-current.html>, +and the latest development version (which may include things that +won't make it into the stable version) can always be found at +L<http://module-build.sourceforge.net/META-spec-blead.html>.> + +=head1 FORMAT + +F<META.yml> files are written in the YAML format (see +L<http://www.yaml.org/>). + +See the following links to learn why we chose YAML instead of, say, +XML or Data::Dumper: + +=over 4 + +=item Module::Build design plans + +L<http://nntp.x.perl.org/group/perl.makemaker/406> + +=item Not keen on YAML + +L<http://nntp.x.perl.org/group/perl.module-authors/1353> + +=item META Concerns + +L<http://nntp.x.perl.org/group/perl.module-authors/1385> + +=back + +=head1 TERMINOLOGY + +=over 4 + +=item distribution + +This is the primary object described by the F<META.yml> +specification. In the context of this document it usually refers to a +collection of modules, scripts, and/or documents that are distributed +together for other developers to use. Examples of distributions are +C<Class-Container>, C<libwww-perl>, or C<DBI>. + +=item module + +This refers to a reusable library of code typically contained in a +single file. Currently, we primarily talk of perl modules, but this +specification should be open enough to apply to other languages as +well (ex. python, ruby). Examples of modules are C<Class::Container>, +C<LWP::Simple>, or C<DBD::File>. + +=back + +=head1 HEADER + +The first line of a F<META.yml> file should be a valid YAML document +header like C<"--- #YAML:1.0">. + +=head1 FIELDS + +The rest of the F<META.yml> file is one big YAML mapping whose keys +are described here. + +=head2 meta-spec + +Example: + + meta-spec: + version: 1.3 + url: http://module-build.sourceforge.net/META-spec-v1.3.html + +(Spec 1.1) [required] {URL} This field indicates the location of the +version of the META.yml specification used. + +=head2 name + +Example: + + name: Module-Build + +(Spec 1.0) [required] {string} The name of the distribution which is often +created by taking the "main module" in the distribution and changing +"::" to "-". Sometimes it's completely different, however, as in the +case of the libwww-perl distribution (see +L<http://search.cpan.org/dist/libwww-perl/>). + +=head2 version + +Example: + + version: 0.20 + +(Spec 1.0) [required] {version} The version of the distribution to which the +F<META.yml> file refers. + +=head2 abstract + +Example: + + abstract: Build and install Perl modules. + +(Spec 1.1) [required] {string} A short description of the purpose of the +distribution. + +=head2 author + +Example: + + author: + - Ken Williams <kwilliams@cpan.org> + +(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the +distribution. The preferred form is author-name <email-address>. + +=head2 license + +Example: + + license: perl + +(Spec 1.0) [required] {string} The license under which this distribution may be +used and redistributed. + +Must be one of the following licenses: + +=over 4 + +=item apache + +The distribution is licensed under the Apache Software License +(L<http://opensource.org/licenses/apachepl.php>). + +=item artistic + +The distribution is licensed under the Artistic License, as specified by the +Artistic file in the standard perl distribution. + +=item bsd + +The distribution is licensed under the BSD License +(L<http://www.opensource.org/licenses/bsd-license.php>). + +=item gpl + +The distribution is licensed under the terms of the Gnu General Public License +(L<http://www.opensource.org/licenses/gpl-license.php>). + +=item lgpl + +The distribution is licensed under the terms of the Gnu Lesser General Public +License (L<http://www.opensource.org/licenses/lgpl-license.php>). + +=item mit + +The distribution is licensed under the MIT License +(L<http://opensource.org/licenses/mit-license.php>). + +=item mozilla + +The distribution is licensed under the Mozilla Public License. +(L<http://opensource.org/licenses/mozilla1.0.php> or +L<http://opensource.org/licenses/mozilla1.1.php>) + +=item open_source + +The distribution is licensed under some other Open Source Initiative-approved +license listed at L<http://www.opensource.org/licenses/>. + +=item perl + +The distribution may be copied and redistributed under the same terms as perl +itself (this is by far the most common licensing option for modules on CPAN). +This is a dual license, in which the user may choose between either the GPL or +the Artistic license. + +=item restrictive + +The distribution may not be redistributed without special permission from the +author and/or copyright holder. + +=item unrestricted + +The distribution is licensed under a license that is not approved by +L<www.opensource.org|http://www.opensource.org/> but that allows distribution +without restrictions. + +=back + +=head2 distribution_type + +Example: + + distribution_type: module + +(Spec 1.0) [optional] {string} What kind of stuff is contained in this +distribution. Most things on CPAN are C<module>s (which can also mean +a collection of modules), but some things are C<script>s. + +Unfortunately this field is basically meaningless, since many +distributions are hybrids of several kinds of things, or some new +thing, or subjectively different in focus depending on who's using +them. Tools like Module::Build and MakeMaker will likely stop +generating this field. + +=head2 requires + +Example: + + requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution requires for proper operation. The keys are the module +names, and the values are version specifications as described in +L<VERSION SPECIFICATIONS>. + +=head2 recommends + +Example: + + recommends: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules +this distribution recommends for enhanced operation. The keys are the +module names, and the values are version specifications as described +in L<VERSION SPECIFICATIONS>. + + + +I<ALTERNATIVE: It may be desirable to present to the user which +features depend on which modules so they can make an informed decision +about which recommended modules to install.> + +Example: + + optional_features: + - foo: + description: Provides the ability to blah. + requires: + Data::Dumper: 0 + File::Find: 1.03 + - bar: + description: This feature is not available on this platform. + excludes_os: MSWin32 + +I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features +which are made available when its requirements are met. For each +feature a description is provided along with any of L<"requires">, +L<"build_requires">, L<"conflicts">, L<"requires_packages">, +L<"requires_os">, and L<"excludes_os"> which have the same meaning in +this subcontext as described elsewhere in this document.> + +=head2 build_requires + +Example: + + build_requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules +required for building and/or testing of this distribution. The keys +are the module names, and the values are version specifications as +described in L<VERSION SPECIFICATIONS>. These dependencies are not +required after the module is installed. + +=head2 conflicts + +Example: + + conflicts: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that +cannot be installed while this distribution is installed. This is a +pretty uncommon situation. The keys for C<conflicts> are the module +names, and the values are version specifications as described in +L<VERSION SPECIFICATIONS>. + + +=head2 dynamic_config + +Example: + + dynamic_config: 0 + +(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> +or F<Makefile.PL> (or similar) must be executed when building this +distribution, or whether it can be built, tested and installed solely +from consulting its +metadata file. The main reason to set this to a true value is that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently Module::Build doesn't actually do anything with this flag +- it's probably going to be up to higher-level tools like CPAN +to do something useful with it. It can potentially bring lots of +security, packaging, and convenience improvements. + +If this field is omitted, it defaults to 1 (true). + +=head2 private + +I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to +L</"no_index">. See below. + +=head2 provides + +Example: + + provides: + Foo::Bar: + file: lib/Foo/Bar.pm + version: 0.27_02 + Foo::Bar::Blah: + file: lib/Foo/Bar/Blah.pm + Foo::Bar::Baz: + file: lib/Foo/Bar/Baz.pm + version: 0.3 + +(Spec 1.1) [optional] {map} A YAML mapping that describes all packages +provided by this distribution. This information can be (and, in some +cases, is) used by distribution and automation mechanisms like PAUSE, +CPAN, and search.cpan.org to build indexes saying in which +distribution various packages can be found. + +When using tools like C<Module::Build> that can generate the +C<provides> mapping for your distribution automatically, make sure you +examine what it generates to make sure it makes sense - indexers will +usually trust the C<provides> field if it's present, rather than +scanning through the distribution files themselves to figure out +packages and versions. This is a good thing, because it means you can +use the C<provides> field to tell the indexers precisely what you want +indexed about your distribution, rather than relying on them to +essentially guess what you want indexed. + +=head2 no_index + +Example: + + no_index: + file: + - My/Module.pm + directory: + - My/Private + package: + - My::Module::Stuff + namespace: + - My::Module::Stuff + +(Spec 1.1) [optional] {map} A YAML mapping that describes any files, +directories, packages, and namespaces that are private +(i.e. implementation artifacts) that are not of interest to searching +and indexing tools. This is useful when no C<provides> field is +present. + +For example, C<search.cpan.org> excludes items listed in C<no_index> +when searching for POD, meaning files in these directories will not +converted to HTML and made public - which is useful if you have +example or test PODs that you don't want the search engine to go +through. + +=head3 file + +(Spec 1.1) [optional] Exclude any listed file(s). + +=head3 directory + +(Spec 1.1) [optional] Exclude anything below the listed +directory(ies). + +[Note: previous editions of the spec had C<dir> instead of +C<directory>, but I think MakeMaker and various users started using +C<directory>, so in deference we switched to that.] + +=head3 package + +(Spec 1.1) [optional] Exclude the listed package(s). + +=head3 namespace + +(Spec 1.1) [optional] Excludes anything below the listed namespace(s), +but I<not> the listed namespace(s) its self. + +=head2 keywords + +Example: + + keywords: + - make + - build + - install + +(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe +this distribution. + +=head2 resources + +Example: + + resources: + license: http://dev.perl.org/licenses/ + homepage: http://sourceforge.net/projects/module-build + bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build + repository: http://sourceforge.net/cvs/?group_id=45731 + MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general + +(Spec 1.1) [optional] {map} A mapping of any URL resources related to +this distribution. All-lower-case keys, such as C<homepage>, +C<license>, and C<bugtracker>, are reserved by this specification, as +they have "official" meanings defined here in this specification. If +you'd like to add your own "special" entries (like the "MailingList" +entry above), use at least one upper-case letter. + +The current set of official keys is: + +=over 2 + +=item homepage + +The official home of this project on the web. + +=item license + +An URL for an official statement of this distribution's license. + +=item bugtracker + +An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. + +=back + + +=head2 generated_by + +Example: + + generated_by: Module::Build version 0.20 + +(Spec 1.0) [required] {string} Indicates the tool that was used to create this +F<META.yml> file. It's good form to include both the name of the tool +and its version, but this field is essentially opaque, at least for +the moment. If F<META.yml> was generated by hand, it is suggested that +the author be specified here. + +[Note: My F<meta_stats.pl> script which I use to gather statistics +regarding F<META.yml> usage prefers the form listed above, i.e. it +splits on /\s+version\s+/ taking the first field as the name of the +tool that generated the file and the second field as version of that +tool. RWS] + +=head1 VERSION SPECIFICATIONS + +Some fields require a version specification (ex. L<"requires">, +L<"recommends">, L<"build_requires">, etc.) to indicate the particular +versionZ<>(s) of some other module that may be required as a +prerequisite. This section details the version specification formats +that are currently supported. + +The simplest format for a version specification is just the version +number itself, e.g. C<2.4>. This means that B<at least> version 2.4 +must be present. To indicate that B<any> version of a prerequisite is +okay, even if the prerequisite doesn't define a version at all, use +the version C<0>. + +You may also use the operators E<lt> (less than), E<lt>= (less than or +equal), E<gt> (greater than), E<gt>= (greater than or equal), == +(equal), and != (not equal). For example, the specification C<E<lt> +2.0> means that any version of the prerequisite less than 2.0 is +suitable. + +For more complicated situations, version specifications may be AND-ed +together using commas. The specification C<E<gt>= 1.2, != 1.5, E<lt> +2.0> indicates a version that must be B<at least> 1.2, B<less than> +2.0, and B<not equal to> 1.5. + +=head1 SEE ALSO + +CPAN, L<http://www.cpan.org/> + +CPAN.pm, L<http://search.cpan.org/dist/CPAN/> + +CPANPLUS, L<http://search.cpan.org/dist/CPANPLUS/> + +Data::Dumper, L<http://search.cpan.org/dist/Data-Dumper/> + +ExtUtils::MakeMaker, L<http://search.cpan.org/dist/ExtUtils-MakeMaker/> + +Module::Build, L<http://search.cpan.org/dist/Module-Build/> + +Module::Install, L<http://search.cpan.org/dist/Module-Install/> + +XML, L<http://www.w3.org/XML/> + +YAML, L<http://www.yaml.org/> + +=head1 HISTORY + +=over 4 + +=item March 14, 2003 (Pi day) + +=over 2 + +=item * + +Created version 1.0 of this document. + +=back + +=item May 8, 2003 + +=over 2 + +=item * + +Added the L</"dynamic_config"> field, which was missing from the initial +version. + +=back + +=item November 13, 2003 + +=over 2 + +=item * + +Added more YAML rationale articles. + +=item * + +Fixed existing link to YAML discussion thread to point to new +L<http://nntp.x.perl.org/group/> site. + +=item * + +Added and deprecated the L<"private"> field. + +=item * + +Added L<"abstract">, L<"configure">, L<"requires_packages">, +L<"requires_os">, L<"excludes_os">, and L<"no_index"> fields. + +=item * + +Bumped version. + +=back + +=item November 16, 2003 + +=over 2 + +=item * + +Added L<"generation">, L<"authored_by"> fields. + +=item * + +Add alternative proposal to the L<"recommends"> field. + +=item * + +Add proposal for a L<"requires_build_tools"> field. + +=back + +=item December 9, 2003 + +=over 2 + +=item * + +Added link to latest version of this specification on CPAN. + +=item * + +Added section L<"VERSION SPECIFICATIONS">. + +=item * + +Chang name from Module::Build::META-spec to CPAN::META::Specification. + +=item * + +Add proposal for L<"auto_regenerate"> field. + +=back + +=item December 15, 2003 + +=over 2 + +=item * + +Add L<"index"> field as a compliment to L<"no_index"> + +=item * + +Add L<"keywords"> field as a means to aid searching distributions. + +=item * + +Add L<"TERMINOLOGY"> section to explain certain terms that may be +ambiguous. + +=back + +=item July 26, 2005 + +=over 2 + +=item * + +Removed a bunch of items (generation, requires_build_tools, +requires_packages, configure, requires_os, excludes_os, +auto_regenerate) that have never actually been supported, but were +more like records of brainstorming. + +=item * + +Changed C<authored_by> to C<author>, since that's always been what +it's actually called in actual F<META.yml> files. + +=item * + +Added the "==" operator to the list of supported version-checking +operators. + +=item * + +Noted that the C<distribution_type> field is basically meaningless, +and shouldn't really be used. + +=item * + +Clarified C<dynamic_config> a bit. + +=back + +=item August 23, 2005 + +=over 2 + +=item * + +Removed the name C<CPAN::META::Specification>, since that implies a +module that doesn't actually exist. + +=back + +=back diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_4.pod b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_4.pod new file mode 100644 index 00000000000..a84fb3dd8a6 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/History/Meta_1_4.pod @@ -0,0 +1,787 @@ +=for :stopwords MailingList PODs RWS subcontext + +=head1 NAME + +CPAN::Meta::History::Meta_1_4 - Version 1.4 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.4 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Various spelling corrections + +=item * + +Include list of valid licenses from L<Module::Build> 0.2807 rather than +linking to the module. + +=back + +=head1 SYNOPSIS + + --- #YAML:1.0 + name: Module-Build + abstract: Build and install Perl modules + version: 0.20 + author: + - Ken Williams <kwilliams@cpan.org> + license: perl + distribution_type: module + requires: + Config: 0 + Cwd: 0 + Data::Dumper: 0 + ExtUtils::Install: 0 + File::Basename: 0 + File::Compare: 0 + File::Copy: 0 + File::Find: 0 + File::Path: 0 + File::Spec: 0 + IO::File: 0 + perl: 5.005_03 + recommends: + Archive::Tar: 1.00 + ExtUtils::Install: 0.3 + ExtUtils::ParseXS: 2.02 + Pod::Text: 0 + YAML: 0.35 + build_requires: + Test: 0 + resources: + license: http://dev.perl.org/licenses/ + meta-spec: + version: 1.4 + url: http://module-build.sourceforge.net/META-spec-v1.3.html + generated_by: Module::Build version 0.20 + +=head1 DESCRIPTION + +This document describes version 1.4 of the F<META.yml> specification. + +The F<META.yml> file describes important properties of contributed +Perl distributions such as the ones found on CPAN. It is typically +created by tools like Module::Build, Module::Install, and +ExtUtils::MakeMaker. + +The fields in the F<META.yml> file are meant to be helpful for people +maintaining module collections (like CPAN), for people writing +installation tools (like CPAN.pm or CPANPLUS), or just for people who +want to know some stuff about a distribution before downloading it and +starting to install it. + +I<Note: The latest stable version of this specification can always be +found at L<http://module-build.sourceforge.net/META-spec-current.html>, +and the latest development version (which may include things that +won't make it into the stable version) can always be found at +L<http://module-build.sourceforge.net/META-spec-blead.html>.> + +=begin MAINTAINER + +The master source for the META spec is META-spec.pod. META-spec.html +is built (manually) from META-spec.pod whenever there are changes, and +the two files should generally be checked in together. Ideally it +would happen through a trigger or something, but it doesn't. + +Ken has a cron job that copies the latest bleeding-edge version of the +spec (HTML version) to Sourceforge whenever his laptop is turned on: + + 21 * * * * svn cat http://svn.perl.org/modules/Module-Build/trunk/website/META-spec.html \ + | ssh kwilliams@shell.sourceforge.net \ + 'cat > /home/groups/m/mo/module-build/htdocs/META-spec-blead.html' + +The numbered revisions of the spec at +L<"http://module-build.sourceforge.net/"> are captures of the spec at +opportune moments. A couple of symlinks also exist for convenience: + + -rw-r--r-- 1 kwilliams 24585 Oct 10 17:21 META-spec-blead.html + lrwxrwxrwx 1 kwilliams 19 Jan 19 2007 META-spec-current.html -> META-spec-v1.3.html + lrwxrwxrwx 1 kwilliams 22 Jan 19 2007 META-spec.html -> META-spec-current.html + -rw-r--r-- 1 kwilliams 5830 Jul 25 2005 META-spec-v1.0.html + -rw-r--r-- 1 kwilliams 7847 Jul 25 2005 META-spec-v1.1.html + -rw-r--r-- 1 kwilliams 22635 Aug 23 2005 META-spec-v1.2.html + -rw-r--r-- 1 kwilliams 24086 Nov 4 2006 META-spec-v1.3.html + +=end MAINTAINER + + +=head1 FORMAT + +F<META.yml> files are written in the YAML format (see +L<http://www.yaml.org/>). + +See the following links to learn why we chose YAML instead of, say, +XML or Data::Dumper: + +=over 4 + +=item Module::Build design plans + +L<http://nntp.x.perl.org/group/perl.makemaker/406> + +=item Not keen on YAML + +L<http://nntp.x.perl.org/group/perl.module-authors/1353> + +=item META Concerns + +L<http://nntp.x.perl.org/group/perl.module-authors/1385> + +=back + +=head1 TERMINOLOGY + +=over 4 + +=item distribution + +This is the primary object described by the F<META.yml> +specification. In the context of this document it usually refers to a +collection of modules, scripts, and/or documents that are distributed +together for other developers to use. Examples of distributions are +C<Class-Container>, C<libwww-perl>, or C<DBI>. + +=item module + +This refers to a reusable library of code typically contained in a +single file. Currently, we primarily talk of perl modules, but this +specification should be open enough to apply to other languages as +well (ex. python, ruby). Examples of modules are C<Class::Container>, +C<LWP::Simple>, or C<DBD::File>. + +=back + +=head1 HEADER + +The first line of a F<META.yml> file should be a valid YAML document +header like C<"--- #YAML:1.0">. + +=head1 FIELDS + +The rest of the F<META.yml> file is one big YAML mapping whose keys +are described here. + +=head2 meta-spec + +Example: + + meta-spec: + version: 1.4 + url: http://module-build.sourceforge.net/META-spec-v1.3.html + +(Spec 1.1) [required] {URL} This field indicates the location of the +version of the META.yml specification used. + +=head2 name + +Example: + + name: Module-Build + +(Spec 1.0) [required] {string} The name of the distribution which is often +created by taking the "main module" in the distribution and changing +"::" to "-". Sometimes it's completely different, however, as in the +case of the libwww-perl distribution (see +L<http://search.cpan.org/dist/libwww-perl/>). + +=head2 version + +Example: + + version: 0.20 + +(Spec 1.0) [required] {version} The version of the distribution to which the +F<META.yml> file refers. + +=head2 abstract + +Example: + + abstract: Build and install Perl modules. + +(Spec 1.1) [required] {string} A short description of the purpose of the +distribution. + +=head2 author + +Example: + + author: + - Ken Williams <kwilliams@cpan.org> + +(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the +distribution. The preferred form is author-name <email-address>. + +=head2 license + +Example: + + license: perl + +(Spec 1.0) [required] {string} The license under which this +distribution may be used and redistributed. + +Must be one of the following licenses: + +=over 4 + +=item apache + +The distribution is licensed under the Apache Software License +(L<http://opensource.org/licenses/apachepl.php>). + +=item artistic + +The distribution is licensed under the Artistic License, as specified by the +Artistic file in the standard perl distribution. + +=item bsd + +The distribution is licensed under the BSD License +(L<http://www.opensource.org/licenses/bsd-license.php>). + +=item gpl + +The distribution is licensed under the terms of the Gnu General Public License +(L<http://www.opensource.org/licenses/gpl-license.php>). + +=item lgpl + +The distribution is licensed under the terms of the Gnu Lesser General Public +License (L<http://www.opensource.org/licenses/lgpl-license.php>). + +=item mit + +The distribution is licensed under the MIT License +(L<http://opensource.org/licenses/mit-license.php>). + +=item mozilla + +The distribution is licensed under the Mozilla Public License. +(L<http://opensource.org/licenses/mozilla1.0.php> or +L<http://opensource.org/licenses/mozilla1.1.php>) + +=item open_source + +The distribution is licensed under some other Open Source Initiative-approved +license listed at L<http://www.opensource.org/licenses/>. + +=item perl + +The distribution may be copied and redistributed under the same terms as perl +itself (this is by far the most common licensing option for modules on CPAN). +This is a dual license, in which the user may choose between either the GPL or +the Artistic license. + +=item restrictive + +The distribution may not be redistributed without special permission from the +author and/or copyright holder. + +=item unrestricted + +The distribution is licensed under a license that is not approved by +L<www.opensource.org|http://www.opensource.org/> but that allows distribution +without restrictions. + +=back + +=head2 distribution_type + +Example: + + distribution_type: module + +(Spec 1.0) [optional] {string} What kind of stuff is contained in this +distribution. Most things on CPAN are C<module>s (which can also mean +a collection of modules), but some things are C<script>s. + +Unfortunately this field is basically meaningless, since many +distributions are hybrids of several kinds of things, or some new +thing, or subjectively different in focus depending on who's using +them. Tools like Module::Build and MakeMaker will likely stop +generating this field. + +=head2 requires + +Example: + + requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl +prerequisites this distribution requires for proper operation. The +keys are the names of the prerequisites (module names or 'perl'), and +the values are version specifications as described in L<VERSION +SPECIFICATIONS>. + +=head2 recommends + +Example: + + recommends: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl +prerequisites this distribution recommends for enhanced operation. +The keys are the names of the prerequisites (module names or 'perl'), +and the values are version specifications as described in L<VERSION +SPECIFICATIONS>. + + + +I<ALTERNATIVE: It may be desirable to present to the user which +features depend on which modules so they can make an informed decision +about which recommended modules to install.> + +Example: + + optional_features: + foo: + description: Provides the ability to blah. + requires: + Data::Dumper: 0 + File::Find: 1.03 + +I<(Spec 1.1) [optional] {map} A YAML mapping of names for optional features +which are made available when its requirements are met. For each +feature a description is provided along with any of L<"requires">, +L<"build_requires">, and L<"conflicts">, which have the same meaning in +this subcontext as described elsewhere in this document.> + +=head2 build_requires + +Example: + + build_requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl +prerequisites required for building and/or testing of this +distribution. The keys are the names of the prerequisites (module +names or 'perl'), and the values are version specifications as +described in L<VERSION SPECIFICATIONS>. These dependencies are not +required after the distribution is installed. + +=head2 configure_requires + +Example: + + configure_requires: + Module::Build: 0.2809 + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.4) [optional] {map} A YAML mapping indicating the Perl prerequisites +required before configuring this distribution. The keys are the +names of the prerequisites (module names or 'perl'), and the values are version specifications as described +in L<VERSION SPECIFICATIONS>. These dependencies are not required +after the distribution is installed. + +=head2 conflicts + +Example: + + conflicts: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating any items that +cannot be installed while this distribution is installed. This is a +pretty uncommon situation. The keys for C<conflicts> are the item +names (module names or 'perl'), and the values are version +specifications as described in L<VERSION SPECIFICATIONS>. + + +=head2 dynamic_config + +Example: + + dynamic_config: 0 + +(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> +or F<Makefile.PL> (or similar) must be executed when building this +distribution, or whether it can be built, tested and installed solely +from consulting its +metadata file. The main reason to set this to a true value is that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently Module::Build doesn't actually do anything with this flag +- it's probably going to be up to higher-level tools like CPAN +to do something useful with it. It can potentially bring lots of +security, packaging, and convenience improvements. + +If this field is omitted, it defaults to 1 (true). + +=head2 private + +I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to +L</"no_index">. See below. + +=head2 provides + +Example: + + provides: + Foo::Bar: + file: lib/Foo/Bar.pm + version: 0.27_02 + Foo::Bar::Blah: + file: lib/Foo/Bar/Blah.pm + Foo::Bar::Baz: + file: lib/Foo/Bar/Baz.pm + version: 0.3 + +(Spec 1.1) [optional] {map} A YAML mapping that describes all packages +provided by this distribution. This information can be (and, in some +cases, is) used by distribution and automation mechanisms like PAUSE, +CPAN, and search.cpan.org to build indexes saying in which +distribution various packages can be found. + +When using tools like C<Module::Build> that can generate the +C<provides> mapping for your distribution automatically, make sure you +examine what it generates to make sure it makes sense - indexers will +usually trust the C<provides> field if it's present, rather than +scanning through the distribution files themselves to figure out +packages and versions. This is a good thing, because it means you can +use the C<provides> field to tell the indexers precisely what you want +indexed about your distribution, rather than relying on them to +essentially guess what you want indexed. + +=head2 no_index + +Example: + + no_index: + file: + - My/Module.pm + directory: + - My/Private + package: + - My::Module::Stuff + namespace: + - My::Module::Stuff + +(Spec 1.1) [optional] {map} A YAML mapping that describes any files, +directories, packages, and namespaces that are private +(i.e. implementation artifacts) that are not of interest to searching +and indexing tools. This is useful when no C<provides> field is +present. + +For example, C<search.cpan.org> excludes items listed in C<no_index> +when searching for POD, meaning files in these directories will not +converted to HTML and made public - which is useful if you have +example or test PODs that you don't want the search engine to go +through. + +=head3 file + +(Spec 1.1) [optional] Exclude any listed file(s). + +=head3 directory + +(Spec 1.1) [optional] Exclude anything below the listed +directory(ies). + +[Note: previous editions of the spec had C<dir> instead of +C<directory>, but I think MakeMaker and various users started using +C<directory>, so in deference we switched to that.] + +=head3 package + +(Spec 1.1) [optional] Exclude the listed package(s). + +=head3 namespace + +(Spec 1.1) [optional] Excludes anything below the listed namespace(s), +but I<not> the listed namespace(s) its self. + +=head2 keywords + +Example: + + keywords: + - make + - build + - install + +(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe +this distribution. + +=head2 resources + +Example: + + resources: + license: http://dev.perl.org/licenses/ + homepage: http://sourceforge.net/projects/module-build + bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build + repository: http://sourceforge.net/cvs/?group_id=45731 + MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general + +(Spec 1.1) [optional] {map} A mapping of any URL resources related to +this distribution. All-lower-case keys, such as C<homepage>, +C<license>, and C<bugtracker>, are reserved by this specification, as +they have "official" meanings defined here in this specification. If +you'd like to add your own "special" entries (like the "MailingList" +entry above), use at least one upper-case letter. + +The current set of official keys is: + +=over 2 + +=item homepage + +The official home of this project on the web. + +=item license + +An URL for an official statement of this distribution's license. + +=item bugtracker + +An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. + +=back + + +=head2 generated_by + +Example: + + generated_by: Module::Build version 0.20 + +(Spec 1.0) [required] {string} Indicates the tool that was used to create this +F<META.yml> file. It's good form to include both the name of the tool +and its version, but this field is essentially opaque, at least for +the moment. If F<META.yml> was generated by hand, it is suggested that +the author be specified here. + +[Note: My F<meta_stats.pl> script which I use to gather statistics +regarding F<META.yml> usage prefers the form listed above, i.e. it +splits on /\s+version\s+/ taking the first field as the name of the +tool that generated the file and the second field as version of that +tool. RWS] + +=head1 VERSION SPECIFICATIONS + +Some fields require a version specification (ex. L<"requires">, +L<"recommends">, L<"build_requires">, etc.) to indicate the particular +versionZ<>(s) of some other module that may be required as a +prerequisite. This section details the version specification formats +that are currently supported. + +The simplest format for a version specification is just the version +number itself, e.g. C<2.4>. This means that B<at least> version 2.4 +must be present. To indicate that B<any> version of a prerequisite is +okay, even if the prerequisite doesn't define a version at all, use +the version C<0>. + +You may also use the operators E<lt> (less than), E<lt>= (less than or +equal), E<gt> (greater than), E<gt>= (greater than or equal), == +(equal), and != (not equal). For example, the specification C<E<lt> +2.0> means that any version of the prerequisite less than 2.0 is +suitable. + +For more complicated situations, version specifications may be AND-ed +together using commas. The specification C<E<gt>= 1.2, != 1.5, E<lt> +2.0> indicates a version that must be B<at least> 1.2, B<less than> +2.0, and B<not equal to> 1.5. + +=head1 SEE ALSO + +CPAN, L<http://www.cpan.org/> + +CPAN.pm, L<http://search.cpan.org/dist/CPAN/> + +CPANPLUS, L<http://search.cpan.org/dist/CPANPLUS/> + +Data::Dumper, L<http://search.cpan.org/dist/Data-Dumper/> + +ExtUtils::MakeMaker, L<http://search.cpan.org/dist/ExtUtils-MakeMaker/> + +Module::Build, L<http://search.cpan.org/dist/Module-Build/> + +Module::Install, L<http://search.cpan.org/dist/Module-Install/> + +XML, L<http://www.w3.org/XML/> + +YAML, L<http://www.yaml.org/> + +=head1 HISTORY + +=over 4 + +=item March 14, 2003 (Pi day) + +=over 2 + +=item * + +Created version 1.0 of this document. + +=back + +=item May 8, 2003 + +=over 2 + +=item * + +Added the L</"dynamic_config"> field, which was missing from the initial +version. + +=back + +=item November 13, 2003 + +=over 2 + +=item * + +Added more YAML rationale articles. + +=item * + +Fixed existing link to YAML discussion thread to point to new +L<http://nntp.x.perl.org/group/> site. + +=item * + +Added and deprecated the L<"private"> field. + +=item * + +Added L<"abstract">, L<"configure">, L<"requires_packages">, +L<"requires_os">, L<"excludes_os">, and L<"no_index"> fields. + +=item * + +Bumped version. + +=back + +=item November 16, 2003 + +=over 2 + +=item * + +Added L<"generation">, L<"authored_by"> fields. + +=item * + +Add alternative proposal to the L<"recommends"> field. + +=item * + +Add proposal for a L<"requires_build_tools"> field. + +=back + +=item December 9, 2003 + +=over 2 + +=item * + +Added link to latest version of this specification on CPAN. + +=item * + +Added section L<"VERSION SPECIFICATIONS">. + +=item * + +Chang name from Module::Build::META-spec to CPAN::META::Specification. + +=item * + +Add proposal for L<"auto_regenerate"> field. + +=back + +=item December 15, 2003 + +=over 2 + +=item * + +Add L<"index"> field as a compliment to L<"no_index"> + +=item * + +Add L<"keywords"> field as a means to aid searching distributions. + +=item * + +Add L<"TERMINOLOGY"> section to explain certain terms that may be +ambiguous. + +=back + +=item July 26, 2005 + +=over 2 + +=item * + +Removed a bunch of items (generation, requires_build_tools, +requires_packages, configure, requires_os, excludes_os, +auto_regenerate) that have never actually been supported, but were +more like records of brainstorming. + +=item * + +Changed C<authored_by> to C<author>, since that's always been what +it's actually called in actual F<META.yml> files. + +=item * + +Added the "==" operator to the list of supported version-checking +operators. + +=item * + +Noted that the C<distribution_type> field is basically meaningless, +and shouldn't really be used. + +=item * + +Clarified C<dynamic_config> a bit. + +=back + +=item August 23, 2005 + +=over 2 + +=item * + +Removed the name C<CPAN::META::Specification>, since that implies a +module that doesn't actually exist. + +=back + +=item June 12, 2007 + +=over 2 + +=item * + +Added C<configure_requires>. + +=back + +=back diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/Merge.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/Merge.pm new file mode 100644 index 00000000000..f4c12869c44 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/Merge.pm @@ -0,0 +1,278 @@ +use strict; +use warnings; + +package CPAN::Meta::Merge; + +our $VERSION = '2.150001'; + +use Carp qw/croak/; +use Scalar::Util qw/blessed/; +use CPAN::Meta::Converter 2.141170; + +sub _identical { + my ($left, $right, $path) = @_; + croak sprintf "Can't merge attribute %s: '%s' does not equal '%s'", join('.', @{$path}), $left, $right unless $left eq $right; + return $left; +} + +sub _merge { + my ($current, $next, $mergers, $path) = @_; + for my $key (keys %{$next}) { + if (not exists $current->{$key}) { + $current->{$key} = $next->{$key}; + } + elsif (my $merger = $mergers->{$key}) { + $current->{$key} = $merger->($current->{$key}, $next->{$key}, [ @{$path}, $key ]); + } + elsif ($merger = $mergers->{':default'}) { + $current->{$key} = $merger->($current->{$key}, $next->{$key}, [ @{$path}, $key ]); + } + else { + croak sprintf "Can't merge unknown attribute '%s'", join '.', @{$path}, $key; + } + } + return $current; +} + +sub _uniq { + my %seen = (); + return grep { not $seen{$_}++ } @_; +} + +sub _set_addition { + my ($left, $right) = @_; + return [ +_uniq(@{$left}, @{$right}) ]; +} + +sub _uniq_map { + my ($left, $right, $path) = @_; + for my $key (keys %{$right}) { + if (not exists $left->{$key}) { + $left->{$key} = $right->{$key}; + } + else { + croak 'Duplication of element ' . join '.', @{$path}, $key; + } + } + return $left; +} + +sub _improvize { + my ($left, $right, $path) = @_; + my ($name) = reverse @{$path}; + if ($name =~ /^x_/) { + if (ref($left) eq 'ARRAY') { + return _set_addition($left, $right, $path); + } + elsif (ref($left) eq 'HASH') { + return _uniq_map($left, $right, $path); + } + else { + return _identical($left, $right, $path); + } + } + croak sprintf "Can't merge '%s'", join '.', @{$path}; +} + +sub _optional_features { + my ($left, $right, $path) = @_; + + for my $key (keys %{$right}) { + if (not exists $left->{$key}) { + $left->{$key} = $right->{$key}; + } + else { + for my $subkey (keys %{ $right->{$key} }) { + next if $subkey eq 'prereqs'; + if (not exists $left->{$key}{$subkey}) { + $left->{$key}{$subkey} = $right->{$key}{$subkey}; + } + else { + Carp::croak "Cannot merge two optional_features named '$key' with different '$subkey' values" + if do { no warnings 'uninitialized'; $left->{$key}{$subkey} ne $right->{$key}{$subkey} }; + } + } + + require CPAN::Meta::Prereqs; + $left->{$key}{prereqs} = + CPAN::Meta::Prereqs->new($left->{$key}{prereqs}) + ->with_merged_prereqs(CPAN::Meta::Prereqs->new($right->{$key}{prereqs})) + ->as_string_hash; + } + } + return $left; +} + + +my %default = ( + abstract => \&_identical, + author => \&_set_addition, + dynamic_config => sub { + my ($left, $right) = @_; + return $left || $right; + }, + generated_by => sub { + my ($left, $right) = @_; + return join ', ', _uniq(split(/, /, $left), split(/, /, $right)); + }, + license => \&_set_addition, + 'meta-spec' => { + version => \&_identical, + url => \&_identical + }, + name => \&_identical, + release_status => \&_identical, + version => \&_identical, + description => \&_identical, + keywords => \&_set_addition, + no_index => { map { ($_ => \&_set_addition) } qw/file directory package namespace/ }, + optional_features => \&_optional_features, + prereqs => sub { + require CPAN::Meta::Prereqs; + my ($left, $right) = map { CPAN::Meta::Prereqs->new($_) } @_[0,1]; + return $left->with_merged_prereqs($right)->as_string_hash; + }, + provides => \&_uniq_map, + resources => { + license => \&_set_addition, + homepage => \&_identical, + bugtracker => \&_uniq_map, + repository => \&_uniq_map, + ':default' => \&_improvize, + }, + ':default' => \&_improvize, +); + +sub new { + my ($class, %arguments) = @_; + croak 'default version required' if not exists $arguments{default_version}; + my %mapping = %default; + my %extra = %{ $arguments{extra_mappings} || {} }; + for my $key (keys %extra) { + if (ref($mapping{$key}) eq 'HASH') { + $mapping{$key} = { %{ $mapping{$key} }, %{ $extra{$key} } }; + } + else { + $mapping{$key} = $extra{$key}; + } + } + return bless { + default_version => $arguments{default_version}, + mapping => _coerce_mapping(\%mapping, []), + }, $class; +} + +my %coderef_for = ( + set_addition => \&_set_addition, + uniq_map => \&_uniq_map, + identical => \&_identical, + improvize => \&_improvize, +); + +sub _coerce_mapping { + my ($orig, $map_path) = @_; + my %ret; + for my $key (keys %{$orig}) { + my $value = $orig->{$key}; + if (ref($orig->{$key}) eq 'CODE') { + $ret{$key} = $value; + } + elsif (ref($value) eq 'HASH') { + my $mapping = _coerce_mapping($value, [ @{$map_path}, $key ]); + $ret{$key} = sub { + my ($left, $right, $path) = @_; + return _merge($left, $right, $mapping, [ @{$path} ]); + }; + } + elsif ($coderef_for{$value}) { + $ret{$key} = $coderef_for{$value}; + } + else { + croak "Don't know what to do with " . join '.', @{$map_path}, $key; + } + } + return \%ret; +} + +sub merge { + my ($self, @items) = @_; + my $current = {}; + for my $next (@items) { + if ( blessed($next) && $next->isa('CPAN::Meta') ) { + $next = $next->as_struct; + } + elsif ( ref($next) eq 'HASH' ) { + my $cmc = CPAN::Meta::Converter->new( + $next, default_version => $self->{default_version} + ); + $next = $cmc->upgrade_fragment; + } + else { + croak "Don't know how to merge '$next'"; + } + $current = _merge($current, $next, $self->{mapping}, []); + } + return $current; +} + +1; + +# ABSTRACT: Merging CPAN Meta fragments + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +CPAN::Meta::Merge - Merging CPAN Meta fragments + +=head1 VERSION + +version 2.150001 + +=head1 SYNOPSIS + + my $merger = CPAN::Meta::Merge->new(default_version => "2"); + my $meta = $merger->merge($base, @additional); + +=head1 DESCRIPTION + +=head1 METHODS + +=head2 new + +This creates a CPAN::Meta::Merge object. It takes one mandatory named +argument, C<version>, declaring the version of the meta-spec that must be +used for the merge. It can optionally take an C<extra_mappings> argument +that allows one to add additional merging functions for specific elements. + +=head2 merge(@fragments) + +Merge all C<@fragments> together. It will accept both CPAN::Meta objects and +(possibly incomplete) hashrefs of metadata. + +=head1 AUTHORS + +=over 4 + +=item * + +David Golden <dagolden@cpan.org> + +=item * + +Ricardo Signes <rjbs@cpan.org> + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2010 by David Golden and Ricardo Signes. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/Prereqs.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/Prereqs.pm index b6e6c73c9e1..75035107f8c 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta/Prereqs.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/Prereqs.pm @@ -2,47 +2,48 @@ use 5.006; use strict; use warnings; package CPAN::Meta::Prereqs; -our $VERSION = '2.140640'; # VERSION -# =head1 DESCRIPTION -# -# A CPAN::Meta::Prereqs object represents the prerequisites for a CPAN -# distribution or one of its optional features. Each set of prereqs is -# organized by phase and type, as described in L<CPAN::Meta::Prereqs>. -# -# =cut +our $VERSION = '2.150001'; + +#pod =head1 DESCRIPTION +#pod +#pod A CPAN::Meta::Prereqs object represents the prerequisites for a CPAN +#pod distribution or one of its optional features. Each set of prereqs is +#pod organized by phase and type, as described in L<CPAN::Meta::Prereqs>. +#pod +#pod =cut use Carp qw(confess); use Scalar::Util qw(blessed); use CPAN::Meta::Requirements 2.121; -# =method new -# -# my $prereq = CPAN::Meta::Prereqs->new( \%prereq_spec ); -# -# This method returns a new set of Prereqs. The input should look like the -# contents of the C<prereqs> field described in L<CPAN::Meta::Spec>, meaning -# something more or less like this: -# -# my $prereq = CPAN::Meta::Prereqs->new({ -# runtime => { -# requires => { -# 'Some::Module' => '1.234', -# ..., -# }, -# ..., -# }, -# ..., -# }); -# -# You can also construct an empty set of prereqs with: -# -# my $prereqs = CPAN::Meta::Prereqs->new; -# -# This empty set of prereqs is useful for accumulating new prereqs before finally -# dumping the whole set into a structure or string. -# -# =cut +#pod =method new +#pod +#pod my $prereq = CPAN::Meta::Prereqs->new( \%prereq_spec ); +#pod +#pod This method returns a new set of Prereqs. The input should look like the +#pod contents of the C<prereqs> field described in L<CPAN::Meta::Spec>, meaning +#pod something more or less like this: +#pod +#pod my $prereq = CPAN::Meta::Prereqs->new({ +#pod runtime => { +#pod requires => { +#pod 'Some::Module' => '1.234', +#pod ..., +#pod }, +#pod ..., +#pod }, +#pod ..., +#pod }); +#pod +#pod You can also construct an empty set of prereqs with: +#pod +#pod my $prereqs = CPAN::Meta::Prereqs->new; +#pod +#pod This empty set of prereqs is useful for accumulating new prereqs before finally +#pod dumping the whole set into a structure or string. +#pod +#pod =cut sub __legal_phases { qw(configure build test runtime develop) } sub __legal_types { qw(requires recommends suggests conflicts) } @@ -78,19 +79,19 @@ sub new { return bless \%guts => $class; } -# =method requirements_for -# -# my $requirements = $prereqs->requirements_for( $phase, $type ); -# -# This method returns a L<CPAN::Meta::Requirements> object for the given -# phase/type combination. If no prerequisites are registered for that -# combination, a new CPAN::Meta::Requirements object will be returned, and it may -# be added to as needed. -# -# If C<$phase> or C<$type> are undefined or otherwise invalid, an exception will -# be raised. -# -# =cut +#pod =method requirements_for +#pod +#pod my $requirements = $prereqs->requirements_for( $phase, $type ); +#pod +#pod This method returns a L<CPAN::Meta::Requirements> object for the given +#pod phase/type combination. If no prerequisites are registered for that +#pod combination, a new CPAN::Meta::Requirements object will be returned, and it may +#pod be added to as needed. +#pod +#pod If C<$phase> or C<$type> are undefined or otherwise invalid, an exception will +#pod be raised. +#pod +#pod =cut sub requirements_for { my ($self, $phase, $type) = @_; @@ -113,21 +114,21 @@ sub requirements_for { return $req; } -# =method with_merged_prereqs -# -# my $new_prereqs = $prereqs->with_merged_prereqs( $other_prereqs ); -# -# my $new_prereqs = $prereqs->with_merged_prereqs( \@other_prereqs ); -# -# This method returns a new CPAN::Meta::Prereqs objects in which all the -# other prerequisites given are merged into the current set. This is primarily -# provided for combining a distribution's core prereqs with the prereqs of one of -# its optional features. -# -# The new prereqs object has no ties to the originals, and altering it further -# will not alter them. -# -# =cut +#pod =method with_merged_prereqs +#pod +#pod my $new_prereqs = $prereqs->with_merged_prereqs( $other_prereqs ); +#pod +#pod my $new_prereqs = $prereqs->with_merged_prereqs( \@other_prereqs ); +#pod +#pod This method returns a new CPAN::Meta::Prereqs objects in which all the +#pod other prerequisites given are merged into the current set. This is primarily +#pod provided for combining a distribution's core prereqs with the prereqs of one of +#pod its optional features. +#pod +#pod The new prereqs object has no ties to the originals, and altering it further +#pod will not alter them. +#pod +#pod =cut sub with_merged_prereqs { my ($self, $other) = @_; @@ -158,18 +159,18 @@ sub with_merged_prereqs { return (ref $self)->new(\%new_arg); } -# =method merged_requirements -# -# my $new_reqs = $prereqs->merged_requirements( \@phases, \@types ); -# my $new_reqs = $prereqs->merged_requirements( \@phases ); -# my $new_reqs = $preerqs->merged_requirements(); -# -# This method joins together all requirements across a number of phases -# and types into a new L<CPAN::Meta::Requirements> object. If arguments -# are omitted, it defaults to "runtime", "build" and "test" for phases -# and "requires" and "recommends" for types. -# -# =cut +#pod =method merged_requirements +#pod +#pod my $new_reqs = $prereqs->merged_requirements( \@phases, \@types ); +#pod my $new_reqs = $prereqs->merged_requirements( \@phases ); +#pod my $new_reqs = $preerqs->merged_requirements(); +#pod +#pod This method joins together all requirements across a number of phases +#pod and types into a new L<CPAN::Meta::Requirements> object. If arguments +#pod are omitted, it defaults to "runtime", "build" and "test" for phases +#pod and "requires" and "recommends" for types. +#pod +#pod =cut sub merged_requirements { my ($self, $phases, $types) = @_; @@ -201,13 +202,13 @@ sub merged_requirements { } -# =method as_string_hash -# -# This method returns a hashref containing structures suitable for dumping into a -# distmeta data structure. It is made up of hashes and strings, only; there will -# be no Prereqs, CPAN::Meta::Requirements, or C<version> objects inside it. -# -# =cut +#pod =method as_string_hash +#pod +#pod This method returns a hashref containing structures suitable for dumping into a +#pod distmeta data structure. It is made up of hashes and strings, only; there will +#pod be no Prereqs, CPAN::Meta::Requirements, or C<version> objects inside it. +#pod +#pod =cut sub as_string_hash { my ($self) = @_; @@ -226,22 +227,22 @@ sub as_string_hash { return \%hash; } -# =method is_finalized -# -# This method returns true if the set of prereqs has been marked "finalized," and -# cannot be altered. -# -# =cut +#pod =method is_finalized +#pod +#pod This method returns true if the set of prereqs has been marked "finalized," and +#pod cannot be altered. +#pod +#pod =cut sub is_finalized { $_[0]{finalized} } -# =method finalize -# -# Calling C<finalize> on a Prereqs object will close it for further modification. -# Attempting to make any changes that would actually alter the prereqs will -# result in an exception being thrown. -# -# =cut +#pod =method finalize +#pod +#pod Calling C<finalize> on a Prereqs object will close it for further modification. +#pod Attempting to make any changes that would actually alter the prereqs will +#pod result in an exception being thrown. +#pod +#pod =cut sub finalize { my ($self) = @_; @@ -253,16 +254,16 @@ sub finalize { } } -# =method clone -# -# my $cloned_prereqs = $prereqs->clone; -# -# This method returns a Prereqs object that is identical to the original object, -# but can be altered without affecting the original object. Finalization does -# not survive cloning, meaning that you may clone a finalized set of prereqs and -# then modify the clone. -# -# =cut +#pod =method clone +#pod +#pod my $cloned_prereqs = $prereqs->clone; +#pod +#pod This method returns a Prereqs object that is identical to the original object, +#pod but can be altered without affecting the original object. Finalization does +#pod not survive cloning, meaning that you may clone a finalized set of prereqs and +#pod then modify the clone. +#pod +#pod =cut sub clone { my ($self) = @_; @@ -286,7 +287,7 @@ CPAN::Meta::Prereqs - a set of distribution prerequisites by phase and type =head1 VERSION -version 2.140640 +version 2.150001 =head1 DESCRIPTION diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/Requirements.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/Requirements.pm index 621550cef6a..83485594985 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta/Requirements.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/Requirements.pm @@ -1,14 +1,74 @@ use strict; use warnings; package CPAN::Meta::Requirements; -our $VERSION = '2.125'; # VERSION # ABSTRACT: a set of version requirements for a CPAN dist +our $VERSION = '2.132'; + +#pod =head1 SYNOPSIS +#pod +#pod use CPAN::Meta::Requirements; +#pod +#pod my $build_requires = CPAN::Meta::Requirements->new; +#pod +#pod $build_requires->add_minimum('Library::Foo' => 1.208); +#pod +#pod $build_requires->add_minimum('Library::Foo' => 2.602); +#pod +#pod $build_requires->add_minimum('Module::Bar' => 'v1.2.3'); +#pod +#pod $METAyml->{build_requires} = $build_requires->as_string_hash; +#pod +#pod =head1 DESCRIPTION +#pod +#pod A CPAN::Meta::Requirements object models a set of version constraints like +#pod those specified in the F<META.yml> or F<META.json> files in CPAN distributions, +#pod and as defined by L<CPAN::Meta::Spec>; +#pod It can be built up by adding more and more constraints, and it will reduce them +#pod to the simplest representation. +#pod +#pod Logically impossible constraints will be identified immediately by thrown +#pod exceptions. +#pod +#pod =cut use Carp (); -use Scalar::Util (); -use version 0.77 (); # the ->parse method +# To help ExtUtils::MakeMaker bootstrap CPAN::Meta::Requirements on perls +# before 5.10, we fall back to the EUMM bundled compatibility version module if +# that's the only thing available. This shouldn't ever happen in a normal CPAN +# install of CPAN::Meta::Requirements, as version.pm will be picked up from +# prereqs and be available at runtime. + +BEGIN { + eval "use version ()"; ## no critic + if ( my $err = $@ ) { + eval "use ExtUtils::MakeMaker::version" or die $err; ## no critic + } +} + +# Perl 5.10.0 didn't have "is_qv" in version.pm +*_is_qv = version->can('is_qv') ? sub { $_[0]->is_qv } : sub { exists $_[0]->{qv} }; + +# construct once, reuse many times +my $V0 = version->new(0); + +#pod =method new +#pod +#pod my $req = CPAN::Meta::Requirements->new; +#pod +#pod This returns a new CPAN::Meta::Requirements object. It takes an optional +#pod hash reference argument. Currently, only one key is supported: +#pod +#pod =for :list +#pod * C<bad_version_hook> -- if provided, when a version cannot be parsed into +#pod a version object, this code reference will be called with the invalid +#pod version string as first argument, and the module name as second +#pod argument. It must return a valid version object. +#pod +#pod All other keys are ignored. +#pod +#pod =cut my @valid_options = qw( bad_version_hook ); @@ -22,22 +82,60 @@ sub new { return bless \%self => $class; } +# from version::vpp +sub _find_magic_vstring { + my $value = shift; + my $tvalue = ''; + require B; + my $sv = B::svref_2object(\$value); + my $magic = ref($sv) eq 'B::PVMG' ? $sv->MAGIC : undef; + while ( $magic ) { + if ( $magic->TYPE eq 'V' ) { + $tvalue = $magic->PTR; + $tvalue =~ s/^v?(.+)$/v$1/; + last; + } + else { + $magic = $magic->MOREMAGIC; + } + } + return $tvalue; +} + +# safe if given an unblessed reference +sub _isa_version { + UNIVERSAL::isa( $_[0], 'UNIVERSAL' ) && $_[0]->isa('version') +} + sub _version_object { - my ($self, $version) = @_; + my ($self, $module, $version) = @_; my $vobj; + # hack around version::vpp not handling <3 character vstring literals + if ( $INC{'version/vpp.pm'} || $INC{'ExtUtils/MakeMaker/version/vpp.pm'} ) { + my $magic = _find_magic_vstring( $version ); + $version = $magic if length $magic; + } + eval { - $vobj = (! defined $version) ? version->parse(0) - : (! Scalar::Util::blessed($version)) ? version->parse($version) - : $version; + if (not defined $version or (!ref($version) && $version eq '0')) { + $vobj = $V0; + } + elsif ( ref($version) eq 'version' || _isa_version($version) ) { + $vobj = $version; + } + else { + local $SIG{__WARN__} = sub { die "Invalid version: $_[0]" }; + $vobj = version->new($version); + } }; if ( my $err = $@ ) { my $hook = $self->{bad_version_hook}; - $vobj = eval { $hook->($version) } + $vobj = eval { $hook->($version, $module) } if ref $hook eq 'CODE'; - unless (Scalar::Util::blessed($vobj) && $vobj->isa("version")) { + unless (eval { $vobj->isa("version") }) { $err =~ s{ at .* line \d+.*$}{}; die "Can't convert '$version': $err"; } @@ -45,27 +143,78 @@ sub _version_object { # ensure no leading '.' if ( $vobj =~ m{\A\.} ) { - $vobj = version->parse("0$vobj"); + $vobj = version->new("0$vobj"); } # ensure normal v-string form - if ( $vobj->is_qv ) { - $vobj = version->parse($vobj->normal); + if ( _is_qv($vobj) ) { + $vobj = version->new($vobj->normal); } return $vobj; } +#pod =method add_minimum +#pod +#pod $req->add_minimum( $module => $version ); +#pod +#pod This adds a new minimum version requirement. If the new requirement is +#pod redundant to the existing specification, this has no effect. +#pod +#pod Minimum requirements are inclusive. C<$version> is required, along with any +#pod greater version number. +#pod +#pod This method returns the requirements object. +#pod +#pod =method add_maximum +#pod +#pod $req->add_maximum( $module => $version ); +#pod +#pod This adds a new maximum version requirement. If the new requirement is +#pod redundant to the existing specification, this has no effect. +#pod +#pod Maximum requirements are inclusive. No version strictly greater than the given +#pod version is allowed. +#pod +#pod This method returns the requirements object. +#pod +#pod =method add_exclusion +#pod +#pod $req->add_exclusion( $module => $version ); +#pod +#pod This adds a new excluded version. For example, you might use these three +#pod method calls: +#pod +#pod $req->add_minimum( $module => '1.00' ); +#pod $req->add_maximum( $module => '1.82' ); +#pod +#pod $req->add_exclusion( $module => '1.75' ); +#pod +#pod Any version between 1.00 and 1.82 inclusive would be acceptable, except for +#pod 1.75. +#pod +#pod This method returns the requirements object. +#pod +#pod =method exact_version +#pod +#pod $req->exact_version( $module => $version ); +#pod +#pod This sets the version required for the given module to I<exactly> the given +#pod version. No other version would be considered acceptable. +#pod +#pod This method returns the requirements object. +#pod +#pod =cut BEGIN { - for my $type (qw(minimum maximum exclusion exact_version)) { + for my $type (qw(maximum exclusion exact_version)) { my $method = "with_$type"; my $to_add = $type eq 'exact_version' ? $type : "add_$type"; my $code = sub { my ($self, $name, $version) = @_; - $version = $self->_version_object( $version ); + $version = $self->_version_object( $name, $version ); $self->__modify_entry_for($name, $method, $version); @@ -77,6 +226,36 @@ BEGIN { } } +sub add_minimum { + my ($self, $name, $version) = @_; + + if (not defined $version or (!ref($version) && $version eq '0')) { + return $self if $self->__entry_for($name); + Carp::confess("can't add new requirements to finalized requirements") + if $self->is_finalized; + + $self->{requirements}{ $name } = + CPAN::Meta::Requirements::_Range::Range->with_minimum($V0); + } + else { + $version = $self->_version_object( $name, $version ); + + $self->__modify_entry_for($name, 'with_minimum', $version); + } + return $self; +} + +#pod =method add_requirements +#pod +#pod $req->add_requirements( $another_req_object ); +#pod +#pod This method adds all the requirements in the given CPAN::Meta::Requirements object +#pod to the requirements object on which it was called. If there are any conflicts, +#pod an exception is thrown. +#pod +#pod This method returns the requirements object. +#pod +#pod =cut sub add_requirements { my ($self, $req) = @_; @@ -92,16 +271,41 @@ sub add_requirements { return $self; } +#pod =method accepts_module +#pod +#pod my $bool = $req->accepts_module($module => $version); +#pod +#pod Given an module and version, this method returns true if the version +#pod specification for the module accepts the provided version. In other words, +#pod given: +#pod +#pod Module => '>= 1.00, < 2.00' +#pod +#pod We will accept 1.00 and 1.75 but not 0.50 or 2.00. +#pod +#pod For modules that do not appear in the requirements, this method will return +#pod true. +#pod +#pod =cut sub accepts_module { my ($self, $module, $version) = @_; - $version = $self->_version_object( $version ); + $version = $self->_version_object( $module, $version ); return 1 unless my $range = $self->__entry_for($module); return $range->_accepts($version); } +#pod =method clear_requirement +#pod +#pod $req->clear_requirement( $module ); +#pod +#pod This removes the requirement for a given module from the object. +#pod +#pod This method returns the requirements object. +#pod +#pod =cut sub clear_requirement { my ($self, $module) = @_; @@ -116,6 +320,17 @@ sub clear_requirement { return $self; } +#pod =method requirements_for_module +#pod +#pod $req->requirements_for_module( $module ); +#pod +#pod This returns a string containing the version requirements for a given module in +#pod the format described in L<CPAN::Meta::Spec> or undef if the given module has no +#pod requirements. This should only be used for informational purposes such as error +#pod messages and should not be interpreted or used for comparison (see +#pod L</accepts_module> instead.) +#pod +#pod =cut sub requirements_for_module { my ($self, $module) = @_; @@ -124,9 +339,23 @@ sub requirements_for_module { return $entry->as_string; } +#pod =method required_modules +#pod +#pod This method returns a list of all the modules for which requirements have been +#pod specified. +#pod +#pod =cut sub required_modules { keys %{ $_[0]{requirements} } } +#pod =method clone +#pod +#pod $req->clone; +#pod +#pod This method returns a clone of the invocant. The clone and the original object +#pod can then be changed independent of one another. +#pod +#pod =cut sub clone { my ($self) = @_; @@ -155,6 +384,12 @@ sub __modify_entry_for { $self->{requirements}{ $name } = $new; } +#pod =method is_simple +#pod +#pod This method returns true if and only if all requirements are inclusive minimums +#pod -- that is, if their string expression is just the version number. +#pod +#pod =cut sub is_simple { my ($self) = @_; @@ -166,12 +401,61 @@ sub is_simple { return 1; } +#pod =method is_finalized +#pod +#pod This method returns true if the requirements have been finalized by having the +#pod C<finalize> method called on them. +#pod +#pod =cut sub is_finalized { $_[0]{finalized} } +#pod =method finalize +#pod +#pod This method marks the requirements finalized. Subsequent attempts to change +#pod the requirements will be fatal, I<if> they would result in a change. If they +#pod would not alter the requirements, they have no effect. +#pod +#pod If a finalized set of requirements is cloned, the cloned requirements are not +#pod also finalized. +#pod +#pod =cut sub finalize { $_[0]{finalized} = 1 } +#pod =method as_string_hash +#pod +#pod This returns a reference to a hash describing the requirements using the +#pod strings in the L<CPAN::Meta::Spec> specification. +#pod +#pod For example after the following program: +#pod +#pod my $req = CPAN::Meta::Requirements->new; +#pod +#pod $req->add_minimum('CPAN::Meta::Requirements' => 0.102); +#pod +#pod $req->add_minimum('Library::Foo' => 1.208); +#pod +#pod $req->add_maximum('Library::Foo' => 2.602); +#pod +#pod $req->add_minimum('Module::Bar' => 'v1.2.3'); +#pod +#pod $req->add_exclusion('Module::Bar' => 'v1.2.8'); +#pod +#pod $req->exact_version('Xyzzy' => '6.01'); +#pod +#pod my $hashref = $req->as_string_hash; +#pod +#pod C<$hashref> would contain: +#pod +#pod { +#pod 'CPAN::Meta::Requirements' => '0.102', +#pod 'Library::Foo' => '>= 1.208, <= 2.206', +#pod 'Module::Bar' => '>= v1.2.3, != v1.2.8', +#pod 'Xyzzy' => '== 6.01', +#pod } +#pod +#pod =cut sub as_string_hash { my ($self) = @_; @@ -182,6 +466,40 @@ sub as_string_hash { return \%hash; } +#pod =method add_string_requirement +#pod +#pod $req->add_string_requirement('Library::Foo' => '>= 1.208, <= 2.206'); +#pod $req->add_string_requirement('Library::Foo' => v1.208); +#pod +#pod This method parses the passed in string and adds the appropriate requirement +#pod for the given module. A version can be a Perl "v-string". It understands +#pod version ranges as described in the L<CPAN::Meta::Spec/Version Ranges>. For +#pod example: +#pod +#pod =over 4 +#pod +#pod =item 1.3 +#pod +#pod =item >= 1.3 +#pod +#pod =item <= 1.3 +#pod +#pod =item == 1.3 +#pod +#pod =item != 1.3 +#pod +#pod =item > 1.3 +#pod +#pod =item < 1.3 +#pod +#pod =item >= 1.3, != 1.5, <= 2.0 +#pod +#pod A version number without an operator is equivalent to specifying a minimum +#pod (C<E<gt>=>). Extra whitespace is allowed. +#pod +#pod =back +#pod +#pod =cut my %methods_for_op = ( '==' => [ qw(exact_version) ], @@ -195,11 +513,18 @@ my %methods_for_op = ( sub add_string_requirement { my ($self, $module, $req) = @_; - Carp::confess("No requirement string provided for $module") - unless defined $req && length $req; + unless ( defined $req && length $req ) { + $req = 0; + $self->_blank_carp($module); + } - my @parts = split qr{\s*,\s*}, $req; + my $magic = _find_magic_vstring( $req ); + if (length $magic) { + $self->add_minimum($module => $magic); + return; + } + my @parts = split qr{\s*,\s*}, $req; for my $part (@parts) { my ($op, $ver) = $part =~ m{\A\s*(==|>=|>|<=|<|!=)\s*(.*)\z}; @@ -215,17 +540,35 @@ sub add_string_requirement { } } +#pod =method from_string_hash +#pod +#pod my $req = CPAN::Meta::Requirements->from_string_hash( \%hash ); +#pod my $req = CPAN::Meta::Requirements->from_string_hash( \%hash, \%opts ); +#pod +#pod This is an alternate constructor for a CPAN::Meta::Requirements +#pod object. It takes a hash of module names and version requirement +#pod strings and returns a new CPAN::Meta::Requirements object. As with +#pod add_string_requirement, a version can be a Perl "v-string". Optionally, +#pod you can supply a hash-reference of options, exactly as with the L</new> +#pod method. +#pod +#pod =cut + +sub _blank_carp { + my ($self, $module) = @_; + Carp::carp("Undefined requirement for $module treated as '0'"); +} sub from_string_hash { - my ($class, $hash) = @_; + my ($class, $hash, $options) = @_; - my $self = $class->new; + my $self = $class->new($options); for my $module (keys %$hash) { my $req = $hash->{$module}; unless ( defined $req && length $req ) { $req = 0; - Carp::carp("Undefined requirement for $module treated as '0'"); + $class->_blank_carp($module); } $self->add_string_requirement($module, $req); } @@ -436,7 +779,7 @@ __END__ =pod -=encoding utf-8 +=encoding UTF-8 =head1 NAME @@ -444,7 +787,7 @@ CPAN::Meta::Requirements - a set of version requirements for a CPAN dist =head1 VERSION -version 2.125 +version 2.132 =head1 SYNOPSIS @@ -463,7 +806,8 @@ version 2.125 =head1 DESCRIPTION A CPAN::Meta::Requirements object models a set of version constraints like -those specified in the F<META.yml> or F<META.json> files in CPAN distributions. +those specified in the F<META.yml> or F<META.json> files in CPAN distributions, +and as defined by L<CPAN::Meta::Spec>; It can be built up by adding more and more constraints, and it will reduce them to the simplest representation. @@ -477,16 +821,13 @@ exceptions. my $req = CPAN::Meta::Requirements->new; This returns a new CPAN::Meta::Requirements object. It takes an optional -hash reference argument. The following keys are supported: +hash reference argument. Currently, only one key is supported: =over 4 =item * -<bad_version_hook> -- if provided, when a version cannot be parsed into - -a version object, this code reference will be called with the invalid version -string as an argument. It must return a valid version object. +C<bad_version_hook> -- if provided, when a version cannot be parsed into a version object, this code reference will be called with the invalid version string as first argument, and the module name as second argument. It must return a valid version object. =back @@ -554,7 +895,7 @@ This method returns the requirements object. =head2 accepts_module - my $bool = $req->accepts_modules($module => $version); + my $bool = $req->accepts_module($module => $version); Given an module and version, this method returns true if the version specification for the module accepts the provided version. In other words, @@ -619,7 +960,7 @@ also finalized. =head2 as_string_hash This returns a reference to a hash describing the requirements using the -strings in the F<META.yml> specification. +strings in the L<CPAN::Meta::Spec> specification. For example after the following program: @@ -651,10 +992,12 @@ C<$hashref> would contain: =head2 add_string_requirement $req->add_string_requirement('Library::Foo' => '>= 1.208, <= 2.206'); + $req->add_string_requirement('Library::Foo' => v1.208); This method parses the passed in string and adds the appropriate requirement -for the given module. It understands version ranges as described in the -L<CPAN::Meta::Spec/Version Ranges>. For example: +for the given module. A version can be a Perl "v-string". It understands +version ranges as described in the L<CPAN::Meta::Spec/Version Ranges>. For +example: =over 4 @@ -682,10 +1025,14 @@ A version number without an operator is equivalent to specifying a minimum =head2 from_string_hash my $req = CPAN::Meta::Requirements->from_string_hash( \%hash ); + my $req = CPAN::Meta::Requirements->from_string_hash( \%hash, \%opts ); -This is an alternate constructor for a CPAN::Meta::Requirements object. It takes -a hash of module names and version requirement strings and returns a new -CPAN::Meta::Requirements object. +This is an alternate constructor for a CPAN::Meta::Requirements +object. It takes a hash of module names and version requirement +strings and returns a new CPAN::Meta::Requirements object. As with +add_string_requirement, a version can be a Perl "v-string". Optionally, +you can supply a hash-reference of options, exactly as with the L</new> +method. =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan @@ -720,6 +1067,30 @@ Ricardo Signes <rjbs@cpan.org> =back +=head1 CONTRIBUTORS + +=for stopwords Ed J Karen Etheridge Leon Timmermans robario + +=over 4 + +=item * + +Ed J <mohawk2@users.noreply.github.com> + +=item * + +Karen Etheridge <ether@cpan.org> + +=item * + +Leon Timmermans <fawaka@gmail.com> + +=item * + +robario <webmaster@robario.com> + +=back + =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2010 by David Golden and Ricardo Signes. diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/Spec.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/Spec.pm index 1ec27af25e9..ec68f178edf 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta/Spec.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/Spec.pm @@ -7,7 +7,8 @@ use 5.006; use strict; use warnings; package CPAN::Meta::Spec; -our $VERSION = '2.140640'; # VERSION + +our $VERSION = '2.150001'; 1; @@ -28,7 +29,7 @@ CPAN::Meta::Spec - specification for CPAN distribution metadata =head1 VERSION -version 2.140640 +version 2.150001 =head1 SYNOPSIS @@ -289,11 +290,17 @@ etc.) as part of its configuration. This field should be set to a false value to indicate that prerequisites included in metadata may be considered final and valid for static analysis. +Note: when this field is true, post-configuration prerequisites are not +guaranteed to bear any relation whatsoever to those stated in the metadata, +and relying on them doing so is an error. See also +L</Prerequisites for dynamically configured distributions> in the implementors' +notes. + This field explicitly B<does not> indicate whether installation may be safely performed without using a Makefile or Build file, as there may be special files to install or custom installation targets (e.g. for dual-life modules that exist on CPAN as well as in the Perl core). This -field only defines whether prerequisites are complete as given in the +field only defines whether or not prerequisites are exactly as given in the metadata. =head3 generated_by @@ -520,7 +527,10 @@ Example: This Map describes any files, directories, packages, and namespaces that are private to the packaging or implementation of the distribution and -should be ignored by indexing or search tools. +should be ignored by indexing or search tools. Note that this is a list of +exclusions, and the spec does not define what to I<include> - see +L</Indexing distributions a la PAUSE> in the implementors notes for more +information. Valid subkeys are as follows: @@ -690,7 +700,8 @@ have a Map with the following valid subkeys: This field is required. It must contain a Unix-style relative file path from the root of the distribution directory to a file that contains or -generates the package. +generates the package. It may be given as C<META.yml> or C<META.json> +to claim a package for indexing without needing a C<*.pm>. =item version @@ -1103,6 +1114,52 @@ and version prerequisite C<$prereq>: If the values of C<$mod> and C<$prereq> have not been scrubbed, however, this presents security implications. +=head2 Prerequisites for dynamically configured distributions + +When C<dynamic_config> is true, it is an error to presume that the +prerequisites given in distribution metadata will have any relationship +whatsoever to the actual prerequisites of the distribution. + +In practice, however, one can generally expect such prerequisites to be +one of two things: + +=over 4 + +=item * + +The minimum prerequisites for the distribution, to which dynamic configuration will only add items + +=item * + +Whatever the distribution configured with on the releaser's machine at release time + +=back + +The second case often turns out to have identical results to the first case, +albeit only by accident. + +As such, consumers may use this data for informational analysis, but +presenting it to the user as canonical or relying on it as such is +invariably the height of folly. + +=head2 Indexing distributions a la PAUSE + +While no_index tells you what must be ignored when indexing, this spec holds +no opinion on how you should get your initial candidate list of things to +possibly index. For "normal" distributions you might consider simply indexing +the contents of lib/, but there are many fascinating oddities on CPAN and +many dists from the days when it was normal to put the main .pm file in the +root of the distribution archive - so PAUSE currently indexes all .pm and .PL +files that are not either (a) specifically excluded by no_index (b) in +C<inc>, C<xt>, or C<t> directories, or common 'mistake' directories such as +C<perl5>. + +Or: If you're trying to be PAUSE-like, make sure you skip C<inc>, C<xt> and +C<t> as well as anything marked as no_index. + +Also remember: If the META file contains a provides field, you shouldn't be +indexing anything in the first place - just use that. + =head1 SEE ALSO =over 4 diff --git a/Master/tlpkg/tlperl/lib/CPAN/Meta/Validator.pm b/Master/tlpkg/tlperl/lib/CPAN/Meta/Validator.pm index f8b2fcaf303..cc0409e6e48 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Meta/Validator.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Meta/Validator.pm @@ -2,26 +2,27 @@ use 5.006; use strict; use warnings; package CPAN::Meta::Validator; -our $VERSION = '2.140640'; # VERSION - -# =head1 SYNOPSIS -# -# my $struct = decode_json_file('META.json'); -# -# my $cmv = CPAN::Meta::Validator->new( $struct ); -# -# unless ( $cmv->is_valid ) { -# my $msg = "Invalid META structure. Errors found:\n"; -# $msg .= join( "\n", $cmv->errors ); -# die $msg; -# } -# -# =head1 DESCRIPTION -# -# This module validates a CPAN Meta structure against the version of the -# the specification claimed in the C<meta-spec> field of the structure. -# -# =cut + +our $VERSION = '2.150001'; + +#pod =head1 SYNOPSIS +#pod +#pod my $struct = decode_json_file('META.json'); +#pod +#pod my $cmv = CPAN::Meta::Validator->new( $struct ); +#pod +#pod unless ( $cmv->is_valid ) { +#pod my $msg = "Invalid META structure. Errors found:\n"; +#pod $msg .= join( "\n", $cmv->errors ); +#pod die $msg; +#pod } +#pod +#pod =head1 DESCRIPTION +#pod +#pod This module validates a CPAN Meta structure against the version of the +#pod the specification claimed in the C<meta-spec> field of the structure. +#pod +#pod =cut #--------------------------------------------------------------------------# # This code copied and adapted from Test::CPAN::Meta @@ -437,13 +438,13 @@ my %definitions = ( # Code #--------------------------------------------------------------------------# -# =method new -# -# my $cmv = CPAN::Meta::Validator->new( $struct ) -# -# The constructor must be passed a metadata structure. -# -# =cut +#pod =method new +#pod +#pod my $cmv = CPAN::Meta::Validator->new( $struct ) +#pod +#pod The constructor must be passed a metadata structure. +#pod +#pod =cut sub new { my ($class,$data) = @_; @@ -459,16 +460,16 @@ sub new { return bless $self, $class; } -# =method is_valid -# -# if ( $cmv->is_valid ) { -# ... -# } -# -# Returns a boolean value indicating whether the metadata provided -# is valid. -# -# =cut +#pod =method is_valid +#pod +#pod if ( $cmv->is_valid ) { +#pod ... +#pod } +#pod +#pod Returns a boolean value indicating whether the metadata provided +#pod is valid. +#pod +#pod =cut sub is_valid { my $self = shift; @@ -478,13 +479,13 @@ sub is_valid { return ! $self->errors; } -# =method errors -# -# warn( join "\n", $cmv->errors ); -# -# Returns a list of errors seen during validation. -# -# =cut +#pod =method errors +#pod +#pod warn( join "\n", $cmv->errors ); +#pod +#pod Returns a list of errors seen during validation. +#pod +#pod =cut sub errors { my $self = shift; @@ -492,31 +493,31 @@ sub errors { return @{$self->{errors}}; } -# =begin :internals -# -# =head2 Check Methods -# -# =over -# -# =item * -# -# check_map($spec,$data) -# -# Checks whether a map (or hash) part of the data structure conforms to the -# appropriate specification definition. -# -# =item * -# -# check_list($spec,$data) -# -# Checks whether a list (or array) part of the data structure conforms to -# the appropriate specification definition. -# -# =item * -# -# =back -# -# =cut +#pod =begin :internals +#pod +#pod =head2 Check Methods +#pod +#pod =over +#pod +#pod =item * +#pod +#pod check_map($spec,$data) +#pod +#pod Checks whether a map (or hash) part of the data structure conforms to the +#pod appropriate specification definition. +#pod +#pod =item * +#pod +#pod check_list($spec,$data) +#pod +#pod Checks whether a list (or array) part of the data structure conforms to +#pod the appropriate specification definition. +#pod +#pod =item * +#pod +#pod =back +#pod +#pod =cut my $spec_error = "Missing validation action in specification. " . "Must be one of 'map', 'list', or 'value'"; @@ -606,113 +607,113 @@ sub check_list { } } -# =head2 Validator Methods -# -# =over -# -# =item * -# -# header($self,$key,$value) -# -# Validates that the header is valid. -# -# Note: No longer used as we now read the data structure, not the file. -# -# =item * -# -# url($self,$key,$value) -# -# Validates that a given value is in an acceptable URL format -# -# =item * -# -# urlspec($self,$key,$value) -# -# Validates that the URL to a META specification is a known one. -# -# =item * -# -# string_or_undef($self,$key,$value) -# -# Validates that the value is either a string or an undef value. Bit of a -# catchall function for parts of the data structure that are completely user -# defined. -# -# =item * -# -# string($self,$key,$value) -# -# Validates that a string exists for the given key. -# -# =item * -# -# file($self,$key,$value) -# -# Validate that a file is passed for the given key. This may be made more -# thorough in the future. For now it acts like \&string. -# -# =item * -# -# exversion($self,$key,$value) -# -# Validates a list of versions, e.g. '<= 5, >=2, ==3, !=4, >1, <6, 0'. -# -# =item * -# -# version($self,$key,$value) -# -# Validates a single version string. Versions of the type '5.8.8' and '0.00_00' -# are both valid. A leading 'v' like 'v1.2.3' is also valid. -# -# =item * -# -# boolean($self,$key,$value) -# -# Validates for a boolean value. Currently these values are '1', '0', 'true', -# 'false', however the latter 2 may be removed. -# -# =item * -# -# license($self,$key,$value) -# -# Validates that a value is given for the license. Returns 1 if an known license -# type, or 2 if a value is given but the license type is not a recommended one. -# -# =item * -# -# custom_1($self,$key,$value) -# -# Validates that the given key is in CamelCase, to indicate a user defined -# keyword and only has characters in the class [-_a-zA-Z]. In version 1.X -# of the spec, this was only explicitly stated for 'resources'. -# -# =item * -# -# custom_2($self,$key,$value) -# -# Validates that the given key begins with 'x_' or 'X_', to indicate a user -# defined keyword and only has characters in the class [-_a-zA-Z] -# -# =item * -# -# identifier($self,$key,$value) -# -# Validates that key is in an acceptable format for the META specification, -# for an identifier, i.e. any that matches the regular expression -# qr/[a-z][a-z_]/i. -# -# =item * -# -# module($self,$key,$value) -# -# Validates that a given key is in an acceptable module name format, e.g. -# 'Test::CPAN::Meta::Version'. -# -# =back -# -# =end :internals -# -# =cut +#pod =head2 Validator Methods +#pod +#pod =over +#pod +#pod =item * +#pod +#pod header($self,$key,$value) +#pod +#pod Validates that the header is valid. +#pod +#pod Note: No longer used as we now read the data structure, not the file. +#pod +#pod =item * +#pod +#pod url($self,$key,$value) +#pod +#pod Validates that a given value is in an acceptable URL format +#pod +#pod =item * +#pod +#pod urlspec($self,$key,$value) +#pod +#pod Validates that the URL to a META specification is a known one. +#pod +#pod =item * +#pod +#pod string_or_undef($self,$key,$value) +#pod +#pod Validates that the value is either a string or an undef value. Bit of a +#pod catchall function for parts of the data structure that are completely user +#pod defined. +#pod +#pod =item * +#pod +#pod string($self,$key,$value) +#pod +#pod Validates that a string exists for the given key. +#pod +#pod =item * +#pod +#pod file($self,$key,$value) +#pod +#pod Validate that a file is passed for the given key. This may be made more +#pod thorough in the future. For now it acts like \&string. +#pod +#pod =item * +#pod +#pod exversion($self,$key,$value) +#pod +#pod Validates a list of versions, e.g. '<= 5, >=2, ==3, !=4, >1, <6, 0'. +#pod +#pod =item * +#pod +#pod version($self,$key,$value) +#pod +#pod Validates a single version string. Versions of the type '5.8.8' and '0.00_00' +#pod are both valid. A leading 'v' like 'v1.2.3' is also valid. +#pod +#pod =item * +#pod +#pod boolean($self,$key,$value) +#pod +#pod Validates for a boolean value. Currently these values are '1', '0', 'true', +#pod 'false', however the latter 2 may be removed. +#pod +#pod =item * +#pod +#pod license($self,$key,$value) +#pod +#pod Validates that a value is given for the license. Returns 1 if an known license +#pod type, or 2 if a value is given but the license type is not a recommended one. +#pod +#pod =item * +#pod +#pod custom_1($self,$key,$value) +#pod +#pod Validates that the given key is in CamelCase, to indicate a user defined +#pod keyword and only has characters in the class [-_a-zA-Z]. In version 1.X +#pod of the spec, this was only explicitly stated for 'resources'. +#pod +#pod =item * +#pod +#pod custom_2($self,$key,$value) +#pod +#pod Validates that the given key begins with 'x_' or 'X_', to indicate a user +#pod defined keyword and only has characters in the class [-_a-zA-Z] +#pod +#pod =item * +#pod +#pod identifier($self,$key,$value) +#pod +#pod Validates that key is in an acceptable format for the META specification, +#pod for an identifier, i.e. any that matches the regular expression +#pod qr/[a-z][a-z_]/i. +#pod +#pod =item * +#pod +#pod module($self,$key,$value) +#pod +#pod Validates that a given key is in an acceptable module name format, e.g. +#pod 'Test::CPAN::Meta::Version'. +#pod +#pod =back +#pod +#pod =end :internals +#pod +#pod =cut sub header { my ($self,$key,$value) = @_; @@ -997,7 +998,7 @@ CPAN::Meta::Validator - validate CPAN distribution metadata structures =head1 VERSION -version 2.140640 +version 2.150001 =head1 SYNOPSIS diff --git a/Master/tlpkg/tlperl/lib/CPAN/Module.pm b/Master/tlpkg/tlperl/lib/CPAN/Module.pm index 2c0c71ae7d1..bf1226c0f04 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Module.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Module.pm @@ -7,7 +7,7 @@ use strict; use vars qw( $VERSION ); -$VERSION = "5.5001"; +$VERSION = "5.5002"; BEGIN { # alarm() is not implemented in perl 5.6.x and earlier under Windows @@ -543,9 +543,18 @@ sub uptodate { # returns true if installed in privlib or archlib sub _in_priv_or_arch { my($self,$inst_file) = @_; - for my $confdirname (qw(archlibexp privlibexp)) { - my $confdir = $Config::Config{$confdirname}; - if ($confdir eq substr($inst_file,0,length($confdir))) { + foreach my $pair ( + [qw(sitearchexp archlibexp)], + [qw(sitelibexp privlibexp)] + ) { + my ($site, $priv) = @Config::Config{@$pair}; + if ($^O eq 'VMS') { + for my $d ($site, $priv) { $d = VMS::Filespec::unixify($d) }; + } + s!/*$!!g foreach $site, $priv; + next if $site eq $priv; + + if ($priv eq substr($inst_file,0,length($priv))) { return 1; } } diff --git a/Master/tlpkg/tlperl/lib/CPAN/Plugin.pm b/Master/tlpkg/tlperl/lib/CPAN/Plugin.pm new file mode 100644 index 00000000000..646d86b2cc9 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Plugin.pm @@ -0,0 +1,145 @@ +package CPAN::Plugin; + +use strict; +use warnings; + +our $VERSION = '0.95'; + +require CPAN; + +###################################################################### + +sub new { # ; + my ($class, %params) = @_; + + my $self = +{ + (ref $class ? (%$class) : ()), + %params, + }; + + $self = bless $self, ref $class ? ref $class : $class; + + unless (ref $class) { + local $_; + no warnings 'once'; + $CPAN::META->use_inst ($_) for $self->plugin_requires; + } + + $self; +} + +###################################################################### +sub plugin_requires { # ; +} + +###################################################################### +sub distribution_object { # ; + my ($self) = @_; + $self->{distribution_object}; +} + +###################################################################### +sub distribution { # ; + my ($self) = @_; + + my $distribution = $self->distribution_object->id; + CPAN::Shell->expand("Distribution",$distribution) + or $self->frontend->mydie("Unknowns distribution '$distribution'\n"); +} + +###################################################################### +sub distribution_info { # ; + my ($self) = @_; + + CPAN::DistnameInfo->new ($self->distribution->id); +} + +###################################################################### +sub build_dir { # ; + my ($self) = @_; + + my $build_dir = $self->distribution->{build_dir} + or $self->frontend->mydie("Distribution has not been built yet, cannot proceed"); +} + +###################################################################### +sub is_xs { # + my ($self) = @_; + + my @xs = glob File::Spec->catfile ($self->build_dir, '*.xs'); # quick try + + unless (@xs) { + require ExtUtils::Manifest; + my $manifest_file = File::Spec->catfile ($self->build_dir, "MANIFEST"); + my $manifest = ExtUtils::Manifest::maniread($manifest_file); + @xs = grep /\.xs$/, keys %$manifest; + } + + scalar @xs; +} + +###################################################################### + +package CPAN::Plugin; + +1; + +__END__ + +=pod + +=head1 NAME + +CPAN::Plugin - Base class for CPAN shell extensions + +=head1 SYNOPSIS + + package My::Plugin; + use base 'CPAN::Plugin'; + + sub post_test { + my ($self, $distribution_object) = @_; + $self = $self->new (distribution_object => $distribution_object); + ...; + } + +=head1 DESCRIPTION + +=head2 Alpha Status + +The plugin system in the CPAN shell was introduced in version 2.07 and +is still considered experimental. + +=head2 How Plugins work? + +See L<CPAN/"Plugin support">. + +=head1 METHODS + +=head2 plugin_requires + +returns list of packages given plugin requires for functionality. +This list is evaluated using C<CPAN->use_inst> method. + +=head2 distribution_object + +Get current distribution object. + +=head2 distribution + +=head2 distribution_info + +=head2 build_dir + +Simple delegatees for misc parameters derived from distribution + +=head2 is_xs + +Predicate to detect whether package contains XS. + +=head1 AUTHOR + +Branislav Zahradnik <barney@cpan.org> + +=cut + diff --git a/Master/tlpkg/tlperl/lib/CPAN/Plugin/Specfile.pm b/Master/tlpkg/tlperl/lib/CPAN/Plugin/Specfile.pm new file mode 100644 index 00000000000..f63d322c74f --- /dev/null +++ b/Master/tlpkg/tlperl/lib/CPAN/Plugin/Specfile.pm @@ -0,0 +1,258 @@ +=head1 NAME + +CPAN::Plugin::Specfile - Proof of concept implementation of a trivial CPAN::Plugin + +=head1 SYNOPSIS + + # once in the cpan shell + o conf plugin_list push CPAN::Plugin::Specfile + + # make permanent + o conf commit + + # any time in the cpan shell to write a spec file + test Acme::Meta + + # disable + o conf plugin_list pop + +=head1 DESCRIPTION + +Implemented as a post-test hook, this plugin writes a specfile after +every successful test run. The content is also written to the +terminal. + +As a side effect, the timestamps of the written specfiles reflect the +linear order of all dependencies. + +B<WARNING:> This code is just a small demo how to use the plugin +system of the CPAN shell, not a full fledged spec file writer. Do not +expect new features in this plugin. + +=head2 OPTIONS + +The target directory to store the spec files in can be set using C<dir> +as in + + o conf plugin_list push CPAN::Plugin::Specfile=dir,/tmp/specfiles-000042 + +The default directory for this is the +C<plugins/CPAN::Plugin::Specfile> directory in the I<cpan_home> +directory. + +=head1 AUTHOR + +Andreas Koenig <andk@cpan.org>, Branislav Zahradnik <barney@cpan.org> + +=cut + +package CPAN::Plugin::Specfile; + +our $VERSION = '0.01'; + +use File::Path; +use File::Spec; + +sub __accessor { + my ($class, $key) = @_; + no strict 'refs'; + *{$class . '::' . $key} = sub { + my $self = shift; + if (@_) { + $self->{$key} = shift; + } + return $self->{$key}; + }; +} +BEGIN { __PACKAGE__->__accessor($_) for qw(dir dir_default) } + +sub new { + my($class, @rest) = @_; + my $self = bless {}, $class; + while (my($arg,$val) = splice @rest, 0, 2) { + $self->$arg($val); + } + $self->dir_default(File::Spec->catdir($CPAN::Config->{cpan_home},"plugins",__PACKAGE__)); + $self; +} + +sub post_test { + my $self = shift; + my $distribution_object = shift; + my $distribution = $distribution_object->pretty_id; + unless ($CPAN::META->has_inst("CPAN::DistnameInfo")){ + $CPAN::Frontend->mydie("CPAN::DistnameInfo not installed; cannot continue"); + } + my $d = CPAN::Shell->expand("Distribution",$distribution) + or $CPAN::Frontend->mydie("Unknowns distribution '$distribution'\n"); + my $build_dir = $d->{build_dir} or $CPAN::Frontend->mydie("Distribution has not been built yet, cannot proceed"); + my %contains = map {($_ => undef)} $d->containsmods; + my @m; + my $width = 16; + my $header = sub { + my($header,$value) = @_; + push @m, sprintf("%-s:%*s%s\n", $header, $width-length($header), "", $value); + }; + my $dni = CPAN::DistnameInfo->new($distribution); + my $dist = $dni->dist; + my $summary = CPAN::Shell->_guess_manpage($d,\%contains,$dist); + $header->("Name", "perl-$dist"); + my $version = $dni->version; + $header->("Version", $version); + $header->("Release", "1%{?dist}"); +#Summary: Template processing system +#Group: Development/Libraries +#License: GPL+ or Artistic +#URL: http://www.template-toolkit.org/ +#Source0: http://search.cpan.org/CPAN/authors/id/A/AB/ABW/Template-Toolkit-%{version}.tar.gz +#Patch0: Template-2.22-SREZIC-01.patch +#BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) + for my $h_tuple + ([Summary => $summary], + [Group => "Development/Libraries"], + [License =>], + [URL =>], + [BuildRoot => "%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)"], + [Requires => "perl(:MODULE_COMPAT_%(eval \"`%{__perl} -V:version`\"; echo \$version))"], + ) { + my($h,$v) = @$h_tuple; + $v = "unknown" unless defined $v; + $header->($h, $v); + } + $header->("Source0", sprintf( + "http://search.cpan.org/CPAN/authors/id/%s/%s/%s", + substr($distribution,0,1), + substr($distribution,0,2), + $distribution + )); + require POSIX; + my @xs = glob "$build_dir/*.xs"; # quick try + unless (@xs) { + require ExtUtils::Manifest; + my $manifest_file = "$build_dir/MANIFEST"; + my $manifest = ExtUtils::Manifest::maniread($manifest_file); + @xs = grep /\.xs$/, keys %$manifest; + } + if (! @xs) { + $header->('BuildArch', 'noarch'); + } + for my $k (sort keys %contains) { + my $m = CPAN::Shell->expand("Module",$k); + my $v = $contains{$k} = $m->cpan_version; + my $vspec = $v eq "undef" ? "" : " = $v"; + $header->("Provides", "perl($k)$vspec"); + } + if (my $prereq_pm = $d->{prereq_pm}) { + my %req; + for my $reqkey (keys %$prereq_pm) { + while (my($k,$v) = each %{$prereq_pm->{$reqkey}}) { + $req{$k} = $v; + } + } + if (-e "$build_dir/Build.PL" && ! exists $req{"Module::Build"}) { + $req{"Module::Build"} = 0; + } + for my $k (sort keys %req) { + next if $k eq "perl"; + my $v = $req{$k}; + my $vspec = defined $v && length $v && $v > 0 ? " >= $v" : ""; + $header->(BuildRequires => "perl($k)$vspec"); + next if $k =~ /^(Module::Build)$/; # MB is always only a + # BuildRequires; if we + # turn it into a + # Requires, then we + # would have to make it + # a BuildRequires + # everywhere we depend + # on *one* MB built + # module. + $header->(Requires => "perl($k)$vspec"); + } + } + push @m, "\n%define _use_internal_dependency_generator 0 +%define __find_requires %{nil} +%define __find_provides %{nil} +"; + push @m, "\n%description\n%{summary}.\n"; + push @m, "\n%prep\n%setup -q -n $dist-%{version}\n"; + if (-e "$build_dir/Build.PL") { + # see http://www.redhat.com/archives/rpm-list/2002-July/msg00110.html about RPM_BUILD_ROOT vs %{buildroot} + push @m, <<'EOF'; + +%build +%{__perl} Build.PL --installdirs=vendor --libdoc installvendorman3dir +./Build + +%install +rm -rf $RPM_BUILD_ROOT +./Build install destdir=$RPM_BUILD_ROOT create_packlist=0 +find $RPM_BUILD_ROOT -depth -type d -exec rmdir {} 2>/dev/null \; +%{_fixperms} $RPM_BUILD_ROOT/* + +%check +./Build test +EOF + } elsif (-e "$build_dir/Makefile.PL") { + push @m, <<'EOF'; + +%build +%{__perl} Makefile.PL INSTALLDIRS=vendor +make %{?_smp_mflags} + +%install +rm -rf $RPM_BUILD_ROOT +make pure_install DESTDIR=$RPM_BUILD_ROOT +find $RPM_BUILD_ROOT -type f -name .packlist -exec rm -f {} ';' +find $RPM_BUILD_ROOT -depth -type d -exec rmdir {} 2>/dev/null ';' +%{_fixperms} $RPM_BUILD_ROOT/* + +%check +make test +EOF + } else { + $CPAN::Frontend->mydie("'$distribution' has neither a Build.PL nor a Makefile.PL\n"); + } + push @m, "\n%clean\nrm -rf \$RPM_BUILD_ROOT\n"; + my $vendorlib = @xs ? "vendorarch" : "vendorlib"; + my $date = POSIX::strftime("%a %b %d %Y", gmtime); + my @doc = grep { -e "$build_dir/$_" } qw(README Changes); + my $exe_stanza = "\n"; + if (my $exe_files = $d->_exe_files) { + if (@$exe_files) { + $exe_stanza = "%{_mandir}/man1/*.1*\n"; + for my $e (@$exe_files) { + unless (CPAN->has_inst("File::Basename")) { + $CPAN::Frontend->mydie("File::Basename not installed, cannot continue"); + } + my $basename = File::Basename::basename($e); + $exe_stanza .= "/usr/bin/$basename\n"; + } + } + } + push @m, <<EOF; + +%files +%defattr(-,root,root,-) +%doc @doc +%{perl_$vendorlib}/* +%{_mandir}/man3/*.3* +$exe_stanza +%changelog +* $date <specfile\@specfile.cpan.org> - $version-1 +- autogenerated by CPAN::Plugin::Specfile() + +EOF + + my $ret = join "", @m; + $CPAN::Frontend->myprint($ret); + my $target_dir = $self->dir || $self->dir_default; + File::Path::mkpath($target_dir); + my $outfile = File::Spec->catfile($target_dir, "perl-$dist.spec"); + open my $specout, ">", $outfile + or $CPAN::Frontend->mydie("Could not open >$outfile: $!"); + print $specout $ret; + $CPAN::Frontend->myprint("Wrote $outfile"); + $ret; +} + +1; diff --git a/Master/tlpkg/tlperl/lib/CPAN/Shell.pm b/Master/tlpkg/tlperl/lib/CPAN/Shell.pm index 9e0bb14a2b8..43e2fb9fa0b 100644 --- a/Master/tlpkg/tlperl/lib/CPAN/Shell.pm +++ b/Master/tlpkg/tlperl/lib/CPAN/Shell.pm @@ -47,7 +47,7 @@ use vars qw( "CPAN/Tarzip.pm", "CPAN/Version.pm", ); -$VERSION = "5.5004"; +$VERSION = "5.5005"; # record the initial timestamp for reload. $reload = { map {$INC{$_} ? ($_,(stat $INC{$_})[9]) : ()} @relo }; @CPAN::Shell::ISA = qw(CPAN::Debug); @@ -374,6 +374,9 @@ sub o { if (!@o_what or $cfilter) { # print all things, "o conf" $cfilter ||= ""; my $qrfilter = eval 'qr/$cfilter/'; + if ($@) { + $CPAN::Frontend->mydie("Cannot parse commandline: $@"); + } my($k,$v); my $configpm = CPAN::HandleConfig->require_myconfig_or_config; $CPAN::Frontend->myprint("\$CPAN::Config options from $configpm\:\n"); @@ -794,177 +797,7 @@ sub _guess_manpage { #-> sub CPAN::Shell::_specfile ; sub _specfile { - my $self = shift; - my $distribution = shift; - unless ($CPAN::META->has_inst("CPAN::DistnameInfo")){ - $CPAN::Frontend->mydie("CPAN::DistnameInfo not installed; cannot continue"); - } - my $d = CPAN::Shell->expand("Distribution",$distribution) - or $CPAN::Frontend->mydie("Unknowns distribution '$distribution'\n"); - my $build_dir = $d->{build_dir} or $CPAN::Frontend->mydie("Distribution has not been built yet, cannot proceed"); - my %contains = map {($_ => undef)} $d->containsmods; - my @m; - my $width = 16; - my $header = sub { - my($header,$value) = @_; - push @m, sprintf("%-s:%*s%s\n", $header, $width-length($header), "", $value); - }; - my $dni = CPAN::DistnameInfo->new($distribution); - my $dist = $dni->dist; - my $summary = $self->_guess_manpage($d,\%contains,$dist); - $header->("Name", "perl-$dist"); - my $version = $dni->version; - $header->("Version", $version); - $header->("Release", "1%{?dist}"); -#Summary: Template processing system -#Group: Development/Libraries -#License: GPL+ or Artistic -#URL: http://www.template-toolkit.org/ -#Source0: http://search.cpan.org/CPAN/authors/id/A/AB/ABW/Template-Toolkit-%{version}.tar.gz -#Patch0: Template-2.22-SREZIC-01.patch -#BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) - for my $h_tuple - ([Summary => $summary], - [Group => "Development/Libraries"], - [License =>], - [URL =>], - [BuildRoot => "%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)"], - [Requires => "perl(:MODULE_COMPAT_%(eval \"`%{__perl} -V:version`\"; echo \$version))"], - ) { - my($h,$v) = @$h_tuple; - $v = "unknown" unless defined $v; - $header->($h, $v); - } - $header->("Source0", sprintf( - "http://search.cpan.org/CPAN/authors/id/%s/%s/%s", - substr($distribution,0,1), - substr($distribution,0,2), - $distribution - )); - require POSIX; - my @xs = glob "$build_dir/*.xs"; # quick try - unless (@xs) { - require ExtUtils::Manifest; - my $manifest_file = "$build_dir/MANIFEST"; - my $manifest = ExtUtils::Manifest::maniread($manifest_file); - @xs = grep /\.xs$/, keys %$manifest; - } - if (! @xs) { - $header->('BuildArch', 'noarch'); - } - for my $k (sort keys %contains) { - my $m = CPAN::Shell->expand("Module",$k); - my $v = $contains{$k} = $m->cpan_version; - my $vspec = $v eq "undef" ? "" : " = $v"; - $header->("Provides", "perl($k)$vspec"); - } - if (my $prereq_pm = $d->{prereq_pm}) { - my %req; - for my $reqkey (keys %$prereq_pm) { - while (my($k,$v) = each %{$prereq_pm->{$reqkey}}) { - $req{$k} = $v; - } - } - if (-e "$build_dir/Build.PL" && ! exists $req{"Module::Build"}) { - $req{"Module::Build"} = 0; - } - for my $k (sort keys %req) { - next if $k eq "perl"; - my $v = $req{$k}; - my $vspec = defined $v && length $v && $v > 0 ? " >= $v" : ""; - $header->(BuildRequires => "perl($k)$vspec"); - next if $k =~ /^(Module::Build)$/; # MB is always only a - # BuildRequires; if we - # turn it into a - # Requires, then we - # would have to make it - # a BuildRequires - # everywhere we depend - # on *one* MB built - # module. - $header->(Requires => "perl($k)$vspec"); - } - } - push @m, "\n%define _use_internal_dependency_generator 0 -%define __find_requires %{nil} -%define __find_provides %{nil} -"; - push @m, "\n%description\n%{summary}.\n"; - push @m, "\n%prep\n%setup -q -n $dist-%{version}\n"; - if (-e "$build_dir/Build.PL") { - # see http://www.redhat.com/archives/rpm-list/2002-July/msg00110.html about RPM_BUILD_ROOT vs %{buildroot} - push @m, <<'EOF'; - -%build -%{__perl} Build.PL --installdirs=vendor --libdoc installvendorman3dir -./Build - -%install -rm -rf $RPM_BUILD_ROOT -./Build install destdir=$RPM_BUILD_ROOT create_packlist=0 -find $RPM_BUILD_ROOT -depth -type d -exec rmdir {} 2>/dev/null \; -%{_fixperms} $RPM_BUILD_ROOT/* - -%check -./Build test -EOF - } elsif (-e "$build_dir/Makefile.PL") { - push @m, <<'EOF'; - -%build -%{__perl} Makefile.PL INSTALLDIRS=vendor -make %{?_smp_mflags} - -%install -rm -rf $RPM_BUILD_ROOT -make pure_install DESTDIR=$RPM_BUILD_ROOT -find $RPM_BUILD_ROOT -type f -name .packlist -exec rm -f {} ';' -find $RPM_BUILD_ROOT -depth -type d -exec rmdir {} 2>/dev/null ';' -%{_fixperms} $RPM_BUILD_ROOT/* - -%check -make test -EOF - } else { - $CPAN::Frontend->mydie("'$distribution' has neither a Build.PL nor a Makefile.PL\n"); - } - push @m, "\n%clean\nrm -rf \$RPM_BUILD_ROOT\n"; - my $vendorlib = @xs ? "vendorarch" : "vendorlib"; - my $date = POSIX::strftime("%a %b %d %Y", gmtime); - my @doc = grep { -e "$build_dir/$_" } qw(README Changes); - my $exe_stanza = "\n"; - if (my $exe_files = $d->_exe_files) { - if (@$exe_files) { - $exe_stanza = "%{_mandir}/man1/*.1*\n"; - for my $e (@$exe_files) { - unless (CPAN->has_inst("File::Basename")) { - $CPAN::Frontend->mydie("File::Basename not installed, cannot continue"); - } - my $basename = File::Basename::basename($e); - $exe_stanza .= "/usr/bin/$basename\n"; - } - } - } - push @m, <<EOF; - -%files -%defattr(-,root,root,-) -%doc @doc -%{perl_$vendorlib}/* -%{_mandir}/man3/*.3* -$exe_stanza -%changelog -* $date <akoenig\@specfile.cpan.org> - $version-1 -- autogenerated by _specfile() in CPAN.pm - -EOF - - my $ret = join "", @m; - $CPAN::Frontend->myprint($ret); - open my $specout, ">", "perl-$dist.spec" or die; - print $specout $ret; - $CPAN::Frontend->myprint("Wrote perl-$dist.spec"); - $ret; + die "CPAN::Shell::_specfile() has been moved to CPAN::Plugin::Specfile::post_test()"; } #-> sub CPAN::Shell::report ; |