[lttng-dev] Babeltrace python bindings documentation is no up-to-date

[Philippe Proulx]

On Mon, Oct 31, 2016 at 4:02 PM, Jean Spector <jean.spector at gmail.com> wrote:
> Thank you Philippe.
>
> Adding a different documentation page for older versions (it's the latest
> package on RHEL 7.2 - so I'd expect more newbies to encounter this issue)
> could help anyone trying the Python bindings for the first time.
> I'm sure you realize that trying the official example and failing can be
> quite frustrating and could turn off potential users.

I'll make sure to make the doc as clear as possible. The main problem here is
that the module is simply not Sphinx-documented in Babeltrace 1.x. I guess
I could search and replace the package names in the doc before publishing it.
I'll find a way to make it clear anyway.

> This is especially
> true if it comes after other issues(let me know if you'd prefer these to be
> sent in separate emails):
>
> RHEL 7.2 uses python 3.4, but babeltrace-python-1.2.4 requires python 3.3,
> which is not available anymore - at least not out of the box.

What do you mean? The bindings work just fine with Python 3.4 and Python 3.5.

> Again, I've solved the issue for myself, so it's not a support call. The
> idea is that it would be great if the initial install+run stage was made
> less painful.
> I believe it would increase the user base as, for instance, I was on the
> verge of giving up after building from source has also failed for me.
>
> When trying to build from latest stable source (1.4.0) on RHEL 7.2, I've
> encountered a couple of issues:
>
> configure would fail on popt. "ln -s /usr/lib64/libpopt.so.0
> /usr/lib64/libpopt.so" worked around the issue, but there must be a better
> way (or a line in the README).
> "python3 -c 'import babeltrace'" would fail with "ImportError:
> /usr/local/lib64/python3.4/site-packages/babeltrace/_nativebt.so: undefined
> symbol: PyInstance_Type"
>
> That's where I gave up trying to build from source. It could be due to the
> same python 3.4 - but it's just a guess.

The official channel for reporting bugs is the bug tracker
<https://bugs.lttng.org/projects/babeltrace/>. If you create an issue there, we
can ask for details about the environment and context and track the bug to
remember it.

I have no idea what's going wrong here, but if you create an issue we
can test the
same environment (RHEL 7.2) and see if we can reproduce the bug.

>
> ==========
>
> To recap, I see 3 issues here:
>
> Documentation - any platform
> Install of the latest  babeltrace-python (1.2.4) - RHEL 7.2
> Building from the latest stable source (1.4.0) - RHEL 7.2
>
>
> In any case, thanks for the great tool. I hope to put it to good use.
> Jean

Thanks for the feedback! We appreciate.

Phil

>
>
> On Mon, Oct 31, 2016 at 7:07 PM, Philippe Proulx <eeppeliteloop at gmail.com>
> wrote:
>>
>> On Sat, Oct 29, 2016 at 9:55 AM, Jean Spector <jean.spector at gmail.com>
>> wrote:
>> > When trying to use the example from
>> > http://diamon.org/babeltrace/docs/python/examples/ (pointed to via
>> > http://lttng.org/viewers/), the code is not up-to-date.
>> >
>> > For instance, the first line in the example (import babeltrace.reader)
>> > fails
>> > as there's no 'reader' to import.
>> >
>> > I've managed to get over it, but thought it would be better to have a
>> > working example code.
>>
>> I wrote this doc and it was merged into master more than a year ago.
>> When writing this doc, I split the `babeltrace` package into the
>> `reader` and `writer` subpackages to make the autodocumentation with
>> Sphinx easier. Now it looks like this split was never backported to
>> v1.2, v1.3, v1.4, and soon v1.5.
>>
>> The `Babeltrace 1.2.0` version you see on the front page is just the
>> current version found when I generated the online version. Really, the
>> title should say `Babeltrace (master branch)`. The master branch will
>> become Babeltrace 2.0 soon. In the meantime, simply drop the `reader`
>> subpackage when you read the doc and try examples. So
>>
>>     import babeltrace.reader as btreader
>>
>>     trace_collection = btreader.TraceCollection()
>>
>> becomes
>>
>>     import babeltrace as btreader
>>
>>     trace_collection = btreader.TraceCollection()
>>
>> For the CTF writer part, drop the `writer` subpackage, and import the
>> `CTFWriter` class: you'll find all the documented classes within this
>> class (kind of weird, and one of the reasons I created a subpackage
>> instead):
>>
>>     import babeltrace.writer as btwriter
>>
>>     writer = btwriter.Writer(trace_path)
>>
>> becomes
>>
>>     from babeltrace import CTFWriter as btwriter
>>
>>     writer = btwriter.Writer(trace_path)
>>
>> Note that the new subpackage split is backward compatible with the
>> bindings of v1.x, so the code you write now will continue to work...
>> forever.
>>
>> I might add an equivalent of this response as a note in the generated
>> documentation.
>>
>> BR,
>> Phil
>>
>> >
>> > P.S. I'm running RHEL 7.2 with babeltrace-python-1.2.4-1.el7.x86_64
>> >
>> > Best Regards,
>> > Jean
>> >
>> >
>> > _______________________________________________
>> > lttng-dev mailing list
>> > lttng-dev at lists.lttng.org
>> > https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
>> >
>
>