2010Q3 Grant Proposal: Improve Parrot Embed/Extend Subsystem Tests and Documentation
Sun, 01-Aug-2010 by
Alberto Simões
edit post
<![CDATA[
<h1>Improve Parrot Embed/Extend Subsystem Tests and Documentation</h1>
<dl>
<dt><strong>Name:</strong></dt>
<dd>
<p>Jonathan "Duke" Leto.</p>
</dd>
<dt><strong>Email:</strong></dt>
<dd>
<p>[hidden email]</p>
</dd>
<dt><strong>Amount Requested:</strong></dt>
<dd>
<p>$1500</p>
</dd>
</dl>
<p>
</p>
<h2>Synopsis</h2>
<p>Currently the Parrot [0] Embedding subsystem is under-tested and under-documented.
This grant proposes to add documentation for all public Embed/Extend API
functions, write tests to increase the code coverage statistics for the
Embed/Extend API to at least 95%, and update the Parrot Developer Docs (PDDs) [1]
where errors or omissions are found. Any bugs found on the way that cannot be
easily fixed will be reported on the Parrot Trac bug-tracker with test cases.</p>
<h2>Benefits to the Perl Community</h2>
<p>There are many projects that will benefit from a completely documentated and
thoroughly tested Parrot Embed Subsystem. Rakudo Perl 6 [2] is built on Parrot, so
people who want to embed Rakudo Perl 6 in any other application will benefit.
Blizkost is a bridge between Perl 5 and Parrot, and embeds both, so will greatly
benefit from good documentation and tests. PL/Parrot [3] is a project that aims to
embed Parrot in the PostgreSQL database [4]. Because Parrot is embedded in
PostgreSQL, any language that runs on Parrot then can easily be embedded.
PL/Perl6 is part of the PL/Parrot project, which loads Rakudo Perl 6 bytecode
and therefore embeds a Perl 6 interpreter inside of PostgreSQL, for use in
writed stored procedures. All of these projects will grealy benefit from
complete documentation, as well any any future applications that want to embed
or extend Parrot.</p>
<p>
</p>
<h2>Deliverables</h2>
<p>According to the code coverage stats [5] for Embed Extend API in Parrot Subversion
revision 48100, the code coverage of src/embed.c is 65.2%, src/extend.c is
71.2% and src/extend_vtable.c is 5.3%. All of these will be raised to at least
95% by writing the appropriate tests.</p>
<p>The embed API documentation in docs/embed.pod [6] contains many parts which are missing
documentation, such as the "Lexicals", "Type Signatures" and "Constants" sections.
This will be filled with the appropriate documenation as it works currently.</p>
<p>A blog post will also be made on a blog syndicated by Perlsphere, describing
how the grant proceeded, lessons learned, bugs found, a summary of tests written
and links to the new documentation.</p>
<p>
</p>
<h2>Project Details</h2>
<p>Currently only about 5 of over 180 functions in src/extend_vtable.c have
test coverage. This will likely require around 50 tests fully cover
each function, but this number can vary depending on the size of a test. The
majority of these tests are simply calling a variety of VTABLE functions
on PMCs, so each test has roughly the same structure. These tests will be
added to t/src/extend_vtable.t (a new test file) and written in Perl 5.</p>
<p>The test coverage for src/embed.c and src/extend.c is much higher, so fewer
tests will be required, but these tests will be more complicated due to the
necessity of testing corner cases. Much of the uncovered code in src/embed.c
relates to dealing packfiles and bytecode, error handling with I/O and using
non-default runcores. These tests will be added to t/src/embed.t and
t/src/extend.t, respectively, and written in Perl 5.</p>
<p>The documentation part of this grant should be straight-forward, but anything
that needs to be clarified will be put to the parrot-dev mailing list.</p>
<p>
</p>
<h2>Inch-stones</h2>
<p>The first inch-stone will be updating docs/embed.pod to contain the "Lexicals",
"Type Signatures" and "Constants" sections. This should take one to two weeks.</p>
<p>The next two inch-stones will be to raise extend_vtable.c to 50% and then 95%
coverage. This splits the work roughly in half, and I expect each to take
roughly 2 weeks.</p>
<p>The tests for embed.c are fewer but will be trickier, so I expect to have
two inch-stones, one for 80% coverage and the other for 95% coverage, and
I expect each to take about 2-3 weeks.</p>
<p>The last inch-stone will be the easiest: writing and publishing the blog post.
I expect this to take about a day.</p>
<p>
</p>
<h2>Project Schedule</h2>
<p>I expect to be able to work about 5-10 hours per week, starting in October,
so it does not conflict with Google Summer of Code. I expect that at this
pace, this grant will take about 2-3 months to finish, taking into account
that I may not work as much around the holidays.</p>
<p>
</p>
<h2>Completeness Criteria</h2>
<p>Since this work will not change any features, it can be committed directly
to Parrot SVN trunk incrementally. When the code coverage statistics have
all reached >= 95%, the missing sections of documentation have been written
and the blog post has been published, this grant will be considered complete.</p>
<p>
</p>
<h2>Bio</h2>
<p>I've hacked on Parrot Virtual Machine ever since I attended a Parrot Hackathon
in 2008. I started off hacking on the Perl 6 test suite, after getting a commit
bit from Larry at the hackathon due to my interest in fixing some bugs and
adding tests relating to math functions and complex numbers. This quickly led me
to bugs in Parrot, and I have mostly been writing tests and fixing bugs for the
Parrot test suite ever since. I have converted large partions of the test suite
from Perl 5 to PIR, as well as implementing parts of Test::More and a TAP Parser
in PIR. I am also the organization administrator for The Perl Foundation/Parrot
Foundation in Google Summer of Code 2010, as well as a mentor for Parrot on RTEMS [7].</p>
<p>I also hack on a project called PL/Parrot, which embeds Parrot and Rakudo Perl
6 into the PostgreSQL database. It is one of the first projects to embed Parrot
in other applications, the others being mod_parrot and Blizkost. I believe it
is the first project to embed Rakudo Perl 6. In the course of hacking on
PL/Parrot, I have written tests for the Parrot embedd/extend API and fixed
documentation, as well as contributing patches and tests for Rakudo.</p>
<p>Since I am a Parrot Core Developer, I can commit directly to Parrot trunk, which
is the best scenario, since everyone will benefit incrementally from better code
coverage and documentation.</p>
<p>As for other credentials, I have a Masters in Mathematics from University of
Central Florida and have published various papers on differential equations,
as well as being a coauthor of the Google Summer of Code Mentor Manual [8].</p>
<p>
</p>
<h2>References</h2>
<p>[0] <a href="http://parrot.org">http://parrot.org</a></p>
<p>[1] <a href="http://docs.parrot.org/parrot/latest/html/pdds.html">http://docs.parrot.org/parrot/latest/html/pdds.html</a></p>
<p>[2] <a href="http://rakudo.org">http://rakudo.org</a></p>
<p>[3] <a href="http://pl.parrot.org">http://pl.parrot.org</a></p>
<p>[4] <a href="http://postgresql.org">http://postgresql.org</a></p>
<p>[5] <a href="http://tapir2.ro.vutbr.cz/cover/cover-results/">http://tapir2.ro.vutbr.cz/cover/cover-results/</a></p>
<p>[6] <a href="http://docs.parrot.org/parrot/devel/html/docs/embed.pod.html">http://docs.parrot.org/parrot/devel/html/docs/embed.pod.html</a></p>
<p>[7] <a href="http://rtems.org">http://rtems.org</a></p>
<p>[8] <a href="http://en.flossmanuals.net/GSoCMentoringGuide">http://en.flossmanuals.net/GSoCMentoringGuide</a></p>
]]>
Comments (5)
I'm not familiar with the Parrot documentation and test suite, but this sounds like a good idea. One of the really strong points that the Perl community has right now is the prevalence of testing that we've developed over the years. It would be good to continue this.
I'd certainly like to see this work done.
I'd just add that it would be good to have a discussion to review the current API design before it gets 'pinned down' by docs and tests. That could be done while waiting for grant approval.
I'm in favor of any attempt to improve existing Parrot documentation. My question is sort of vague and hand-wavey. Sorry about that.
I respect the desire to wait for the dust to settle on the current API design. At the same time, an API design review could take a while and documentation is needed soon. If you implemented the documentation now, how could you minimize the impact of underlying code changes on your work?
Tim: Thanks for your encouragement. I have sent this proposal to parrot-dev and will ask if any changes in the current API design are planned.
The latest version of this proposal can be found at:
http://github.com/leto/proposals/blob/master/TPF/Improve_Parrot_Embedding.pod
As a side note I would like to say that my feeling about funding a parrot grant, now with the Parrot Foundation, is exactly the same as before it getting alive. Parrot can be used to implement another programming languages, but it is still a Perl community project, and Parrot developers are working closely with Rakudo developers on getting Perl 6 into existence.
