More tutorial work.

ingydotnet · Dec 18, 2014 · 849dfa7 · 849dfa7
1 parent 76ea880
commit 849dfa7
Showing 1 changed file with 104 additions and 16 deletions.
diff --git a/doc/Inline/Module/Tutorial.swim b/doc/Inline/Module/Tutorial.swim
@@ -22,7 +22,7 @@ this.
 
 No matter which framework you use to make modules ([ExtUtils::MakeMaker],
 [Dist::Zilla]) etc, you'll need to add a little metadata to the controls. For
-now we'll just show `Makefile.PL` way:
+now we'll just show `Makefile.PL` ([ExtUtils::MakeMaker]) way:
 
   use lib 'inc';
   use ExtUtils::MakeMaker;
@@ -40,15 +40,44 @@ now we'll just show `Makefile.PL` way:
     },
   );
 
-
 So you need to use `Inline::Module` and add a `postamble` section with an
 `inline` section (with at least a `module` name) to `WriteMakefile`. The
 arguments specify the information the [Inline::Module] needs to do the right
-things.
+things. The `stub` and `ilsm` values above are the defaults, so not really
+needed in that example. All the values for those keys can be either a string or
+an array ref of strings (ie single or multiple values).
 
 NOTE: You also need to add `inc` to @INC, even if doesn't exist while you are
 developing and testing. It will exist when you ship it to CPAN, and the `make
-install` process needs it to work properly.
+install` process needs it to work properly. The Makefile.PL or Build.PL will
+actually die if you don't put `inc` first in `@INC`.
+
+See [Alt::Acme::Math::XS::EUMM] for a working example on CPAN.
+
+== Meta Values
+
+Just to reiterate, whether you are using [ExtUtils::MakeMaker],
+[Module::Build], [Module::Install], [Dist::Zilla] or [Zilla::Dist], you need to
+specify 3 Meta values:
+
+- `module`
+
+  One or more module names that live under the `lib` directory and use Inline
+  inside. This value is required in all cases (no default).
+
+- `stub`
+
+  One or more names of /stub/ modules, that are referenced in the `module`
+  modules listed above. The default is to add '::Inline' to each value of the
+  `module` keyword.
+
+- `ilsm`
+
+  A list of the Inline Language Support Modules (ILSMs) needed. Usually just
+  one of [Inline::C] (the default) or [Inline::CPP].
+
+Each framework list above has a slightly different way to express the values,
+but they will all seem normal in that framework. See below.
 
 == The Module
 
@@ -107,8 +136,19 @@ extension libraries. As long the shared library stuff gets built into the
 
 == Automatic Stub Generation
 
-If you don't want to keep the generated stub code around, there is a way to
-have it autogenerated. Just set `PERL5OPT` like this:
+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.
+
+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.
+
+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'
 
@@ -117,7 +157,11 @@ 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.
+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
 
@@ -198,25 +242,67 @@ popular CPAN build systems, like [Dist::Zilla].
 
 == [Dist::Zilla]
 
-Let's start with this one, since it is so popular…
+For [Dist::Zilla], install [Dist::Zilla::Plugin::InlineModule] and add this to
+your `dist.ini` file:
 
-*To be continued…*
+  [InlineModule]
+  module = Acme::Math::XS
+  stub = Acme::Math::XS::Inline
+  ilsm = Inline::C
+
+Again, the last 2 lines are defaults. You can use any of the keywords multiple
+times.
+
+See [Alt::Acme::Math::XS::DistZilla] for a working example on CPAN.
 
 == [Module::Build]
 
-*To be continued…*
+Install [Module::Build::InlineModule] and write a `Build.PL` file that looks
+like this:
+
+  use lib 'inc';
+  use Module::Build::InlineModule;
+
+  Module::Build::InlineModule->new(
+    dist_name => 'Alt-Acme-Math-XS-ModuleBuild',
+    ...
+    inline => {
+      module => 'Acme::Math::XS',
+      stub => 'Acme::Math::XS::Inline',
+      ilsm => 'Inline::C',
+    },
+  )->create_build_script();
+
+See [Alt::Acme::Math::XS::ModuleBuild] for a working example on CPAN.
 
 == [Module::Install]
 
-*To be continued…*
+Install [Module::Build::InlineModule] and write a `Makefile.PL` that looks like
+this:
+
+  use inc::Module::Install;
+
+  name 'Alt-Acme-Math-XS-ModuleInstall';
+  ...
+  inline module => 'Acme::Math::XS';
+  inline stub => 'Acme::Math::XS::Inline';
+  inline ilsm => 'Inline::C';
+
+  WriteAll;
+
+See [Alt::Acme::Math::XS::ModuleInstall] for a working example on CPAN.
 
 == [Zilla::Dist]
 
-*To be continued…*
+Just add these lines to your Meta file:
 
-== [Distar]
+=zild:
+  inline:
+    module: Acme::Math::XS
+    stub: Acme::Math::XS::Inline
+    ilsm: Inline::C
 
-*To be continued…*
+See [Alt::Acme::Math::XS::ZillaDist] for a working example on CPAN.
 
 = External Files
 
@@ -233,8 +319,10 @@ Things that change when you use `C++`…
 = Using languages other than `C` and `C++`
 
 It /may/ be possible (though highly experimental) to use other Inline Language
-Support Modules (ILSMs), like Java or Python. This section will talk about
-that…
+Support Modules (ILSMs), like Java or Python. Simply list your ILSM of choice
+in the Meta section, and see what happens.
+
+Report any issues to: https://github.com/ingydotnet/inline-module-pm/issues
 
 = Document Status