This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [Perftools]Re: tapset howto?


Hi -


> [...]
> > How would you justify much effort on runtime documentation?
> 
> Because people other than you use it and have questions. 

Are these questions of the sort that more doxygen markup would
necessarily preempt?  Direct use of the runtime outside systemtap is
unlikely to become a priority.

> It is used in tapsets.  

I foresee this being the case less and less.  In particular, other
than a small group of existing routines are given a script-side
handler

> Porting the arch-dependent pieces and testing it is necessary for
> supporting new cpus.

OK.  Depending on the scale of code involved, one might use ordinary
comments or file groupings to highlight portworthy areas.


> > There is not a substantial difference.  A script in .../tapset can
> > contain any mixture of global/probe/probe-alias/function definitions,
> > and may satisfy and generate external references with respect to other
> > scripts.  The translator attempts to automatically resolve all these
> > kinds of references.
> 
> From an implementation standpoint, there is no difference. From a script
> developer's standpoint, there is a huge difference.  We need to collect
> utility functions, that basically extend the language, group them
> together and document them well. That way all scripts and tapsets can
> make use of them.

Your formulation misses my point.  By virtue of the automatic
resolution logic in the translator, *all* scripts provide new
"builtins" or "utilities", whether they be global variables, probe
point aliases, or functions.  All tapset scripts need to be written to
enable and exploit the same kind of reuse.


> > > We need some standard for documenting tapset functions. 
> > 
> > Like stapfuncs(5), stapprobes(5), and future stapvars(5)?  Maybe
> > slicing the same content up "horizontally" (by tapset rather than by
> > exported artifact category) would also make sense, and maybe this can
> > be accomplished by mechanical means.
> 
> When we have a few dozen tapsets, I think you will not enjoy paging
> through enormous man pages. Each tapset needs to be documented
> individually and the tapset documentation automatically merged by some
> means. 

That is what I meant by slicing it up horizontally.  Which form ends
up being written by hand vs. machine doesn't make much difference.

> And it needs to be easily searchable and indexed. [...]

What more than (say) apropos(1) do you envision for this?


- FChE

Attachment: pgp00000.pgp
Description: PGP signature


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]