You are viewing a plain text version of this content. The canonical link for it is here.
Posted to apreq-dev@httpd.apache.org by Joe Schaefer <jo...@sunstarsys.com> on 2004/07/19 18:40:51 UTC
[PROPOSAL] docs, tables, tests (was: Re: separate pod files for Apache:: packages)
Joe Schaefer <jo...@sunstarsys.com> writes:
[...]
> What I'm sort-of looking for is to add one podfile for
> ::Table and one for ::Error, bringing the total pods to 5
> (the other packages are specialized enough that they probably
> don't need separate docs). But we should somehow add links/copies
> in the installated docs so that eg
>
> % man Apache::Request::Table
> % man Apache::Cookie::Table
> % man Apache::Upload::Table
>
> all point to the same documentation.
Keeping that in mind...
with the perl APIs complete, actually I think it's time
to consider refactoring all the *::Table code into separate
modules. The table APIs aren't 100% necessary for our perl
users, and separating them out would reduce the memory footprint
of Apache::Request, Apache::Upload, and Apache::Cookie.
So what I propose we do is
1) add to glue/perl/docs:
Request.pod (replaces xsbuilder/Apache/Request/Request_pod)
Cookie.pod ( " " " /Cookie/Cookie_pod)
Upload.pod ( " " " /Upload/Upload_pod)
Table.pod (new)
Error.pod (new)
We should use Test::Inline (or something similar) to extract
basic API tests from these pods. I haven't given this any
more thought, but hopefully someone can flesh out the details
a bit to make sure this is workable.
2) Factor the Apache::*::Table packages into separate modules.
If we want to be nice, we could C<<require>> those modules
whenever Apache::Request or Apache::Cookie generates a table,
that way users wouldn't notice the table refactoring (yes
it's a minor performace hit, but IMO reasonable since perl's
TIEHASH API is really slow anyways).
3) Have the build system transplant the /docs pods into the blib/
directory during `make`, replicating Table.pod and Error.pod
as needed.
Comments?
--
Joe Schaefer
Re: [PROPOSAL] docs, tables, tests
Posted by Joe Schaefer <jo...@sunstarsys.com>.
Joe Schaefer <jo...@sunstarsys.com> writes:
[...]
> 2) Factor the Apache::*::Table packages into separate modules.
> If we want to be nice, we could C<<require>> those modules
> whenever Apache::Request or Apache::Cookie generates a table,
> that way users wouldn't notice the table refactoring (yes
> it's a minor performace hit, but IMO reasonable since perl's
> TIEHASH API is really slow anyways).
I just tried this, separating Apache::Request::Table from
Apache::Request. Stripping the symbols from the .so's,
we have the following file sizes:
original Request.so: 42 K
new Request.so: 34 K
new Table.so: 28 K
I was actually expecting a more significant size reduction than 23%.
Since the combined size of the split is 62 K, ~ 52% larger than the
original. It now looks to me like splitting out the tables into
separate modules will be a bad idea, so I won't pursue this item
further.
--
Joe Schaefer
Re: [PROPOSAL] docs, tables, tests
Posted by Joe Schaefer <jo...@sunstarsys.com>.
Stas Bekman <st...@stason.org> writes:
[...]
> > Here's a patch that accomplishes this for *nix, but it
> > uses a Makefile pattern (%.t: %.pod) which may be gnu-specific.
> > Just make a dummy glue/perl/docs/Error.pod file to start
> > playing with Inline::Test. I'll move the existing docs over
> > to this directory and commit the changes in a day or two, unless
> > someone has a better idea?
>
> won't that produce an overhead of copying the files as many times as
> you run 'make' (e.g. during development).
No, that's what the %.pod prereq is there for. It only regenerates
the Foo.t the file if the Foo.pod file is more recent. I've already
moved the docs over (locally, not in cvs) and written a few Inline
tests, and it works pretty well so far:
% make test
[...]
server localhost.localdomain:8529 started
t/apreq/big_input....ok
t/apreq/cgi..........ok
t/apreq/cookie.......ok
t/apreq/inherit......ok
t/apreq/request......ok
t/apreq/upload.......ok
All tests successful.
Files=6, Tests=101, 8 wallclock secs ( 5.19 cusr + 0.61 csys = 5.80 CPU)
[warning] server localhost.localdomain:8529 shutdown
/usr/bin/perl -Mblib -MTest::Harness -e 'runtests(@ARGV)' docs/Cookie.t docs/Error.t docs/Request.t docs/Table.t docs/Upload.t
docs/Cookie.....[apreq_env.c(179): Success] Lookup of HTTP_COOKIE failed: status=2
docs/Cookie.....ok
docs/Error......ok
docs/Request....ok
docs/Table......ok
docs/Upload.....ok
All tests successful.
Files=5, Tests=23, 0 wallclock secs ( 0.41 cusr + 0.05 csys = 0.46 CPU)
--
Joe Schaefer
Re: [PROPOSAL] docs, tables, tests
Posted by Stas Bekman <st...@stason.org>.
Joe Schaefer wrote:
> Joe Schaefer <jo...@sunstarsys.com> writes:
>
> [...]
>
>
>>Right- I guess we could also use the ./docs subdir to hold the
>>.t files Test::Inline generates, and add a "test" target to the
>>MY::postamble sub above to include them in a `make test` run.
>
>
> Here's a patch that accomplishes this for *nix, but it
> uses a Makefile pattern (%.t: %.pod) which may be gnu-specific.
> Just make a dummy glue/perl/docs/Error.pod file to start
> playing with Inline::Test. I'll move the existing docs over
> to this directory and commit the changes in a day or two, unless
> someone has a better idea?
won't that produce an overhead of copying the files as many times as you
run 'make' (e.g. during development). You may want copy the idea of
glue_pods from mp2, which uses a timestamp to avoid a useless repetition
of a target that hasn't changed.
--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: [PROPOSAL] docs, tables, tests (was: Re: separate pod files for
Apache:: packages)
Posted by Randy Kobes <ra...@theoryx5.uwinnipeg.ca>.
On Mon, 20 Jul 2004, Joe Schaefer wrote:
> Joe Schaefer <jo...@sunstarsys.com> writes:
>
> [...]
>
> > Right- I guess we could also use the ./docs subdir to hold the
> > .t files Test::Inline generates, and add a "test" target to the
> > MY::postamble sub above to include them in a `make test` run.
>
> Here's a patch that accomplishes this for *nix, but it
> uses a Makefile pattern (%.t: %.pod) which may be gnu-specific.
> Just make a dummy glue/perl/docs/Error.pod file to start
> playing with Inline::Test. I'll move the existing docs over
> to this directory and commit the changes in a day or two, unless
> someone has a better idea?
Looks good - I'll look at playing with the Inline::Test
stuff in a few days, and also fiddle with the Makefile
targets if Win32 doesn't understand the syntax.
--
best regards,
randy
Re: [PROPOSAL] docs, tables, tests (was: Re: separate pod files for Apache:: packages)
Posted by Joe Schaefer <jo...@sunstarsys.com>.
Joe Schaefer <jo...@sunstarsys.com> writes:
[...]
> Right- I guess we could also use the ./docs subdir to hold the
> .t files Test::Inline generates, and add a "test" target to the
> MY::postamble sub above to include them in a `make test` run.
Here's a patch that accomplishes this for *nix, but it
uses a Makefile pattern (%.t: %.pod) which may be gnu-specific.
Just make a dummy glue/perl/docs/Error.pod file to start
playing with Inline::Test. I'll move the existing docs over
to this directory and commit the changes in a day or two, unless
someone has a better idea?
Index: glue/perl/Makefile.PL
===================================================================
RCS file: /home/cvs/httpd-apreq-2/glue/perl/Makefile.PL,v
retrieving revision 1.9
diff -u -r1.9 Makefile.PL
--- glue/perl/Makefile.PL 30 Oct 2003 01:22:00 -0000 1.9
+++ glue/perl/Makefile.PL 20 Jul 2004 04:04:10 -0000
@@ -11,6 +11,8 @@
use Apache::TestRun ();
use Apache::TestConfigPerl ();
use File::Find qw(finddepth);
+use File::Spec::Functions qw(catdir);
+
my @scripts = ();
{
@@ -34,5 +36,47 @@
clean => { FILES => "xs t/logs t/TEST @scripts" },
realclean => { FILES => "xsbuilder/tables" },
);
+
+
+sub copy_docs {
+ my @lines;
+ my $dfs = '$(DIRFILESEP)';
+
+ foreach my $file (@_) {
+ my @dirs;
+ $file =~ /(\w+\.pod)$/ or next;
+ if ($1 eq "Error.pod" or $1 eq "Table.pod") {
+ push @dirs, catdir("Apache", $_) for qw/Request Cookie Upload/;
+ }
+ else {
+ push @dirs, "Apache";
+ }
+ push @lines, map <<EOT, @dirs;
+subdirs :: \$(INST_LIBDIR)$dfs$_$dfs$1
+\$(INST_LIBDIR)$dfs$_$dfs$1: $file
+ \$(NOECHO) \$(MKPATH) \$(INST_LIBDIR)$dfs$_
+ \$(CP) $file \$(INST_LIBDIR)$dfs$_$dfs$1
+
+EOT
+ }
+ return join "", @lines;
+}
+
+sub MY::postamble {
+ my @docs = <docs/*.pod>;
+ my @tests = @docs;
+ s/pod$/t/ for @tests;
+
+ return copy_docs(@docs) . sprintf <<'EOT', "@tests";
+%%.t : %%.pod
+ pod2test $< $@
+
+doc_test : %s
+ $(FULLPERL) -Mblib -MTest::Harness -e 'runtests(@ARGV)' $^
+
+test :: doc_test
+
+EOT
+}
__END__
--
Joe Schaefer
Re: [PROPOSAL] docs, tables, tests (was: Re: separate pod files for Apache:: packages)
Posted by Joe Schaefer <jo...@sunstarsys.com>.
Randy Kobes <ra...@theoryx5.uwinnipeg.ca> writes:
[...]
> Although you later found not much advantage to separating
> out the Apache::*::Table packages, it still seems to make
> sense (?) to separate out the Table.pod (as well as
> Error.pod), as they're similar.
+1. Basically I'm toying with adding something like this to
the bottom of glue/perl/Makefile.PL:
==================================================
sub copy_docs {
my @lines;
my $dfs = '$(DIRFILESEP)';
foreach my $file (@_) {
my @dirs;
$file =~ /(\w+\.pod)$/ or next;
if ($1 eq "Error.pod" or $1 eq "Table.pod") {
push @dirs, catfile("Apache", $_) for qw/Request Cookie Upload/;
}
else {
push @dirs, catfile "Apache";
}
push @lines, map <<EOT, @dirs;
subdirs :: \$(INST_LIBDIR)$dfs$_$dfs$1
\$(INST_LIBDIR)$dfs$_$dfs$1: $file
\$(MKPATH) \$(INST_LIBDIR)$dfs$_
\$(CP) $file \$(INST_LIBDIR)$dfs$_$dfs$1
EOT
}
return join "", @lines;
}
sub MY::postamble {
return copy_docs <docs/*.pod>;
}
==================================================
It's messy, but that will just copy whatever pods we put in
the ./docs subdir into their proper location in ./blib,
duplicating Table.pod and Error.pod as necessary.
> I could take a look at using Test::Inline to make some basic
> API tests (probably this weekend - I'm away for this week).
> From what I understand, one inserts the basic code for a
> test within the pod, and then use a supplied script to
> extract the tests into a .t test file that is run as usual
> (developers do the extraction, so users don't have to
> install Test::Inline). So with this it'd probably be a good
> idea to have two separate test directories - one for these
> tests (requiring Test::More), and the present one using
> Apache-Test.
Right- I guess we could also use the ./docs subdir to hold the
.t files Test::Inline generates, and add a "test" target to the
MY::postamble sub above to include them in a `make test` run.
If this is ok, let's name new directory "api", since it holds
our api docs *and* their tests.
--
Joe Schaefer
Re: [PROPOSAL] docs, tables, tests (was: Re: separate pod files for
Apache:: packages)
Posted by Randy Kobes <ra...@theoryx5.uwinnipeg.ca>.
On Mon, 19 Jul 2004, Joe Schaefer wrote:
> Joe Schaefer <jo...@sunstarsys.com> writes:
>
> [...]
>
> > What I'm sort-of looking for is to add one podfile for
> > ::Table and one for ::Error, bringing the total pods to 5
> > (the other packages are specialized enough that they probably
> > don't need separate docs). But we should somehow add links/copies
> > in the installated docs so that eg
> >
> > % man Apache::Request::Table
> > % man Apache::Cookie::Table
> > % man Apache::Upload::Table
> >
> > all point to the same documentation.
>
> Keeping that in mind...
> with the perl APIs complete, actually I think it's time
> to consider refactoring all the *::Table code into separate
> modules. The table APIs aren't 100% necessary for our perl
> users, and separating them out would reduce the memory footprint
> of Apache::Request, Apache::Upload, and Apache::Cookie.
>
> So what I propose we do is
>
> 1) add to glue/perl/docs:
> Request.pod (replaces xsbuilder/Apache/Request/Request_pod)
> Cookie.pod ( " " " /Cookie/Cookie_pod)
> Upload.pod ( " " " /Upload/Upload_pod)
> Table.pod (new)
> Error.pod (new)
>
> We should use Test::Inline (or something similar) to extract
> basic API tests from these pods. I haven't given this any
> more thought, but hopefully someone can flesh out the details
> a bit to make sure this is workable.
Although you later found not much advantage to separating
out the Apache::*::Table packages, it still seems to make
sense (?) to separate out the Table.pod (as well as
Error.pod), as they're similar.
I could take a look at using Test::Inline to make some basic
API tests (probably this weekend - I'm away for this week).
>From what I understand, one inserts the basic code for a
test within the pod, and then use a supplied script to
extract the tests into a .t test file that is run as usual
(developers do the extraction, so users don't have to
install Test::Inline). So with this it'd probably be a good
idea to have two separate test directories - one for these
tests (requiring Test::More), and the present one using
Apache-Test.
> 2) Factor the Apache::*::Table packages into separate modules.
> If we want to be nice, we could C<<require>> those modules
> whenever Apache::Request or Apache::Cookie generates a table,
> that way users wouldn't notice the table refactoring (yes
> it's a minor performace hit, but IMO reasonable since perl's
> TIEHASH API is really slow anyways).
>
> 3) Have the build system transplant the /docs pods into the blib/
> directory during `make`, replicating Table.pod and Error.pod
> as needed.
So would one have separate Apache::*::(Table|Error)
packages, being essentially clones of each other
(perhaps with appropriate name substitutions)?
--
best regards,
randy