search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.86k stars 528 forks source link

h2xs does not create VERSION stubs #7065

Closed p5pRT closed 20 years ago

p5pRT commented 20 years ago

Migrated from rt.perl.org#25268 (status was 'resolved')

Searchable as RT25268$

p5pRT commented 20 years ago

From @davidnicol

Created by @davidnicol

nobody knows about the VERSION method except people who have thoroughly read perldoc -f use. I believe that it would be a good thing if h2xs added a default VERSION method to the code it creates\, and commented it out. This commented-out code would have an obvious way to edit it in order to create a VERSION method that knows what lower version numbers the current version is incompatbile with.

Let's say the current version is 2.3.4 and the current version supports the same interface as everything from 1.0.0 to 2.2.3 but then an incompatibility was introduced in 2.2.4 which was taken out in 2.3.1. We would want to describe this situation by uncommenting the VERSION code and editing a configuration structure something like this​:

  {   my %VERSION_INCOMPATIBILITY;

  $VERSION_INCOMPATIBILITY{'[0.0.0\,1.0.0)'} =   "constructor syntax has changed";   $VERSION_INCOMPATIBILITY{'[2.2.4\,2.3.1)'} =   "frobniz method croaks without second argument";

  sub VERSION{   ... not sure exactly what goes here\,   but it parses (keys %VERSION_INCOMPATIBILITY)   comparing each to the provided parameter;   `perldoc -f use` is not clear on whether the   desired version arrives in $_[0] or $_[1] ...

  }   }

And the above would be commented out\, along with instructions for using it\, just like the discussion of %EXPORT_TAGS which now appears in h2xs-provided skeletons.

Perl Info ``` Flags: category=utilities severity=wishlist Site configuration information for perl v5.6.1: Configured by bhcompile at Mon Aug 18 16:06:54 EDT 2003. Summary of my perl5 (revision 5.0 version 6 subversion 1) configuration: Platform: osname=linux, osvers=2.4.21-1.1931.2.393.entsmp, archname=i386-linux uname='linux porky.devel.redhat.com 2.4.21-1.1931.2.393.entsmp #1 smp thu aug 14 14:47:21 edt 2003 i686 unknown ' config_args='-des -Doptimize=-O2 -march=i386 -mcpu=i686 -Dcc=gcc -Dcf_by=Red Hat, Inc. -Dcccdlflags=-fPIC -Dinstallprefix=/usr -Dprefix=/usr -Darchname=i386-linux -Dvendorprefix=/usr -Dsiteprefix=/usr -Uusethreads -Uuseithreads -Uuselargefiles -Dd_dosuid -Dd_semctl_semun -Di_db -Di_ndbm -Di_gdbm -Di_shadow -Di_syslog -Dman3ext=3pm -Dinc_version_list=5.6.0/i386-linux 5.6.0' hint=recommended, useposix=true, d_sigaction=define usethreads=undef use5005threads=undef useithreads=undef usemultiplicity=undef useperlio=undef d_sfio=undef uselargefiles=undef usesocks=undef use64bitint=undef use64bitall=undef uselongdouble=undef Compiler: cc='gcc', ccflags ='-fno-strict-aliasing -I/usr/local/include', optimize='-O2 -march=i386 -mcpu=i686', cppflags='-fno-strict-aliasing -I/usr/local/include' ccversion='', gccversion='2.96 20000731 (Red Hat Linux 7.2 2.96-112.7.2)', gccosandvers='' intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234 d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12 ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=4 alignbytes=4, usemymalloc=n, prototype=define Linker and Libraries: ld='gcc', ldflags =' -L/usr/local/lib' libpth=/usr/local/lib /lib /usr/lib libs=-lnsl -ldl -lm -lc -lcrypt -lutil perllibs=-lnsl -ldl -lm -lc -lcrypt -lutil libc=/lib/libc-2.2.4.so, so=so, useshrplib=false, libperl=libperl.a Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-rdynamic' cccdlflags='-fPIC', lddlflags='-shared -L/usr/local/lib' Locally applied patches: @INC for perl v5.6.1: /usr/lib/perl5/5.6.1/i386-linux /usr/lib/perl5/5.6.1 /usr/lib/perl5/site_perl/5.6.1/i386-linux /usr/lib/perl5/site_perl/5.6.1 /usr/lib/perl5/site_perl/5.6.0/i386-linux /usr/lib/perl5/site_perl/5.6.0 /usr/lib/perl5/site_perl /usr/lib/perl5/vendor_perl/5.6.1/i386-linux /usr/lib/perl5/vendor_perl/5.6.1 /usr/lib/perl5/vendor_perl . Environment for perl v5.6.1: HOME=/home/david LANG=en_US LANGUAGE (unset) LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/usr/kerberos/bin:/bin:/usr/bin:/usr/bin/X11:/usr/local/bin:/usr/games:/opt/gnome/bin:/usr/X11R6/bin:/home/david/bin PERL_BADLANG (unset) SHELL=/bin/bash ```
p5pRT commented 20 years ago

From @schwern

On Mon\, Jan 26\, 2004 at 06​:59​:55AM -0000\, davidnico@​cpan.org (via RT) wrote​:

nobody knows about the VERSION method except people who have thoroughly read perldoc -f use. I believe that it would be a good thing if h2xs added a default VERSION method to the code it creates\, and commented it out. This commented-out code would have an obvious way to edit it in order to create a VERSION method that knows what lower version numbers the current version is incompatbile with.

I'm not a fan of adding more code to the h2xs template that's not strictly necessary. The h2xs template is designed to get a new module author off the ground with a minimum of fuss. Throwing in more code will be confusing.

This is also not code commonly put in brand new modules. Version incompatibilities of the type you're talking about don't become important until many versions down the road\, if ever at all\, at which point they've presumably figured it out themselves.

Rather than saddling every h2xs module with cut & code\, it would better be put into a module. Version​::Compatibility or something.

sub VERSION\{
    \.\.\. not sure exactly what goes here\,
    but it parses \(keys %VERSION\_INCOMPATIBILITY\)
    comparing each to the provided parameter; 
    \`perldoc \-f use\` is not clear on whether the
    desired version arrives in $\_\[0\] or $\_\[1\] \.\.\.

\}

VERSION() is documented in the man page for UNIVERSAL. As its a method\, the optional version # comes in on $_[1].

-- Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern/ You'll do.

p5pRT commented 20 years ago

The RT System itself - Status changed from 'new' to 'open'

p5pRT commented 20 years ago

From @JohnPeacock

I tried to send this yesterday\, but my home machine cannot seem to contact the perl.org MX boxes. :\~(

davidnico@​cpan.org (via RT) wrote​:

nobody knows about the VERSION method except people who have thoroughly read perldoc -f use. I believe that it would be a good thing if h2xs added a default VERSION method to the code it creates\, and commented it out. This commented-out code would have an obvious way to edit it in order to create a VERSION method that knows what lower version numbers the current version is incompatbile with.

As the "official" VERSION maven\, I'd appreciate it if this was _not_ the case. I don't have any problem with any developer desiring a finer control overriding the UNIVERSAL​::VERSION with their own\, but the thought of leading developers to believe that they could safely do it on their own would be just dangerous.

\{
my %VERSION\_INCOMPATIBILITY;

$VERSION\_INCOMPATIBILITY\{'\[0\.0\.0\,1\.0\.0\)'\} = 
    "constructor syntax has changed";
$VERSION\_INCOMPATIBILITY\{'\[2\.2\.4\,2\.3\.1\)'\} = 
    "frobniz method croaks without second argument";

sub VERSION\{
    \.\.\. not sure exactly what goes here\,
    but it parses \(keys %VERSION\_INCOMPATIBILITY\)
    comparing each to the provided parameter; 
    \`perldoc \-f use\` is not clear on whether the
    desired version arrives in $\_\[0\] or $\_\[1\] \.\.\.

\}
\}

I've already got most of the design and coding done for a module I am calling version​::Limit (version​::Incompatibility is too long to type ;~) based on my version module. I need to finish the tests and complete the documentation.

For example (this code is working already)​:

package LimitTest; use version​::Limit;

version​::Limit​::Scope( "[0.0.0\,1.0.0)" => "constructor syntax has changed"\, "[2.2.4\,2.3.1)" => "frobniz method croaks without second argument"\, ); our $VERSION = "3.2.5";

and then this works​:

perl -I lib -I t -e 'use LimitTest 0.1.0;' Cannot 'use LimitTest 0.1.0'​: constructor syntax has changed at lib/version/Limit.pm line 77. BEGIN failed--compilation aborted at -e line 1.

However\, this module will be strictly limited to 5.8.0 and later Perl's\, since it requires the enhanced v-string support only introduced in 5.8.0.

Contact me offline...

John

-- John Peacock Director of Information Research and Technology Rowman & Littlefield Publishing Group 4501 Forbes Boulevard Suite H Lanham\, MD 20706 301-459-3366 x.5010 fax 301-429-5748

p5pRT commented 20 years ago

From @schwern

On Mon\, Jan 26\, 2004 at 06​:59​:55AM -0000\, davidnico@​cpan.org (via RT) wrote​:

nobody knows about the VERSION method except people who have thoroughly read perldoc -f use. I believe that it would be a good thing if h2xs added a default VERSION method to the code it creates\, and commented it out. This commented-out code would have an obvious way to edit it in order to create a VERSION method that knows what lower version numbers the current version is incompatbile with.

I'm not a fan of adding more code to the h2xs template that's not strictly necessary. The h2xs template is designed to get a new module author off the ground with a minimum of fuss. Throwing in more code will be confusing.

This is also not code commonly put in brand new modules. Version incompatibilities of the type you're talking about don't become important until many versions down the road\, if ever at all\, at which point they've presumably figured it out themselves.

Rather than saddling every h2xs module with cut & code\, it would better be put into a module. Version​::Compatibility or something.

sub VERSION\{
    \.\.\. not sure exactly what goes here\,
    but it parses \(keys %VERSION\_INCOMPATIBILITY\)
    comparing each to the provided parameter; 
    \`perldoc \-f use\` is not clear on whether the
    desired version arrives in $\_\[0\] or $\_\[1\] \.\.\.

\}

VERSION() is documented in the man page for UNIVERSAL. As its a method\, the optional version # comes in on $_[1].

-- Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern/ You'll do.

p5pRT commented 20 years ago

From tassilo.parseval@post.rwth-aachen.de

On Mon\, Jan 26\, 2004 at 06​:59​:55AM +0000 davidnico@​cpan.org (via RT) wrote​:

This is a bug report for perl from davidnico@​cpan.org\, generated with the help of perlbug 1.33 running under perl v5.6.1.

----------------------------------------------------------------- [Please enter your report here]

nobody knows about the VERSION method except people who have thoroughly read perldoc -f use. I believe that it would be a good thing if h2xs added a default VERSION method to the code it creates\, and commented it out. This commented-out code would have an obvious way to edit it in order to create a VERSION method that knows what lower version numbers the current version is incompatbile with.

Let's say the current version is 2.3.4 and the current version supports the same interface as everything from 1.0.0 to 2.2.3 but then an incompatibility was introduced in 2.2.4 which was taken out in 2.3.1. We would want to describe this situation by uncommenting the VERSION code and editing a configuration structure something like this​:

\{
my %VERSION\_INCOMPATIBILITY;

$VERSION\_INCOMPATIBILITY\{'\[0\.0\.0\,1\.0\.0\)'\} = 
    "constructor syntax has changed";
$VERSION\_INCOMPATIBILITY\{'\[2\.2\.4\,2\.3\.1\)'\} = 
    "frobniz method croaks without second argument";

sub VERSION\{
    \.\.\. not sure exactly what goes here\,
    but it parses \(keys %VERSION\_INCOMPATIBILITY\)
    comparing each to the provided parameter; 
    \`perldoc \-f use\` is not clear on whether the
    desired version arrives in $\_\[0\] or $\_\[1\] \.\.\.

\}
\}

And the above would be commented out\, along with instructions for using it\, just like the discussion of %EXPORT_TAGS which now appears in h2xs-provided skeletons.

And which I immediately delete each time I create a new module. Using h2xs' skeleton as an ersatz-documentation looks like abuse to me.

A better documentation (or in fact any documentation) of the VERSION method is probably better placed in perlnewmod.pod or perlmod.pod.

Interestingly\, perlmod.pod is deliberately misleading the reader. It gives this code as an example​:

  $VERSION = do { my @​r = (q$Revision​: 2.21 $ =~ /\d+/g);   sprintf "%d."."%02d" x $#r\, @​r };

This implies that versioning always happens through $VERSION whereas the above could also be a candidate for an overridden VERSION() method.

Tassilo -- $_=q#"\,}])!JAPH!qq(tsuJ[{@​"tnirp}3..0}_$;//​::niam/s~=)]3[))_$-3(rellac(=_$({ pam{rekcahbus})(rekcah{lrePbus})(lreP{rehtonabus})!JAPH!qq(rehtona{tsuJbus#; $_=reverse\,s+(?\<=sub).+q#q!'"qq.\t$&."'!#+sexisexiixesixeseg;y~\n~~dddd;eval

p5pRT commented 20 years ago

From @schwern

On Tue\, Jan 27\, 2004 at 10​:46​:50AM +0100\, Tassilo von Parseval wrote​:

Interestingly\, perlmod.pod is deliberately misleading the reader. It gives this code as an example​:

$VERSION = do \{ my @&#8203;r = \(q$Revision&#8203;: 2\.21 $ =~ /\\d\+/g\); 
                sprintf "%d\."\."%02d" x $\#r\, @&#8203;r \};

This implies that versioning always happens through $VERSION whereas the above could also be a candidate for an overridden VERSION() method.

perl -wle 'package Foo; $VERSION = 4.2; print Foo->VERSION' 4.2

VERSION() reads $VERSION.

-- Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern/ Follow me to certain death!   http​://www.unamerican.com/

p5pRT commented 20 years ago

From @JohnPeacock

davidnico@​cpan.org (via RT) wrote​:

nobody knows about the VERSION method except people who have thoroughly read perldoc -f use. I believe that it would be a good thing if h2xs added a default VERSION method to the code it creates\, and commented it out. This commented-out code would have an obvious way to edit it in order to create a VERSION method that knows what lower version numbers the current version is incompatbile with.

As the "official" VERSION maven\, I'd appreciate it if this was _not_ the case. I don't have any problem with any developer desiring a finer control overriding the UNIVERSAL​::VERSION with their own\, but the thought of leading developers to believe that they could safely do it on their own would be just dangerous.

Let's say the current version is 2.3.4 and the current version supports the same interface as everything from 1.0.0 to 2.2.3 but then an incompatibility was introduced in 2.2.4 which was taken out in 2.3.1. We would want to describe this situation by uncommenting the VERSION code and editing a configuration structure something like this​:

\{
my %VERSION\_INCOMPATIBILITY;

$VERSION\_INCOMPATIBILITY\{'\[0\.0\.0\,1\.0\.0\)'\} = 
    "constructor syntax has changed";
$VERSION\_INCOMPATIBILITY\{'\[2\.2\.4\,2\.3\.1\)'\} = 
    "frobniz method croaks without second argument";

sub VERSION\{
    \.\.\. not sure exactly what goes here\,
    but it parses \(keys %VERSION\_INCOMPATIBILITY\)
    comparing each to the provided parameter; 
    \`perldoc \-f use\` is not clear on whether the
    desired version arrives in $\_\[0\] or $\_\[1\] \.\.\.

\}
\}

I think this is eminently doable with a version​::Incompatible module (obviously based on my version module ;). This would have the additional benefit that it would act a compatibility module between multiple versions of Perl. I'm not done with the base "version.pm" module yet (some nagging leaks)\, but I have a working plan for the future.

Contact me offline...

John

-- John Peacock Director of Information Research and Technology Rowman & Littlefield Publishing Group 4720 Boston Way Lanham\, MD 20706 301-459-3366 x.5010 fax 301-429-5747

p5pRT commented 20 years ago

From @JohnPeacock

See CPAN/authors/id/J/JP/JPEACOCK/version-Limit-0.01.tar.gz for a way to do this using the "version" module and Perl 5.8.0+

p5pRT commented 20 years ago

@JohnPeacock - Status changed from 'open' to 'resolved'

p5pRT commented 20 years ago

From @JohnPeacock

John Peacock wrote​:

I've already got most of the design and coding done for a module I am calling version​::Limit (version​::Incompatibility is too long to type ;~) based on my version module. I need to finish the tests and complete the documentation.

And here is the module​:

  version-Limit-0.01.tar.gz

has entered CPAN as

  file​: $CPAN/authors/id/J/JP/JPEACOCK/version-Limit-0.01.tar.gz   size​: 3979 bytes   md5​: 388231caae207c66854abae707041216

To quote from the POD​:

DESCRIPTION In a mature\, highly structured development environment\, it is sometimes desireable to exert a more fine-grained versioning model than that per- mitted by the default behavior. With the standard Perl version model\, it is only possible to establish a maximum version (the most recent) for a given module. However\, this precludes changing the provided interface\, or specifically excluding certain versions (because of bugs). Using this module makes both of those things possible.

I realize that I didn't update the README file\, and I am going to have to quickly release 0.02\, so I am going to hunt for some new features or tests to justify another release so quickly... :o

John

-- John Peacock Director of Information Research and Technology Rowman & Littlefield Publishing Group 4720 Boston Way Lanham\, MD 20706 301-459-3366 x.5010 fax 301-429-5747

p5pRT commented 20 years ago

From whatever@davidnicol.com

On Tue\, 2004-01-27 at 18​:15\, Michael G Schwern wrote​:

Version incompatibilities of the type you're talking about don't become important until many versions down the road\, if ever at all\, at which point they've presumably figured it out themselves.

Schwern said this? Schwern? Schwern is presuming that people in general are capable of figuring something out for themselves? After even Dr. Conway failed to add a VERSION method that would throws error on attempts to include the ealier\, incompatible version of Parse​::RecDescent? The details are subtle and I cannot explain them\, here's Fergal Daly fro module authors​:

To see why the current situation is most definitely broken\, take the example of Parse​::RecDescent again. 1.90 changed in a fundamental way. Using the current system\, what should the author have done? Calling it 2.0 would be no good because

use Parse​::RecDescent 1.84;

works fine with 2.0 and CPAN.pm would download 2.0 if you told it you need at least 1.84.

I think that four or five lines are all that are needed to make module authors mindful of version incompatbility approaches from the getgo. Adding  
# sub VERSION{ # $_[1] \< 2.3 and die \<\<EOF; # version 2.3 and later releases of Foo​::Bar take an # array-reference as the eighth argument to baz() # EOF # };

to the h2xs-created template might help.

p5pRT commented 20 years ago

From @schwern

On Thu\, Feb 05\, 2004 at 12​:12​:49AM -0600\, david nicol wrote​:

On Tue\, 2004-01-27 at 18​:15\, Michael G Schwern wrote​:

Version incompatibilities of the type you're talking about don't become important until many versions down the road\, if ever at all\, at which point they've presumably figured it out themselves.

Schwern said this? Schwern? Schwern is presuming that people in general are capable of figuring something out for themselves? After even Dr. Conway failed to add a VERSION method that would throws error on attempts to include the ealier\, incompatible version of Parse​::RecDescent? The details are subtle and I cannot explain them\, here's Fergal Daly fro module authors​:

The idea of throwing a wad of commented out cut & paste code into the h2xs template just because the author might need it a dozen releases down the road is the problem here. The VERSION issue is irrelevant.

Use a module. That's what they're for.

-- Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern/ Worship the sig file

p5pRT commented 20 years ago

From whatever@davidnicol.com

Michael G Schwern via RT wrote​:

The idea of throwing a wad of commented out cut & paste code into the h2xs template just because the author might need it a dozen releases down the road is the problem here. The VERSION issue is irrelevant.

Use a module. That's what they're for.

So throw a commented-out module use into the template. How many modules have never introduced interface incompatibilities through their lives? "Just might" is mistaken in my unresearched opinion\, I suspect it's more of a certainty. I have no exhaustive statistics though.

p5pRT commented 20 years ago

From @schwern

On Fri\, Feb 06\, 2004 at 10​:26​:16AM -0600\, david wrote​:

Michael G Schwern via RT wrote​:

The idea of throwing a wad of commented out cut & paste code into the h2xs template just because the author might need it a dozen releases down the road is the problem here. The VERSION issue is irrelevant.

Use a module. That's what they're for.

So throw a commented-out module use into the template. How many modules have never introduced interface incompatibilities through their lives? "Just might" is mistaken in my unresearched opinion\, I suspect it's more of a certainty. I have no exhaustive statistics though.

I also don't think its wise to start throwing in commented out "just in case you might need it down the road" modules uses into h2xs templates. How many modules have never needed more testing? We should throw "# use Carp​::Assert" in there. And people always forget to check their opens so there should be a "# use Fatal qw(open close)". Pick a pet peeve. Its a slippery slope that shouldn't be started down. Keep the templates sparse and simple\, throw anything not immediately useful out\, so the first time module author that's going to use them doesn't get confused.

A perlfaq entry sounds more like the solution to your problem.

-- Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern/ Hold on while I slip into something a little more naked.

p5pRT commented 20 years ago

From whatever@davidnicol.com

Michael G Schwern wrote​:

On Fri\, Feb 06\, 2004 at 10​:26​:16AM -0600\, david wrote​:

I also don't think its wise to start throwing in commented out "just in case you might need it down the road" modules uses into h2xs templates. How many modules have never needed more testing? We should throw "# use Carp​::Assert" in there. And people always forget to check their opens so there should be a "# use Fatal qw(open close)". Pick a pet peeve. Its a slippery slope that shouldn't be started down. Keep the templates sparse and simple\, throw anything not immediately useful out\, so the first time module author that's going to use them doesn't get confused.

A perlfaq entry sounds more like the solution to your problem.

How about a module-authors BCP document\, and a heavy module template that includes stubs for all best current module-authoring practices?

p5pRT commented 20 years ago

From @schwern

On Fri\, Feb 06\, 2004 at 01​:46​:12PM -0600\, david wrote​:

How about a module-authors BCP document

Sure. We need a dedicated man page for module authors anyway.

and a heavy module template that includes stubs for all best current module-authoring practices?

Not in h2xs\, it already does too much as it is. I'm not a fan of "throw lots of commented out code and instructions into a template" as a method of educating\, as you've probably gathered. Also\, wadding all best practices together is a pretty poor practice.

What might be an interesting experiment is a simple web form to generate module templates. It has a bunch of checkboxes for various widgets and doodads that one might want in their module and\, after the author picks what they want\, it assembles it into a usable template. The advantage of a web form over a CLI like h2xs is you don't have to wade through all the obscure command line switches. All the functionality can be clearly described next to each checkbox. And you don't have to wait for the next version of Perl to use it.

-- Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern/ Playstation? Of course Perl runs on Playstation.   -- Jarkko Hietaniemi