Remove autostub feature.

Deprecate it with informative die for now.
ingydotnet · Dec 27, 2014 · 7c9595c · 7c9595c
1 parent 02206ac
commit 7c9595c
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 93 deletions.
diff --git a/ReadMe.pod b/ReadMe.pod
@@ -32,6 +32,9 @@ In C<Makefile.PL>:
       postamble => {
         inline => {
           module => 'Acme::Math::XS',
+          stub => 'Acme::Math::XS::Inline',
+          ilsm => 'Inline::C',
+          makestub => 1,
         },
       },
     );
@@ -79,24 +82,36 @@ an array ref of multiple modules.
 Optional. This is the Inline Language Support Module (ilsm) that you are
 using. It defaults to L<Inline::C>. It can be an array ref of multiple ilsm-s.
 
+=item C<makestub>
+
+    makestub => 1,
+
+This will cause the stubs to be updated every time the C<Makefile.PL> is run.
+
 =back
 
 =head1 STUB MODULE GENERATION
 
 During development, L<Inline::Module> needs to generate I<stub> modules. For
 the case in the synopsis, it would need to generate C<Acme::Math::XS::Inline>.
-There a few similar but different ways to do this:
+There a couple ways to do this. The explicit way is:
 
     perl -MInline::Module=makestub,Acme::Math::XS::Inline
 
-or:
+You can also add C<< makestub => 1 >> to your C<Makefile.PL> inline section.
+Every time you run C<perl Makefile.PL> as an author, the stubs will be
+generated under the C<lib/> directory.
 
-    export PERL5OPT='-MInline::Module=autostub'
-    prove -lv t/
+=head1 GENERATED FILES
 
-or:
+When Inline is invoked it will use the C<.inline/> directory to do it. This is
+temporary build cache directory. You may want to add C<.inline/> to your
+C<.gitignore> (or similar) file.
 
-    perl Makefile.PL
+You may also want to add the stub file paths to C<.gitignore>. You may also
+want to consider committing them. Even though they are generated code, they
+are very small and should almost never change. Committing them may be easier
+for your collaborating developers.
 
 =head1 TPF GRANT
 

diff --git a/doc/Inline/Module.swim b/doc/Inline/Module.swim
@@ -23,6 +23,9 @@ In `Makefile.PL`:
     postamble => {
       inline => {
         module => 'Acme::Math::XS',
+        stub => 'Acme::Math::XS::Inline',
+        ilsm => 'Inline::C',
+        makestub => 1,
       },
     },
   );
@@ -69,22 +72,34 @@ Arguments are key/value pairs.
   using. It defaults to [Inline::C]. It can be an array ref of multiple
   ilsm-s.
 
+- `makestub`
+
+    makestub => 1,
+
+  This will cause the stubs to be updated every time the `Makefile.PL` is run.
+
 = Stub Module Generation
 
 During development, [Inline::Module] needs to generate /stub/ modules. For the
 case in the synopsis, it would need to generate `Acme::Math::XS::Inline`.
-There a few similar but different ways to do this:
+There a couple ways to do this. The explicit way is:
 
   perl -MInline::Module=makestub,Acme::Math::XS::Inline
 
-or:
+You can also add `makestub => 1` to your `Makefile.PL` inline section. Every
+time you run `perl Makefile.PL` as an author, the stubs will be generated under
+the `lib/` directory.
 
-  export PERL5OPT='-MInline::Module=autostub'
-  prove -lv t/
+= Generated Files
 
-or:
+When Inline is invoked it will use the `.inline/` directory to do it. This is
+temporary build cache directory. You may want to add `.inline/` to your
+`.gitignore` (or similar) file.
 
-  perl Makefile.PL
+You may also want to add the stub file paths to `.gitignore`. You may also want
+to consider committing them. Even though they are generated code, they are very
+small and should almost never change. Committing them may be easier for your
+collaborating developers.
 
 = TPF Grant
 

diff --git a/doc/Inline/Module/Tutorial.swim b/doc/Inline/Module/Tutorial.swim
@@ -137,32 +137,16 @@ extension libraries. As long the shared library stuff gets built into the
 == Automatic Stub Generation
 
 The stub module is generated code, and many people don't like to commit
-generated code. There are a few ways to deal with this.
+generated code. There are a couple ways to deal with this.
 
 The first is just to commit it anyway, because it only has to change very
 rarely; when you install a new Inline::Module whose API version has changed.
-You will get an error telling you to regenerate the stub. One main advantage of
-this is that your project collaborators don't need to know about generating the
-stub.
+You will get an error telling you to regenerate the stub. One main advantage
+of this is that your project collaborators don't need to know about generating
+the stub.
 
 The second way is to ignore it in your source control (ie `.gitignore` file).
 
-There is another way that that is called *autostubbing*. Just set `PERL5OPT`
-like this:
-
-  export PERL5OPT='-MInline::Module=autostub,Acme::Math::XS::Inline'
-
-This will add a CODE ref to @INC that will generate stub modules just in time,
-as in-memory files. For instance if you just run your tests with:
-
-  prove -l t/
-
-the stub modules will be autogenerated, just-in-time, in memory. You'll never
-see them on disk or worry about needing to commit or ignore them. Then again,
-you have to make sure the environment variable is set.
-
-TMTOWTDI! Choose the stubbing method that suits you best.
-
 == Testing
 
 There are a few ways to test stuff and I'll describe them here. They should be

diff --git a/lib/Inline/Module.pm b/lib/Inline/Module.pm
@@ -16,7 +16,6 @@ sub DEBUG { if (DEBUG_ON) { print "DEBUG >>> ", sprintf(@_), "\n" }}
 
 #------------------------------------------------------------------------------
 # This import serves multiple roles:
-# - -MInline::Module=autostub
 # - ::Inline module's proxy to Inline.pm
 # - Makefile.PL postamble
 # - Makefile rule support
@@ -36,22 +35,26 @@ sub import {
     }
     elsif ($program eq 'Build.PL') {
         $class->check_inc_inc($program);
+        return;
     }
 
     return unless @_;
     my $cmd = shift;
 
     return $class->handle_stub($stub_module, @_)
         if $cmd eq 'stub';
-    return $class->handle_autostub(@_)
-        if $cmd eq 'autostub';
     return $class->handle_makestub(@_)
         if $cmd eq 'makestub';
     return $class->handle_distdir(@ARGV)
         if $cmd eq 'distdir';
     return $class->handle_fixblib()
         if $cmd eq 'fixblib';
 
+    # TODO: Deprecated 12/26/2014. Remove this in a month.
+    die "Inline::Module 'autostub' no longer supported. " .
+        "Remove this option from PERL5OPT."
+            if $cmd eq 'autostub';
+
     die "Unknown Inline::Module::import argument '$cmd'"
 }
 
@@ -183,45 +186,6 @@ sub handle_makestub {
     exit 0;
 }
 
-sub handle_autostub {
-    my ($class, @args) = @_;
-
-    # Don't mess with Perl tools, while using PERL5OPT and autostub:
-    return unless
-        $0 eq '-e' or
-        defined $ENV{_} and $ENV{_} =~ m!/prove[^/]*$!;
-    # Don't autostub in the distdir:
-    return if -e './inc/Inline/Module.pm';
-
-    DEBUG_ON && DEBUG "Inline::Module::autostub(@_)";
-
-    require lib;
-    lib->import('lib');
-
-    my %autostub_modules;
-    for my $arg (@args) {
-        if ($arg =~ m!::!) {
-            $autostub_modules{$arg} = 1;
-        }
-        else {
-            croak "Unknown 'autostub' argument: '$arg'";
-        }
-    }
-
-    push @INC, sub {
-        my ($this, $module) = @_;
-        delete $ENV{PERL5OPT};
-
-        $module =~ s!\.pm$!!;
-        $module =~ s!/!::!g;
-        $autostub_modules{$module} or return;
-
-        my $code = $class->proxy_module($module);
-        open my $fh, '<', \$code;
-        return $fh;
-    }
-}
-
 sub handle_distdir {
     my ($class, $distdir, @args) = @_;
     my $stub_modules = [];
@@ -359,9 +323,7 @@ sub proxy_module {
     my ($class, $module) = @_;
 
     return <<"...";
-# DO NOT EDIT
-#
-# GENERATED BY: Inline::Module $Inline::Module::VERSION
+# DO NOT EDIT. GENERATED BY: Inline::Module
 #
 # This module is for author-side development only. When this module is shipped
 # to CPAN, it will be automagically replaced with content that does not
@@ -381,19 +343,16 @@ use Inline::Module stub => '$API_VERSION';
 sub dyna_module {
     my ($class, $module) = @_;
     return <<"...";
-# DO NOT EDIT
-#
-# GENERATED BY: Inline::Module $Inline::Module::VERSION
+# DO NOT EDIT. GENERATED BY: Inline::Module $Inline::Module::VERSION
 
 use strict; use warnings;
 package $module;
 use base 'DynaLoader';
 bootstrap $module;
-
 1;
 ...
 
-# XXX - think about this later:
+# TODO: Add XS VERSION checking support:
 # our \$VERSION = '0.0.5';
 # bootstrap $module \$VERSION;
 }

diff --git a/note/ToDo b/note/ToDo
@@ -11,8 +11,6 @@
 - Find out why `make test` invokes Inline::Module in a distdir
   - Only `make` should do that
 
-- Disable autostub when inc/ exists (ie during distdir time)
-
 == Soon
 
 - Check VERSION in XS

diff --git a/test/devel/generate-stub.t b/test/devel/generate-stub.t
@@ -10,15 +10,6 @@ BAIL_ON_FAIL
   rm -fr lib
 }
 
-{
-  (
-    export PERL5OPT=-MInline::Module=autostub,Foo::Bar
-    perl -e 'use Foo::Bar'
-  )
-  pass "Stub was auto-generated as IO::String object"
-  # ok "`[ ! -e lib ] && [ ! -e blib ]`" "Neither lib nor blib exist"
-}
-
 done_testing
 teardown