module-build-general — General discussion about Module::Build project

Re: [Module::Build] ANNOUNCE: 0.21 released

[Randy W. S. <Ra...@Th...>]

On 10/16/2003 8:20 PM, Ken Williams wrote:
> I'm applying a patch to do so, here's what it looks like.
> 
>  -Ken
> 
> --- lib/Module/Build/Base.pm    16 Oct 2003 01:26:23 -0000    1.213
> +++ lib/Module/Build/Base.pm    17 Oct 2003 00:15:47 -0000    1.214
> @@ -1216,7 +1216,9 @@
>    }
> 
>    return {} unless -d $dir;
> -  return { map {$_, $_} @{ $self->rscan_dir($dir, qr{\.$type$}) } };
> +  return { map {$_, $_}
> +       map $self->localize_file_path($_),
> +       @{ $self->rscan_dir($dir, qr{\.$type$}) } };
>  }
> 
>  sub localize_file_path {
> 

It's a good thing I got a late start--otherwise, I'd a had to do that. ;)

That fixed it.

Thanks,
Randy.

Re: [Module::Build] M::B 0.21 OSX warnings

[Ken W. <ke...@ma...>]

On Thursday, October 16, 2003, at 07:41  PM, Ken Williams wrote:

>
> I didn't see this because I'm using a newer version of File::Spec, I 
> guess.  What line in t/manifypods.t is causing the problem?
>

Ah, I see now.  It's this:

  my %distro = (
               'bin/sample.pl' => "sample.pl.$man{ext1}",
               'lib/Sample/Docs.pod' => "Sample$man{sep}Docs.$man{ext3}",
               'lib/Sample.pm' => "Sample.$man{ext3}",
               'script' => '',
               'lib/Sample/NoPod.pm' => '',
              );
  $_ = $m->localize_file_path($_) foreach %distro;


We shouldn't be passing in '' to localize_file_path() either, since 
that's not a valid path.  We only need to localize the keys anyway, not 
the values.

I'll apply the following patch too, in addition to yours.

  -Ken

--- t/manifypods.t	11 Oct 2003 02:39:57 -0000	1.6
+++ t/manifypods.t	17 Oct 2003 00:52:26 -0000
@@ -39,7 +39,8 @@
  	      'script' => '',
  	      'lib/Sample/NoPod.pm' => '',
  	     );
-$_ = $m->localize_file_path($_) foreach %distro;
+# foreach(keys %foo) doesn't give proper lvalues on 5.005, so we use 
the ugly way
+%distro = map {$m->localize_file_path($_), $distro{$_}} keys %distro;

  $m->dispatch('build');

Re: [Module::Build] M::B 0.21 OSX warnings

[Ken W. <ke...@ma...>]

On Thursday, October 16, 2003, at 10:19  AM, Chris Dolan wrote:

> I saw a bunch of warnings from 'Build test' on Mac OSX, perl 5.8.1, 
> M::B v0.21.  These occur in manifypods.t, and originate from 
> File::Spec::Unix::canonpath() getting undef and not handling it 
> properly.
>
> First, I submitted a patch to File::Spec to better handle the undef.  
> But, we really shouldn't be handing undef to canonpath in the first 
> place.
>
> I discovered the source of the undef by running:
>    perl -w -Mblib -MCarp 
> -e'$SIG{__WARN__}=\&confess;do"t/manifypods.t"'
> which showed the cause to be localize_file_path() called with '' as 
> the path.
>
> The following patch prevents localize_file_path from trying to do any 
> work if the path is already localized by virtue of being relative.
>
> Chris
>
> --- lib/Module/Build/Base.pm.orig      2003-10-16 09:29:52.000000000 
> -0500
> +++ lib/Module/Build/Base.pm    2003-10-16 10:06:32.000000000 -0500
> @@ -1221,6 +1221,7 @@
>
>  sub localize_file_path {
>    my ($self, $path) = @_;
> +  return $path unless ($path =~ m{/});
>    return File::Spec->catfile( split qr{/}, $path );
>  }
>

Looks good, I'll apply.

I didn't see this because I'm using a newer version of File::Spec, I 
guess.  What line in t/manifypods.t is causing the problem?

  -Ken

Re: [Module::Build] Array form of do_system causing problems

[Ken W. <ke...@ma...>]

On Thursday, October 16, 2003, at 01:40  PM, Chris Dolan wrote:

> I build packages like this:
>    Build dist gzip="gzip -f --best"
>
> This causes Module::Build::Platform::Unix to emit:
>    $self->do_system("gzip -f --best", "$dir.tar");
> which bombs because there is no program called "gzip -f --best".
>
> Perhaps do_system should check if there are spaces in the name of the 
> executable?  That might not be the right thing on a Windows box, or 
> any other platform where spaces commonly occur in directory names...
>
> Regardless of that complication, here's a new version of do_system.  
> It fixes the bug, but reintroduces the shell complications we were 
> trying to avoid.

Yeah, and it specifically does the wrong thing if your gzip is
something like "/My Macintosh/My Stuff/gzip".

The 'gzip' parameter is intended to be the path to gzip, not the path 
plus arguments.  But if it's important to take arguments, that could be 
added.

  -Ken

Re: [Module::Build] ANNOUNCE: 0.21 released

[Ken W. <ke...@ma...>]

On Thursday, October 16, 2003, at 08:25  AM, Ken Williams wrote:

>
>
> It looks like File::Find isn't localizing the path to use backslashes 
> on your system.  Is this an older File::Find?
>
> Maybe I should explicitly the results of rscan_dir() using 
> localize_file_path() inside _find_file_by_type().

I'm applying a patch to do so, here's what it looks like.

  -Ken

--- lib/Module/Build/Base.pm	16 Oct 2003 01:26:23 -0000	1.213
+++ lib/Module/Build/Base.pm	17 Oct 2003 00:15:47 -0000	1.214
@@ -1216,7 +1216,9 @@
    }

    return {} unless -d $dir;
-  return { map {$_, $_} @{ $self->rscan_dir($dir, qr{\.$type$}) } };
+  return { map {$_, $_}
+	   map $self->localize_file_path($_),
+	   @{ $self->rscan_dir($dir, qr{\.$type$}) } };
  }

  sub localize_file_path {

[Module::Build] Array form of do_system causing problems

[Chris D. <ch...@cl...>]

I build packages like this:
    Build dist gzip="gzip -f --best"

This causes Module::Build::Platform::Unix to emit:
    $self->do_system("gzip -f --best", "$dir.tar");
which bombs because there is no program called "gzip -f --best".

Perhaps do_system should check if there are spaces in the name of the 
executable?  That might not be the right thing on a Windows box, or any 
other platform where spaces commonly occur in directory names...

Regardless of that complication, here's a new version of do_system.  It 
fixes the bug, but reintroduces the shell complications we were trying 
to avoid.

sub do_system {
   my ($self, @cmd) = @_;
   print "@cmd\n";
   if ($cmd[0] =~ /\s/) {
     return !system("@cmd");
   } else {
     return !system(@cmd);
   }
}

Chris
--
Chris Dolan, Software Developer, Clotho Advanced Media Inc.
608-294-7900, 211 S Paterson Suite 260, Madison WI 53703

[Module::Build] M::B 0.21 OSX warnings

[Chris D. <ch...@cl...>]

I saw a bunch of warnings from 'Build test' on Mac OSX, perl 5.8.1, 
M::B v0.21.  These occur in manifypods.t, and originate from 
File::Spec::Unix::canonpath() getting undef and not handling it 
properly.

First, I submitted a patch to File::Spec to better handle the undef.  
But, we really shouldn't be handing undef to canonpath in the first 
place.

I discovered the source of the undef by running:
    perl -w -Mblib -MCarp -e'$SIG{__WARN__}=\&confess;do"t/manifypods.t"'
which showed the cause to be localize_file_path() called with '' as the 
path.

The following patch prevents localize_file_path from trying to do any 
work if the path is already localized by virtue of being relative.

Chris

--- lib/Module/Build/Base.pm.orig      2003-10-16 09:29:52.000000000 
-0500
+++ lib/Module/Build/Base.pm    2003-10-16 10:06:32.000000000 -0500
@@ -1221,6 +1221,7 @@

  sub localize_file_path {
    my ($self, $path) = @_;
+  return $path unless ($path =~ m{/});
    return File::Spec->catfile( split qr{/}, $path );
  }

--
Chris Dolan, Software Developer, Clotho Advanced Media Inc.
ch...@cl..., 294-7900, 211 S Paterson, Madison WI 53703

Re: [Module::Build] M::B actions design

[Ken W. <ke...@ma...>]

On Thursday, October 16, 2003, at 05:50  AM, Steve Purkis wrote:

> I think they all stem from the fact that M::B was not written with 
> this design in mind, so it would take a lot of effort to refactor 
> things.  It certainly would involve a *lot* of changes, and little (if 
> any) backwards compatibility.  There is potentially a huge gain as far 
> as simplicity is concerned, but it may be more work than it's worth.

I think we could do it without too much difficulty, actually.  I'll 
ponder it...

This is something I've been wanting to do in the back of my mind too.  
It sure would be nice to have local-only actions, easily 
redistributable actions, etc.

  -Ken

[Module::Build] M::B actions design

[Steve P. <sp...@qu...>]

On Thursday, October 16, 2003, at 12:06  am, Randy W. Sims wrote:

> There is another issue here in that the list of actions is growing 
> quite large, and M::B is (IMHO) turning into a large monolithic 
> module. Would it be worth the effort to re-architect actions, so that 
> they are plug-ins (M::B::ACTION::html, M::B::ACTION::dist). This would 
> keep M::B from becoming monolithic and would allow others to develop 
> plug-ins to expand functionality without requiring invasive code 
> changes.

Yes, M::B: is becoming quite monolithic.  So was MakeMaker.  The main 
difference I find between the two is that M::B is much easier to read, 
understand and extend.

Splitting out the actions is not a bad idea - I bounced a similar one 
around with some friends in the past:

	package My::Action;

	use base qw( Module::Build::Action );
	use constant depends_on => qw( foo, bar );

	sub builder { }	# the parent M::B obj

	sub check_dependencies {
		...
	}

	sub execute {
		...
	}

There are a few problems with these ideas: how do you write platform 
specific code?  One answer is to sub-class each action, or write a 
method for each platform in the action's class.  That could work, but 
it could also get a bit hairy.

Then, how do you access commonly used methods?  A solution might be to 
bung all these methods in a common place that everybody inherits from, 
say M::B::Common:

	M::B::Common
	    |
	    +- M::B::Base
	    |
	    +- M::B::Action
	          |
		      +- M::B::Action::Foo

And, how do you subclass actions?  If I want to write my own 'install' 
action, how do I do it?  At the moment, I sub-class M::B and do it 
there.  Sub-classing each action is easy, but how do you get M::B to 
use them?  One way is to say M::B::Base must have stub methods for each 
action so that they can be overridden.

I think they all stem from the fact that M::B was not written with this 
design in mind, so it would take a lot of effort to refactor things.  
It certainly would involve a *lot* of changes, and little (if any) 
backwards compatibility.  There is potentially a huge gain as far as 
simplicity is concerned, but it may be more work than it's worth.

That said...

> This is only half thought-out, so I'm not sure if it's practical. For 
> example, I don't know how easy it would be to come up with an 
> interface so that actions could get info from M::B without digging 
> into the internals.

Making them plugins is a good idea, but it's even more complicated.


> <thinking out loud>
>
> Each module would contain one or more actions.

I'd limit it to one a package.  That way you can get the action name 
from the package name itself:

	'build' => M::B::Action::Build


>  M::B would search for plugin actions at startup, querying each module 
> for a list of supported actions.

So M::B builds up a list of actions and their classes?  And I assume it 
would search particular sub-classes, starting with 
Module::Build::Action?  Maybe that's how you could do user level 
sub-classing: push on your own 'search' package:

	@M::B::SearchPackages = qw( My::Action Module::Build::Action );

Then it would find your actions first.  If you have 1 action per 
package, then M::B already knows what it does.  So eventually you build 
a map:

	$build->{ActionClassMap} = {
		Build   => 'My::Action::Build'
		Install => 'M::B::Action::Install'
	};

Then to dispatch, you do something like:

	sub dispatch {
		my $self   = shift;
		my $action = shift;
		my $aclass = $self->{ActionClassMap}->{$action} || die;
		$aclass->new->builder( $self )->check_dependencies->execute;
	}


>  Each action knows what parameters it accepts and can display its own 
> help info. There could be a helper class for generating actions and 
> linking them by dependencies, i.e.
>
> my $action = new M::B::ACTION::Builder(
>   name => 'My_lib',
>   code => sub {},
>   ...
> );

Dunno if that's needed - M::B already does it.


> my $top = new M::B::ACTION::Builtin( name => 'all' );
> $top->add_dependency($action);

I'd go with 'M::B::Action::All', it's more consistent.

Food for thought...

-Steve

Re: [Module::Build] PROPOSAL: M::B should install HTML documentation

[Steve P. <sp...@qu...>]

On Thursday, October 16, 2003, at 12:06  am, Randy W. Sims wrote:

> On 10/15/2003 6:23 PM, Michael G Schwern wrote:
>> On Wed, Oct 15, 2003 at 10:39:12AM -0500, Chris Dolan wrote:
>>> On Wednesday, October 15, 2003, at 06:12  AM, <kev...@ub...> 
>>> wrote:
>>>
>>>> I would love to see M::B support building HTML documentation.
>>>
>>>
>>> I have built a module to do exactly that.  It is not yet published 
>>> to CPAN, but here's the documentation.  The main work left to do is 
>>> to tweak some of the defaults and to get a Pod::Html regression bug 
>>> fixed (doesn't handle nested =item tags right, grr...)
>> A few things to note:
>> 5.8.1 finally included Config options for HTML installation 
>> directories.
>> So look for $Config{install*html*dir} (installhtml1dir, 
>> installhtml3dir,
>> installsitehtml1dir, etc...) and if they're set, Module::Build should
>> install HTML docs by default.
>
> IIRC, some of those have been around longer but where unused; I don't 
> think anyone ever agreed on where html docs should be installed.
>
>> I would avoid passing Pod::Html specific flags into Module::Build.  
>> Have
>> a plan ready to map them in case Pod::Html is replaced.  The names of
>> the Pod::Html arguments are fairly generic, so its sort of moot.  
>> Just keep your upgrade path open in case one of the future POD->HTML 
>> modules on CPAN matures.
>
> ActiveState distributions have their own means of generating html from 
> pod (the ActivePerl::DocTools module), if that module is present you 
> probably should use it or atleast ask the user.

I'd argue that it's up to ActiveState to override M::B's behaviour in 
this case.  But I've no knowledge of how ActivePerl::DocTools works (I 
can't find it on CPAN), so I don't know how feasible that is.


> There is another issue here in that the list of actions is growing 
> quite large, and M::B is (IMHO) turning into a large monolithic > module.

This too belongs in another thread :).

In context of HTML docs, I think it makes sense to support it 
(especially if it is supported in perl-5.8.1), and I don't think it 
would be the straw that broke the camel's back.

-Steve

Re: [Module::Build] make test failure report (Cygwin)

[Randy W. S. <Ra...@Th...>]

On 10/15/2003 8:41 AM, Randy W. Sims wrote:

> Greg Matheson wrote:
> 
>> On Wed, 15 Oct 2003, Greg Matheson wrote:
>>
>>
>>> Failed Test Stat Wstat Total Fail  Failed  List of Failed
>>> ------------------------------------------------------------------------------- 
>>>
>>> t/compat.t                41   18  43.90%  5-8 11 14 18-21 24 27 
>>> 31-34 37 40
>>
>>
>>
>> Sorry, I didn't have make installed. I guess I've been installing all 
>> my modules with Module::Build recently.
>>
>> Here is the output after installing make.
>>
> 
> <snipped verbose output>
> 
>> All tests successful.
>> Files=1, Tests=41, 135 wallclock secs ( 0.00 cusr +  0.00 csys =  0.00 
>> CPU)
>>
> 
> I think the solution is to guard t/compat.t with a test 
> for the make utility and warn if it's not found (but not error)?
> 

patch attached.

Randy.

Re: [Module::Build] ANNOUNCE: 0.21 released

[Randy W. S. <Ra...@Th...>]

I forgot to attatch the output.

Re: [Module::Build] ANNOUNCE: 0.21 released

[Randy W. S. <Ra...@Th...>]

On 10/15/2003 9:49 PM, Ken Williams wrote:

> Hey,
> 
> I just release version 0.21 of Module::Build to CPAN and Sourceforge.  
> Here are the changes since 0.20 (they include the changes from a couple 
> of beta versions):
> 
> 0.21  Wed Oct 15 20:47:05 CDT 2003
> 

A test failure creeped in on Windows (not Cygwin) at t/install.t #19.

Any ideas what might of changed here?

There is also something going on at t/runthrough.t #20. I think I 
upgraded the Tar module recently, that may have something to do with it 
as it has always been troublesome on Windows.

Randy.

Re: [Module::Build] [PATCH] make test failure report (Cygwin)

[Randy W. S. <Ra...@Th...>]

On 10/15/2003 8:46 AM, Ken Williams wrote:

> 
>> BTW, wouldn't it be better to use Pod::Parser in the dist_* routines 
>> for more acurate results?
> 
> 
> Probably so, yeah.  Is that a core module?
> 
>  -Ken

Yeah, though I'm not sure when it was added. The attached patch should 
be safe though.

Randy.

Re: [Module::Build] PROPOSAL: M::B should install HTML documentation

[Michael G S. <sc...@po...>]

On Wed, Oct 15, 2003 at 07:06:49PM -0400, Randy W. Sims wrote:
> >5.8.1 finally included Config options for HTML installation directories.
> >So look for $Config{install*html*dir} (installhtml1dir, installhtml3dir,
> >installsitehtml1dir, etc...) and if they're set, Module::Build should
> >install HTML docs by default.
> 
> IIRC, some of those have been around longer but where unused; I don't 
> think anyone ever agreed on where html docs should be installed.

Configure finally asks you where you want to install HTML documentation.  
The default is not to install.


-- 
Michael G Schwern        sc...@po...  http://www.pobox.com/~schwern/
Abandon failing tactics.

[Module::Build] ANNOUNCE: 0.21 released

[Ken W. <ke...@ma...>]

Hey,

I just release version 0.21 of Module::Build to CPAN and Sourceforge.  
Here are the changes since 0.20 (they include the changes from a couple 
of beta versions):

0.21  Wed Oct 15 20:47:05 CDT 2003

  - Added a have_c_compiler() method.

  - Added documentation for the requires(), recommends(),
    build_requires(), and conflicts() methods.

  - On Unix platforms, we now create the "Build" script with a #! line
    matching the perl interpreter that was used to invoke the Build.PL
    script, rather than whatever is in $Config{startperl}.  This avoids
    a potential warning about the interpreters not matching. [Spotted
    by Ken Y. Clark]

  - The Unix version now uses the safer multi-argument form of system()
    when building distribution tarballs.

  - Added a regression test for the 'dist' action to the t/runthrough.t
    test.

  - Fixed a problem with File::Spec usage when creating the names of
    'libdoc' manual pages - the code wasn't dealing with the volume or
    file portions correctly on certain platforms.

  - When creating the names of the 'libdoc' manual pages, we no longer
    assume that pods are under the hard-coded paths 'blib/lib' or
    'blib/arch'.

  - Fixed a crashing bug that could sometimes occur when the
    distribution contained no 'lib' directory. [Chris Dolan]

  - Fixed a crashing bug that happened when the user had .PL files in
    the lib/ directory and didn't explicitly name them in a hash
    reference to the new() constructor. [Chris Reinhardt, bug #4036]

  - .PL files are now passed the names of their target file(s) on the
    command line when they run.

  - When YAML.pm wasn't installed, t/runthrough.t wasn't properly
    skipping some tests that required YAML.  This is now fixed.
    [Stephen J. Smith]

  - Added documentation for the dist_version() and dist_name()
    methods. [Spotted by Johan Vromans]

  - Existing values in $ENV{HARNESS_PERL_SWITCHES} are now respected
    and not squashed when we run the 'test' action. [Paul Johnson]

  - On cygwin, the separator string for manual page names has been set
    to '.'.  Previously it was '::', inherited from Unix. [Yitzchak
    Scott-Thoennes]

  - Avoid a warning when Build.PL is run (i.e. when the new() method is
    called) and no MANIFEST file exists. [Michael Schwern and Kevin
    Ruscoe]

  - Added documentation for the 'code' and 'docs' actions. [Steve
    Purkis and Mark Stosberg]

  - The internal method compile_support_files() has been renamed to
    process_support_files() in order to make it consistent with other
    processing methods.  Note that it was never documented using the
    old name.  It's still not documented, actually.  Maybe later.

  - Skip the 'write' pseudo-entry in the 'diff' action's installation
    map. [Chris Dolan]

  - Fixed a bug in which notes() set in the Build.PL before
    create_build_script() was called would get lost unless more notes()
    were also set afterwards. [Spotted by Dave Rolsky]

  - The process of building elements of the distribution is now driven
    by a list of build elements, paving the way for letting people add
    their own types of build elements in future versions of
    Module::Build (or in the current version with some difficulty).

  - Fixed some linking errors on Cygwin. [Randy Sims, Terrence Brannon]

  - Fixed a line-ending problem with detecting the dist_abstract
    properly on Cygwin. [Randy Sims]

  - Fixed a problem with signatures that occurred if 'distsign' was
    called before 'distdir' - the signature would be generated twice.

  - Added a 'create_readme' parameter to new(), which will use
    Pod::Text to generate a README from the main (dist_version_from)
    module file during the 'distdir' action.

  - We now refuse to run the 'Build' script if it was created using a
    different version of Module::Build.  This has caused a couple of
    nasty bugs in the past, I don't want to know what it would cause in
    the future.

  - Documentation for do_system() has been added. [Dave Rolsky]

  - run_perl_script() is now available as a class method, though it
    will need to (re-)find the perl interpreter in this case.

  - Added a new_from_context() method that authors of automated tools
    like CPANPLUS and CPAN can use instead of running all tasks as
    sub-processes.  We also use it in the regression tests for
    Module::Build itself.  ** Note that this method is currently
    undocumented because its name may change in the future. **

  - When signing distributions with Module::Signature, we now
    automatically add the SIGNATURE file to the MANIFEST, avoiding an
    unpleasant chicken/egg problem for the module author.
    [unpleasantness spotted by sungo]

  - In Module::Build::Compat, added support for the 'verbose' parameter
    to Makefile.PL [spotted by Soren Andersen, fixed by Michael
    Schwern]

  - The Module::Build distribution now has a cryptographic 'SIGNATURE'
    file created by Module::Signature.

  - Added proper documentation for the subclass() method. [spotted by
    Jonathan Steinert]

  - Worked around a Config.pm bug in Red Hat 9 which prevented man
    pages from being installed in the correct places. [spotted by Ville
    Skytta]

  - Fixed a Module::Build::Compat bug in which setting INSTALLDIRS
    caused a crash. [spotted by Ilya Martynov]

Re: [Module::Build] Use of manifest action produces ExtUtils::Manifest warnings

[Ken W. <ke...@ma...>]

On Tuesday, October 14, 2003, at 09:27  PM, Michael G Schwern wrote:

> On Tue, Oct 14, 2003 at 09:03:52PM -0500, Ken Williams wrote:
>> They're both aware of MANIFEST.SKIP files, but the only purpose of a
>> MANIFEST.SKIP file is to help auto-generate a MANIFEST file.  If you
>> don't have a MANIFEST file, then that warning (or maybe something a
>> little more friendly) should indeed be emitted.
>>
>> However, I just noticed that projects that use MakeMaker *don't* emit
>> any warnings in this situation.  I'm not sure what to make of that.  I
>> sort of think they should, but maybe not.  Schwern?
>
> You shouldn't get a warning about not having a MANIFEST from Build.PL.
> Why?  Consider how you generate a MANIFEST...
>
>     ./Build manifest
>
> What do you have to do before you can run ./Build?  *Bonk*  
> Enlightenment.
> :)

Okay, twist my arm.  I'll make the change.  I just like to warn when I 
don't like what people are doing.

  -Ken

Re: [Module::Build] PROPOSAL: M::B should install HTML documentation

[Randy W. S. <Ra...@Th...>]

On 10/15/2003 6:23 PM, Michael G Schwern wrote:
> On Wed, Oct 15, 2003 at 10:39:12AM -0500, Chris Dolan wrote:
> 
>>On Wednesday, October 15, 2003, at 06:12  AM, <kev...@ub...> 
>>wrote:
>>
>>>I would love to see M::B support building HTML documentation.
>>
>>
>>I have built a module to do exactly that.  It is not yet published to 
>>CPAN, but here's the documentation.  The main work left to do is to 
>>tweak some of the defaults and to get a Pod::Html regression bug fixed 
>>(doesn't handle nested =item tags right, grr...)
> 
> 
> A few things to note:
> 
> 5.8.1 finally included Config options for HTML installation directories.
> So look for $Config{install*html*dir} (installhtml1dir, installhtml3dir,
> installsitehtml1dir, etc...) and if they're set, Module::Build should
> install HTML docs by default.

IIRC, some of those have been around longer but where unused; I don't 
think anyone ever agreed on where html docs should be installed.

> I would avoid passing Pod::Html specific flags into Module::Build.  Have
> a plan ready to map them in case Pod::Html is replaced.  The names of
> the Pod::Html arguments are fairly generic, so its sort of moot.  Just keep 
> your upgrade path open in case one of the future POD->HTML modules on CPAN 
> matures.

ActiveState distributions have their own means of generating html from 
pod (the ActivePerl::DocTools module), if that module is present you 
probably should use it or atleast ask the user.

There is another issue here in that the list of actions is growing quite 
large, and M::B is (IMHO) turning into a large monolithic module. Would 
it be worth the effort to re-architect actions, so that they are 
plug-ins (M::B::ACTION::html, M::B::ACTION::dist). This would keep M::B 
from becoming monolithic and would allow others to develop plug-ins to 
expand functionality without requiring invasive code changes.

This is only half thought-out, so I'm not sure if it's practical. For 
example, I don't know how easy it would be to come up with an interface 
so that actions could get info from M::B without digging into the 
internals.

<thinking out loud>

Each module would contain one or more actions. M::B would search for 
plugin actions at startup, querying each module for a list of supported 
actions. Each action knows what parameters it accepts and can display 
its own help info. There could be a helper class for generating actions 
and linking them by dependencies, i.e.

my $action = new M::B::ACTION::Builder(
   name => 'My_lib',
   code => sub {},
   ...
);

my $top = new M::B::ACTION::Builtin( name => 'all' );
$top->add_dependency($action);

</thinking out loud>

Just a thought,
Randy.

-- 
A little learning is a dang'rous thing;
Drink deep, or taste not the Pierian spring;
There shallow draughts intoxicate the brain;
And drinking largely sobers us again.
                 - Alexander Pope

Re: [Module::Build] PROPOSAL: M::B should install HTML documentation

[Michael G S. <sc...@po...>]

On Wed, Oct 15, 2003 at 10:39:12AM -0500, Chris Dolan wrote:
> On Wednesday, October 15, 2003, at 06:12  AM, <kev...@ub...> 
> wrote:
> >I would love to see M::B support building HTML documentation.
> 
> 
> I have built a module to do exactly that.  It is not yet published to 
> CPAN, but here's the documentation.  The main work left to do is to 
> tweak some of the defaults and to get a Pod::Html regression bug fixed 
> (doesn't handle nested =item tags right, grr...)

A few things to note:

5.8.1 finally included Config options for HTML installation directories.
So look for $Config{install*html*dir} (installhtml1dir, installhtml3dir,
installsitehtml1dir, etc...) and if they're set, Module::Build should
install HTML docs by default.

I would avoid passing Pod::Html specific flags into Module::Build.  Have
a plan ready to map them in case Pod::Html is replaced.  The names of
the Pod::Html arguments are fairly generic, so its sort of moot.  Just keep 
your upgrade path open in case one of the future POD->HTML modules on CPAN 
matures.


-- 
Michael G Schwern        sc...@po...  http://www.pobox.com/~schwern/
Kindly do not attempt to cloud the issue with facts.

Re: [Module::Build] PROPOSAL: M::B should install HTML documentation

[Chris D. <ch...@cl...>]

Kevin,

It would certainly be possible to fold it in.  I originally wrote it 
for internal company use only, so I didn't try to merge it with M::B 
directly.  I'm using it for our ActionScript/Flash packager, which 
subclasses Module::Build::Html for POD extraction (since man pages are 
pretty meaningless to Flash developers).

Chris

On Wednesday, October 15, 2003, at 12:44  PM, <kev...@ub...> 
wrote:

> Chris
>
>>> I would love to see M::B support building HTML documentation.
>
>> I have built a module to do exactly that.  It is not yet published to
>> CPAN, but here's the documentation.
>
>>     Module::Build::Html - HTML documentation for packages
>
> That sounds excellent.  However, two requests:
>
> 1) Could this code not just be folded into the M::B distribution 
> immediately
> as an additional action.  For example:
>
> ./Build htmldocs css=http://perldoc.com/css/perldoc.css...
>
> I should think that this would increase its take-up.
>
> 2) I would be keen to see all of the options to Pod::Html supported.
> In particular, I would like to use --cachedir option.
>
> Cheers
> Kevin
--
Chris Dolan, Software Developer, Clotho Advanced Media Inc.
ch...@cl..., 294-7900, 211 S Paterson, Madison WI 53703

RE: [Module::Build] PROPOSAL: M::B should install HTML documentation

[<kev...@ub...>]

Chris

>> I would love to see M::B support building HTML documentation.

> I have built a module to do exactly that.  It is not yet published to=20
> CPAN, but here's the documentation.

>     Module::Build::Html - HTML documentation for packages

That sounds excellent.  However, two requests:

1) Could this code not just be folded into the M::B distribution =
immediately
as an additional action.  For example:

./Build htmldocs css=3Dhttp://perldoc.com/css/perldoc.css...

I should think that this would increase its take-up.

2) I would be keen to see all of the options to Pod::Html supported.
In particular, I would like to use --cachedir option.

Cheers
Kevin

+ANYTHING+BELOW+WAS+ADDED+AFTER+I+HIT+SEND+

Visit our website at http://www.ubs.com

This message contains confidential information and is intended only 
for the individual named.  If you are not the named addressee you 
should not disseminate, distribute or copy this e-mail.  Please 
notify the sender immediately by e-mail if you have received this 
e-mail by mistake and delete this e-mail from your system.

E-mail transmission cannot be guaranteed to be secure or error-free 
as information could be intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain viruses.  The sender therefore 
does not accept liability for any errors or omissions in the contents 
of this message which arise as a result of e-mail transmission.  If 
verification is required please request a hard-copy version.  This 
message is provided for informational purposes and should not be 
construed as a solicitation or offer to buy or sell any securities or 
related financial instruments.

Re: [Module::Build] PROPOSAL: M::B should install HTML documentation

[Chris D. <ch...@cl...>]

On Wednesday, October 15, 2003, at 06:12  AM, <kev...@ub...> 
wrote:
> I would love to see M::B support building HTML documentation.


I have built a module to do exactly that.  It is not yet published to 
CPAN, but here's the documentation.  The main work left to do is to 
tweak some of the defaults and to get a Pod::Html regression bug fixed 
(doesn't handle nested =item tags right, grr...)

Chris



NAME
     Module::Build::Html - HTML documentation for packages

DESCRIPTION
     This package adds automatic generation of HTML documentation to
     Module::Build.

SYNOPSIS
     Use almost exactly like Module::Build. That is, for end users:

        cd My-Package
        perl Build.PL installhtml=/my/dir/for/html
        Build
        Build test
        Build install

     See the configuration section below for details on how to use the
     optional arguments to "perl Build.PL".

     For developers, create a file called Build.PL that looks something 
like:

         use Module::Build;
         my $builder = "Module::Build";
         eval 'use Module::Build::Html; $builder .= "::Html"; ';
         $builder -> new(
                         module_name => 'My::Package',
                         license => 'gpl',
                         requires => {
                            ...
                         },
         )->create_build_script;

CONFIGURATION
     We've added a few custom configuration parameters that you can use.
     Typically, these are useful to the end user, not the developer. As 
such,
     use them like this:

       perl Build.pl key=value

     instead of putting them into the Build.PL directly.

     css=URL
         Defaults to <http://www.clotho.com/css/perldoc.css>. Decent
         alternatives include <http://search.cpan.org/s/style.css> and
         <http://perldoc.com/css/perldoc.css>. You should feel to 
download
         and edit one of these for your own purposes. "file://" URLs work
         just great for local CSS files.

     installhtml=DIR
         Defaults to "undef", which means that HTML files are created, 
but
         not installed by default. Decent alternatives include, for 
example,
         "/usr/share/perlhtml" and "$HOME/Documents/perl".

     htmlext=EXTENSION
         Defaults to "html". Decent alternatives include, for example,
         "shtml", "HTM" and "php".

OVERRIDDEN METHODS
     _construct KEY => VALUE, KEY => VALUE, ...
         This method is called internally by new(). We apply our custom
         configuration value here (unless the user has already overridden
         them in "perl Build.PL").

     _set_install_paths
         Add the "installhtml" directory to the list of installation
         directories, if needed.

     ACTION_docs
         Add HTML output to the documentation creation step.

NEW METHODS
     htmlify_all_pods
         This closely parallels the manify_bin_pods() and 
manify_lib_pods()
         methods from Module::Build::Base. All files which might contain 
POD
         are examined and HTML versions of the POD are output to the
         "blib/htmldoc" directory. Pod::Html is loaded to perform the
         conversion.

AUTHOR
     Clotho Advanced Media Inc., *cp...@cl...*

--
Chris Dolan, Software Developer, Clotho Advanced Media Inc.
ch...@cl..., 294-7900, 211 S Paterson, Madison WI 53703

Re: [Module::Build] [PATCH] make test failure report (Cygwin)

[Ken W. <ke...@ma...>]

On Tuesday, October 14, 2003, at 11:52  PM, Randy W. Sims wrote:

> On 10/14/2003 11:04 PM, Randy W. Sims wrote:
>
>> PS. I've attached output of the error I'm getting from t/runthrough.t 
>> on Win2k for the archives.
>> not ok 23# Test 23 got: '<SOFTPKG NAME="Sample" VERSION="0,01,0,0">
>>     <TITLE>Sample</TITLE>
>> </ABSTRACT>CT>Foo foo sample foo
>>     <AUTHOR>Sample Man &lt;sa...@ex...&gt;</AUTHOR>
>>     <IMPLEMENTATION>
>>         <DEPENDENCY NAME="File-Spec" VERSION="0,0,0,0" />
>>         <CODEBASE HREF="/path/to/codebase" />
>>     </IMPLEMENTATION>
>> </SOFTPKG>
>> ' (t/runthrough.t at line 130)
>> #    Expected: '<SOFTPKG NAME="Sample" VERSION="0,01,0,0">
>>     <TITLE>Sample</TITLE>
>>     <ABSTRACT>Foo foo sample foo</ABSTRACT>
>>     <AUTHOR>Sample Man &lt;sa...@ex...&gt;</AUTHOR>
>>     <IMPLEMENTATION>
>>         <DEPENDENCY NAME="File-Spec" VERSION="0,0,0,0" />
>>         <CODEBASE HREF="/path/to/codebase" />
>>     </IMPLEMENTATION>
>> </SOFTPKG>
>> '
>> Deleting Sample.ppd
>> Deleting save_out
>> Deleting Sample-0.01.tar.gz
>> Deleting lib/Sample/Script
>> Deleting blib
>> Deleting _build
>> Deleting Build
>
> And here is the patch to fix it; It seems the line ending in the 
> abstract was causing trouble.

Wow, what a weird way to manifest that error.  I'll apply the patch, 
thanks.


> BTW, wouldn't it be better to use Pod::Parser in the dist_* routines 
> for more acurate results?

Probably so, yeah.  Is that a core module?

  -Ken

Re: [Module::Build] make test failure report (Cygwin)

[Randy W. S. <Ra...@Th...>]

Greg Matheson wrote:

> On Wed, 15 Oct 2003, Greg Matheson wrote:
> 
> 
>>Failed Test Stat Wstat Total Fail  Failed  List of Failed
>>-------------------------------------------------------------------------------
>>t/compat.t                41   18  43.90%  5-8 11 14 18-21 24 27 31-34 37 40
> 
> 
> Sorry, I didn't have make installed. I guess I've been installing all my modules with Module::Build recently.
> 
> Here is the output after installing make.
> 
> t/compat....1..41
> # Running under perl version 5.008001 for cygwin
> # Current time local: Wed Oct 15 08:03:02 2003
> # Current time GMT:   Wed Oct 15 08:03:02 2003
> # Using Test.pm version 1.24

<snipped verbose output>

> All tests successful.
> Files=1, Tests=41, 135 wallclock secs ( 0.00 cusr +  0.00 csys =  0.00 CPU)
> 

Ahh, I was on the wrong trail. Thanks for the help on this; I think the 
solution is to guard t/compat.t with a test for the make utility and 
warn if it's not found (but not error)?

 > PS. My messages aren't making it to the list,
 > because my school's mail server is in an
 > open relay database. I get messages from the list, however.

Thanks,
Randy.

[Module::Build] PROPOSAL: M::B should install HTML documentation

[<kev...@ub...>]

All

The following comments were collected from a previous thread:

SP> As an aside, I always thought it would be a bit more useful to=20
SP> generate HTML manpages on Win32 & friends, considering they don't =
have=20
SP> a 'man' tool by default.
=20
SP> For example, ACTION_docs could be split up into ACTION_manpages,=20
SP> ACTION_html_docs:
=20
SP> ./Build html_docs
SP> ./Build manpages
=20
SP> And there could be config parameters set for each (with sensible=20
SP> defaults for each OS) that ACTION_docs checked before trying to do=20
SP> anything.
=20
SP> What do people think: a useful idea, or feature creep?

YS-T> I'd think whether to install HTML would be a separate option, =
unrelated
YS-T> to man pages.
=20
SP> Yeah - that discussion really belongs in a separate thread.

So, here is the new thread :-)

I would love to see M::B support building HTML documentation.  I don't =
think
this is at all specific to platforms that don't have man.  I work on =
Unix, but
try to provide all documentation in both man and HTML form.  Currently, =
I
achieve this by using M::B to generate the man pages, then installhtml =
[1]
to generate HTML documentation.  However, there are two problems with =
this:

a) installhtml appears to be a bit of an obscure part of the Perl =
distribution.
For example, IIRC, it is not installed into the bin directory by =
default; you have to
copy it yourself.  It also does not support all the features of =
pod2html.
In particular, I want to use the --cachedir option (not documented in =
pod2html
but documented in the Pod::Html page).

b) It is not as elegant as if the functionality were integrated into =
M::B.

My favoured interface would be that ./Build generates man pages as it =
does now.
A separate action - ./Build htmldocs - would invoke pod2html (or maybe =
Pod::Html
directly, not sure) to generate the HTML docs.  There would need to be a
way to pass options through to pod2html.  Maybe something like the =
following:

./Build htmldocs -htmldir=3D/foo --htmlroot=3D/bar --cachedir=3Dname =
[etc]

1. http://search.cpan.org/dist/perl/installhtml

Cheers
Kevin

+ANYTHING+BELOW+WAS+ADDED+AFTER+I+HIT+SEND+

Visit our website at http://www.ubs.com

This message contains confidential information and is intended only 
for the individual named.  If you are not the named addressee you 
should not disseminate, distribute or copy this e-mail.  Please 
notify the sender immediately by e-mail if you have received this 
e-mail by mistake and delete this e-mail from your system.

E-mail transmission cannot be guaranteed to be secure or error-free 
as information could be intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain viruses.  The sender therefore 
does not accept liability for any errors or omissions in the contents 
of this message which arise as a result of e-mail transmission.  If 
verification is required please request a hard-copy version.  This 
message is provided for informational purposes and should not be 
construed as a solicitation or offer to buy or sell any securities or 
related financial instruments.