Parrot file list
Mark Sparshatt
In another thread Erik Lechak speculated about the possibility of a getting
started guide. This got me thinking that one of the problems I'd found
starting out was the number of files that Make up the Parrot system and
trying to work out what each of them does.
Basically I'd like to know if there's any sort of listing that gives a
general description of what each file is used for.
If there isn't, I've started making some notes of my own and if anyone else
thinks this would be useful then I can type them up in POD format and send
them in.
Any comments or suggestions would be appreciated
Regards,
Mark Sparshatt
Sean O'Rourke
> Basically I'd like to know if there's any sort of listing that gives a
> general description of what each file is used for.
>
> If there isn't, I've started making some notes of my own and if anyone else
> thinks this would be useful then I can type them up in POD format and send
> them in.
I'd actually like to see this sort of info at the top of each file,
perhaps in the overview section. That way it's less likely to drift away
from reality when existing files are changed or new ones are added. For
files where this is not possible (e.g. the pdds), maybe a per-directory
README or WTFISTHIS could be used instead. Just a thought -- I have
enough trouble keeping the manifest in sync ;).
/s
Tanton Gibbs
one place. It's a nuisance to have to open every file just to see what it
is. By the time I figure out what the 60th file does, I've forgotten what
the first does. It would be nice to have the information at the top of the
file
and then have a program pull it and create a separate file...that way they
are always in sync.
Tanton
Sean O'Rourke
> I agree with this; however, I also think it would be nice to have it all in
> one place. It's a nuisance to have to open every file just to see what it
> is. By the time I figure out what the 60th file does, I've forgotten what
> the first does. It would be nice to have the information at the top of the
> file
> and then have a program pull it and create a separate file...that way they
> are always in sync.
My thoughts exactly. Hopefully the boilerplate comment is regular enough
that this should be easy-ish to write.
/s
Erik Lechak
>Hi all,
>
>In another thread Erik Lechak speculated about the possibility of a getting
>started guide. This got me thinking that one of the problems I'd found
>starting out was the number of files that Make up the Parrot system and
>trying to work out what each of them does.
>
>Basically I'd like to know if there's any sort of listing that gives a
>general description of what each file is used for.
>
>If there isn't, I've started making some notes of my own and if anyone else
>thinks this would be useful then I can type them up in POD format and send
>them in.
>
>
>
Hi, This is Erik,
I was working on this myself. The going is slow because I am trying to
figure out what the files do. I would love to see your list.
I am also trying to document the various structs and their interactions.
Can anyone out there give a brief description of following:
Stash
Arena
Memory_Pool
Buffer
Memory_Block
Small_Object_Pool
Small_Object_Arena
Is there a document out there that describes the genclass.pl script,
Vtable.pm and how pmc files become C files? If I wanted to write a
section on creating a new pmc, what is the simplest one to show? Is
there the equivalent to a hello world pmc? The only documentation in
Vtable.pm says 'No user-serviceable parts inside'. This is funny, but
it didn't help me figure out what is going on.
I found the start of a "getting started" guide a while ago on this
group. I am using that as my starting point. I am surprised that this
guide is not included in the distribution. Are the any other authors
out there that have written useful documentation that is not included in
the dirtribution?
Thanks,
Erik
Brent Dax
# mark sparshatt wrote:
# I am also trying to document the various structs and their
# interactions.
# Buffer
Unfortunately, I'm not a GC person, so this is the only one I recognize.
A Buffer is essentially a handle on a chunk of memory; it stores a
pointer to the memory, the size of the allocation, some flags, etc.
When garbage collection is run, the GC finds all the buffers attached to
the root set (registers, stacks, and symbol tables) or attached to
something attached to the root set, recursively. Any buffers not
attached to the root set are destroyed and their memory is freed for
later use. A Buffer is the (spiritual) superclass of a String, and will
soon be the superclass of a PMC as well.
--Brent Dax <bren...@cpan.org>
@roles=map {"Parrot $_"} qw(embedding regexen Configure)
Wire telegraph is a kind of a very, very long cat. You pull his tail in
New York and his head is meowing in Los Angeles. And radio operates
exactly the same way. The only difference is that there is no cat.
--Albert Einstein (explaining radio)
Erik Lechak
>I agree with this; however, I also think it would be nice to have it all in
>one place. It's a nuisance to have to open every file just to see what it
>is. By the time I figure out what the 60th file does, I've forgotten what
>the first does. It would be nice to have the information at the top of the
>file
>and then have a program pull it and create a separate file...that way they
>are always in sync.
>
>
Hi,
I agree with you completely. I like embedded documents. I would like to
see the docs/dev directory filled up with generated documentation as
part of the build process. I wrote the parrotdoc thing to quickly get
something that will work in C and in Perl and look like it was a
comment. While trying to figure out what the various files,structs, and
functions do in parrot, I was commenting the code. I wanted a way to
autogenerate documents with these comments. But The consensus was to
use POD to do the embedded document thing. I decided not to continue on
the "comment the code route" because I don't like POD. And I think a
good demonstration of why I don't like it is the ops files. I am trying
to think of a polite way to introduce java and python people to the ops
files when they are a mixture of C, POD and perl comments. I would
hate to see all the C files go this route. It will make it unreadable
to anyone that does not use POD.
If parrot decides to go the route of embedding documents in its C code.
Please do not use POD! Find a C developer sitting next to you that does
not know POD and ask them how they like the flow of the ops files.
Someone suggested 'doxygen', I am sure there are several other
document/comment styles out there.
Tanton Gibbs himself wrote:
"I personally find POD distasteful, but since it is the norm, then I think we should stick with it."
POD is not the norm in C, and Parrot can't be stuck in a rut already.
Sorry for the rant,
Erik
Leopold Toetsch
> I am also trying to document the various structs and their interactions.
> Can anyone out there give a brief description of following:
> Arena
> Memory_Pool
> Buffer
> Memory_Block
> Small_Object_Pool
> Small_Object_Arena
I did announce to write a document on the memory management internals
not too long ago. So await somd pod ;-) in the near future.
> Is there a document out there that describes the genclass.pl script,
> Vtable.pm and how pmc files become C files? If I wanted to write a
> section on creating a new pmc, what is the simplest one to show?
$ perldoc docs/vtable.pod
> Is
> there the equivalent to a hello world pmc? The only documentation in
> Vtable.pm says 'No user-serviceable parts inside'. This is funny, but
> it didn't help me figure out what is going on.
Actually "hello world" is not the intent, what a class can do. Classes
implement the behaviuor of e.g PerlIntegers or -hashes.
Your mentioned Vtable.pm is just "use"d by genclass.pl to do some file
parsing, that's all, it's a utility class.
> Thanks,
> Erik
leo
Leopold Toetsch
> ... I decided not to continue on
> the "comment the code route" because I don't like POD. And I think a
> good demonstration of why I don't like it is the ops files. I am trying
> to think of a polite way to introduce java and python people to the ops
> files when they are a mixture of C, POD and perl comments.
Actually docs/core_ops.pod is already autogenerated from core.ops - so I
don't see your point. core.ops is readable and has _all_ the information
in it, what is currently needed to assemble or execute an op code.
And mixture - not really, it's like a perl file:
=something
pod_goes_here
=cut
code_goes_here
.... with one difference, "code_goes_here" is not perl code, but is
translated by perl to generate various files, and yes, has C like
semantics. Please try to read similar solutions that use m4 for such a
task ... brrr.
So don't care much about *.ops, their docu is already autogenerated -
though the contents of the documents is a little bit hmm sparse ;-)
leo
Erik Lechak
I had a response all typed up, but I erased it. I just want to learn
enough so I can start coding, and these pod conversations are just
getting in my way, and I don't want to waste the Parrot communities time
or bandwidth with my trivial issues. Your time is much more valuable
getting perl6 up and running than defending pod.
I think the problem is that this community is a hard-core perl
community, and as such pod is second nature. I imagine that when you
look at a text file that contains pod you don't see all the blank lines,
equal signs, or html looking things that I see, you honestly see a well
formatted document. I have not reached that level of podness.
It would be like me getting frustrated at the Germans because they write
their source code comments in German (no offense to the Germans).
Duh... The name of the mailing list is perl6-internals, and this is
first and foremost the Perl6 interpreter. I got caught up in the
multi-language aspect of Parrot and I guess I was pushing that point. I
am sure that if this group consisted of primarily java programmers there
would be javadocs all over the place.
I hope that the first draft of my "getting started" guide will be ready
on Tuesday. I hope that there will be other newbies out there that can
give me their feedback on the guide.
Sorry for all the bandwidth I chewed up, but at least I got some people
thinking about documentation.
If there are any people out there that want to get involved in parrot
but don't know how or feel intimidated to post to the group, just send
an email to me with your questions or comments and I will try to get
them addressed in the guide.
Thanks,
Erik
Mark Sparshatt
>On Fri, 4 Oct 2002, Tanton Gibbs wrote:
>> I agree with this; however, I also think it would be nice to have it all in
>> one place. It's a nuisance to have to open every file just to see what it
>> is. By the time I figure out what the 60th file does, I've forgotten what
>> the first does. It would be nice to have the information at the top of the
>> file
>> and then have a program pull it and create a separate file...that way they
>> are always in sync.
>
>that this should be easy-ish to write.
I agree with all this.
My first thought had been to have a seperate file containing the list, but
that would prove difficult to maintain.
So at the top of every file there'd be a summary like
=file_summary filename
description
=cut
Then this could be processed by a utility.
As to the format for documentation, I don't think there's any format which is
appreciably better, or worse than any other.
I'm more familiar with JavaDoc than POD but I don't really see how
/**
Some Java documentation
*/
is any better than
=pod
Some POD documentation
=cut
Or maybe it'd be helpful to have a beginners guide to POD, for people who are
more used to another languages doc style.
Best Regards
Mark Sparshatt
Steve Fink
>
> Is there a document out there that describes the genclass.pl script,
> Vtable.pm and how pmc files become C files?
classes/pmc2c.pl has documentation for the last.
perldoc -F classes/pmc2c.pl
> If I wanted to write a section on creating a new pmc, what is the
> simplest one to show? Is there the equivalent to a hello world pmc?
perlint.pmc is probably the closest. Although you might want a "hello
worlds" too -- aggregates are fairly different.