A sketch of a command-line interface for apitrace

José Fonseca jose.r.fonseca at gmail.com
Tue Oct 25 14:51:59 PDT 2011


On Tue, Oct 25, 2011 at 9:01 PM, Carl Worth <cworth at cworth.org> wrote:
>
> Thanks for the quick feedback, José.
>
> On Tue, 25 Oct 2011 19:47:10 +0100, José Fonseca <jose.r.fonseca at gmail.com> wrote:
>> >   replay       Replay the given trace visually
>>
>> s/replay/retrace" for consistency with code and documentation.
>
> I consciously avoided "retrace" because we're _not_ actually tracing
> anything again, (that is, not unless you run something like:
>
>        apitrace trace apitrace replay <trace>

"trace" here is a metaphor, and so is "retrace".  I understand your
interpretation of "retrace", but the intended reading is trace==
record, and retrace==replay, as in "retracing repeats the same steps
that were done when tracing".

I admit I could have chosen record/replay, but trace/retrace had a
better sound to it, and that's how the docs and code are named now.
Furthermore, it ties in nicely with the project name, "apitrace".  So
for good or worse, I'd like to stick with the "trace/retrace" naming
convention.

>> Much more interesting would be to specify a qualitative frequency,
>> such as "/draw", "/framebuffer", or "/frame", to specify every draw
>> call, every frambuffer object change, or every frame, respectively.
>
> Yes, we'll need something to capture this (like the existing -S=WHEN
> option to glretrace). My plan for that, (which I neglected to capture in
> the writeup), was a separate option --every=WHEN. I think this can
> combine well with the existing numeric --frames selection:
>
>        apitrace dump-images --frames=200-300 --every=draw
>
> I had imagined this --every option to be something unique to
> dump-images. But it is similar to the --functions=REGEXP I proposed,
> (simply providing a few named classes for which functions are considered
> to be "draw" functions or frame boundaries). So I'll give some thought
> to what we might do here for a general option.

Sounds good.

[...]

> You said "diff-trace" where I had simply "dump". Which direction would
> you like to resolve that? I like getting away from any command that's
> not strictly "diff", but I'm not sure that "apitrace dump-trace <trace>"
> makes it very clear what this operation is doing. So what might we name
> this case? How about dump-calls and diff-calls? Any other idea?

Given we're not doing the magical diff anymore, what about having the
suffixless verbs refer to traces, i.e.,

      object     dump verb    diff verb
      -----------------------------------------
      trace        dump        diff
      state        dump-state    diff-state
      images    dump-images  diff-images
      ...

therefore, the most common operation is more succint.

>> BTW, for trim, it would be really sweet if it could take a tracedump
>> output as input of which frames to select. This would make the process
>> really versatile: somebody will dump the trace to a file, open the
>> ascii text dump on vim/emacs/etc, manually delete the calls it doesn't
>> care, and then obtain a new one.
>
> Good idea. We could also generalize all the commands to take any of our
> formats (trace, calls, state, or images) as a means of specifying which
> calls/frames to dump/compare/etc. We're basically already doing that in
> the diff case, so it would be nice to make that common for trim,
> etc. (It would be nice even for "apitrace trace". After carefully
> trimming one trace, I could easily create a new one trimmed just right
> From the start without having to go through a separate trim operation.)
>
[...]
>> Minor details are subject to personal taste, but overall this looks
>> quite nice.
>
> Thanks. I think doing this design work upfront is really going to pay
> off as good usability in the long term.
>
>> I suppose that apitrace and qapitrace would live in /usr/bin, and
>> everything else in /usr/lib/apitrace/...
>
> Or you could require "apitrace gui" to get the gui and have only
> apitrace in /usr/bin. Your call on that one.

I'll defer to Zack here.  But from my POV, the GUI should be a equal
citizen as the CLI. One can imagine that certain users might want to
use strictly the GUI.

>> Just one general question: is your plan to re-implement all the python
>> scripts in C, or do you foresee a mixture of commands in C++/Python,
>> at least transitorily?
>
> Since we already have to do all the path-searching stuff to setup our
> LD_PRELOAD (or whatever) for "apitrace trace" I think there's very
> little additional code needed to exec existing scripts written in
> python, etc. And I definitely prefer to use existing code rather than
> writing new code where I can.
>
> It wouldn't even be too hard to support a common convention where
> dropping a new program into /usr/lib/apitrace/apitrace-foo means that
> "apitrace foo" now works, (and could even list the new command in
> "apitrace help" and call out to "apitrace-foo --help" for "apitrace help
> foo").

That means that we'll need to make a seprate shared library (to avoid
linking the common code on every executable). It needs to be separate
because the wrappers must not depend on any shared library, so still
need a statically linked common library.

> So that argues for at least renaming existing things like tracediff.sh
> to /usr/lib/apitrace/apitrace-diff-calls or so. This apitrace- prefix
> for binaries might even be enough so that we don't need a separate /bin
> under /usr/lib/apitrace.

That's fine. I care about backwards compatibility in terms of
functionality, but not so much interface: I'm fine renaming command
options if it makes sense.

The only tricky business here is that on windows the .py extension is
required. We can always fix up at install time, but in the git tree
the scripts should be named either with .py or without, so I'm not
sure what's best.

Jose


More information about the apitrace mailing list