inc/ExtUtils/MakeMaker/Dist/Zilla/Develop.pm

   1 package ExtUtils::MakeMaker::Dist::Zilla::Develop;
   2 BEGIN {
   3   $ExtUtils::MakeMaker::Dist::Zilla::Develop::AUTHORITY = 'cpan:DOY';
   4 }
   5 {
   6   $ExtUtils::MakeMaker::Dist::Zilla::Develop::VERSION = '0.03';
   7 }
   8 use strict;
   9 use warnings;
  10 # ABSTRACT: create bare-bones Makefile.PL files for use with dzil
  11
  12 use ExtUtils::MakeMaker ();
  13
  14 sub import {
  15     warn <<'EOF';
  16
  17   ********************************* WARNING **********************************
  18
  19   This module uses Dist::Zilla for development. This Makefile.PL will let you
  20   run the tests, but you are encouraged to install Dist::Zilla and the needed
  21   plugins if you intend on doing any serious hacking.
  22
  23   ****************************************************************************
  24
  25 EOF
  26
  27     ExtUtils::MakeMaker->export_to_level(1, @_);
  28 }
  29
  30 {
  31     package # hide from PAUSE
  32         MY;
  33
  34     my $message;
  35     BEGIN {
  36         $message = <<'MESSAGE';
  37
  38   ********************************* ERROR ************************************
  39
  40   This module uses Dist::Zilla for development. This Makefile.PL will let you
  41   run the tests, but should not be used for installation or building dists.
  42   Building a dist should be done with 'dzil build', installation should be
  43   done with 'dzil install', and releasing should be done with 'dzil release'.
  44
  45   ****************************************************************************
  46
  47 MESSAGE
  48         $message =~ s/^(.*)$/\t\$(NOECHO) echo "$1";/mg;
  49     }
  50
  51     sub install {
  52         return <<EOF;
  53 install:
  54 $message
  55 \t\$(NOECHO) echo "Running dzil install for you...";
  56 \t\$(NOECHO) dzil install
  57 EOF
  58     }
  59
  60     sub dist_core {
  61         return <<EOF;
  62 dist:
  63 $message
  64 \t\$(NOECHO) echo "Running dzil build for you...";
  65 \t\$(NOECHO) dzil build
  66 EOF
  67     }
  68 }
  69
  70
  71 1;
  72
  73 __END__
  74
  75 =pod
  76
  77 =head1 NAME
  78
  79 ExtUtils::MakeMaker::Dist::Zilla::Develop - create bare-bones Makefile.PL files for use with dzil
  80
  81 =head1 VERSION
  82
  83 version 0.03
  84
  85 =head1 SYNOPSIS
  86
  87   # Makefile.PL
  88   use ExtUtils::MakeMaker::Dist::Zilla::Develop;
  89   WriteMakefile(NAME => 'Foo::Bar');
  90
  91 =head1 DESCRIPTION
  92
  93 L<Dist::Zilla> makes developing modules much easier by generating all kinds of
  94 boilerplate files, saving authors from having to write them by hand, but in
  95 some cases this can make developing more inconvenient. The most prominent
  96 example of this is with C<Makefile.PL> files - although the majority of
  97 distributions can be hacked on just by editing the files in a source control
  98 checkout and using C<prove> for testing, for some this isn't sufficient. In
  99 particular, distributions which use an auto-generated test suite and
 100 distributions which use XS both need special handling at build time before they
 101 will function, and with Dist::Zilla, this means running C<dzil build> and
 102 rebuilding after every change. This is tedious!
 103
 104 This module provides an alternative. Create a minimal C<Makefile.PL> in source
 105 control which handles just enough functionality for basic development (it can
 106 be as minimal as just what is in the L</SYNOPSIS>, but can also contain
 107 commands to generate your test suite, for example), and tell Dist::Zilla to
 108 replace it with a real C<Makefile.PL> when you're actually ready to build a
 109 real distribution. To do this, make sure you're still using the
 110 L<MakeMaker|Dist::Zilla::Plugin::MakeMaker> plugin, either directly or through
 111 a pluginbundle like L<@Basic|Dist::Zilla::PluginBundle::Basic>, and add the
 112 C<exclude_filename = Makefile.PL> option to your F<dist.ini> where you use
 113 C<[GatherDir]>.
 114
 115 In addition, this module also intercepts the C<install> and C<dist> rules in
 116 the generated Makefile to run the appropriate Dist::Zilla commands
 117 (C<dzil install> and C<dzil build>). This allows users to continue to use the
 118 C<perl Makefile.PL && make && make install> set of commands, and have the
 119 correct thing continue to happen.
 120
 121 Note that if you're using this module to ease testing of an XS distribution,
 122 you'll need to account for your module not containing a C<$VERSION> statement
 123 (assuming you're using the L<PkgVersion|Dist::Zilla::Plugin::PkgVersion>
 124 plugin). To do this, you should use an XSLoader invocation similar to this:
 125
 126   BEGIN {
 127       XSLoader::load(
 128           'Foo::Bar',
 129           $Foo::Bar::{VERSION} ? ${ $Foo::Bar::{VERSION} } : ()
 130       );
 131   }
 132
 133 This ensures that the C<$Foo::Bar::VERSION> glob isn't created if it didn't
 134 exist initially, since this can confuse XSLoader.
 135
 136 =head1 BUGS
 137
 138 No known bugs.
 139
 140 Please report any bugs to GitHub Issues at
 141 L<https://github.com/doy/extutils-makemaker-dist-zilla-develop/issues>.
 142
 143 =head1 SEE ALSO
 144
 145 L<ExtUtils::MakeMaker>
 146
 147 L<Dist::Zilla>
 148
 149 =head1 SUPPORT
 150
 151 You can find this documentation for this module with the perldoc command.
 152
 153     perldoc ExtUtils::MakeMaker::Dist::Zilla::Develop
 154
 155 You can also look for information at:
 156
 157 =over 4
 158
 159 =item * MetaCPAN
 160
 161 L<https://metacpan.org/release/ExtUtils-MakeMaker-Dist-Zilla-Develop>
 162
 163 =item * Github
 164
 165 L<https://github.com/doy/extutils-makemaker-dist-zilla-develop>
 166
 167 =item * RT: CPAN's request tracker
 168
 169 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=ExtUtils-MakeMaker-Dist-Zilla-Develop>
 170
 171 =item * CPAN Ratings
 172
 173 L<http://cpanratings.perl.org/d/ExtUtils-MakeMaker-Dist-Zilla-Develop>
 174
 175 =back
 176
 177 =head1 AUTHOR
 178
 179 Jesse Luehrs <doy@tozt.net>
 180
 181 =head1 COPYRIGHT AND LICENSE
 182
 183 This software is copyright (c) 2014 by Jesse Luehrs.
 184
 185 This is free software; you can redistribute it and/or modify it under
 186 the same terms as the Perl 5 programming language system itself.
 187
 188 =cut