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

Tue Nov 1 05:52:07 UTC 2016

I couldn't reproduce the issues I had when building from source on my VM
and don't have a vanilla RHEL 7.2 now to reproduce :-(

Regarding documentation, current changes look all right. Adding a note
regarding software collections will certainly help.

There's another minor issue I see in the docs. They mention the package
name on Debian and Ubuntu, but not on RHEL and Fedora - even though there's
an rpm available.

In any case, thank you very much for your help.

-Jean

On Nov 1, 2016 02:52, "Philippe Proulx" <eeppeliteloop at gmail.com> wrote:

> On Mon, Oct 31, 2016 at 4:38 PM, Philippe Proulx
> <eeppeliteloop at gmail.com> wrote:
> > 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.
>
> Jean,
>
> See <http://diamon.org/babeltrace/docs/python/> again.
>
> I added an important admonition to each page which at least explains what
> to do if you're using Babeltrace 1.x. Plus the indicated version is
> now `2.0.0-pre`.
>
> It should not be so complicated to understand for newcomers. That's the
> best
> I can do for the moment; writing a different version for Babeltrace
> 1.x is out of
> the question.
>
> Phil
>
> >
> >> 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
> >>> >
> >>
> >>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.lttng.org/pipermail/lttng-dev/attachments/20161101/6177013f/attachment.html>