[Boost-users] [Stacktrace] Second review begins today 17th Mar ends 26th Mar

Subject: [Boost-users] [Stacktrace] Second review begins today 17th Mar ends 26th Mar
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-03-17 15:09:05

I am pleased to announce the second review of the proposed
Boost.Stacktrace library running from today until Sunday 26th.

Stacktrace is an optionally header-only library providing multiple
implementation backends. At its very simplest it lets you capture the
stack backtrace for the calling thread and to print it to a
std::ostream& of your choice. The basic_stacktrace<> class quacks
like a STL container of frame object instances. The rest of the API
pretty much follows STL design principles for the most part. Use is
therefore unsurprising.

You can find the documentation at
http://apolukhin.github.io/stacktrace/index.html and the github repo
at https://github.com/apolukhin/stacktrace.

Review guidelines
=================
This is a second review of this library with many changes implemented in
response to feedback from the previous review. My previous review report
can be found at http://lists.boost.org/boost-announce/2017/01/0486.php
where I made the following conditions for acceptance:

1. That the documentation more clearly set out what Stacktrace does and
especially does not do, and that the default facilities provided are
those of the Minimum Viable Product described above i.e. no source file
nor line number discovery, no external dependencies on libraries not
always provided on the target platform, no invocation of child
processes, no async safety during stacktrace parsing. Stacktrace ought
to be pared back to the minimum viable product featureset with no
external dependencies at all.

2. That suitable predefined macros opt in to additional functionality
such as serialisation of offset translated backtraces, retrieval of
source code path and line number etc. Enabling these may introduce
dependencies on third party libraries not always present on a system
such as libunwind, or on third party helper utilities such as addr2line.

I would recommend that the APIs the use of which are dependent on such
third party items are entirely compiled out of Stacktrace when the macro
enabling them is not defined.

3. That the documentation describe ONLY the default minimum viable
product functionality in its tutorial and quick start. All extra
functionality enabled by macros is to be relocated into a separate
documentation section away from the main documentation e.g.
"Advanced/optional features".

4. That APIs made available only when a given macro has turned them on
are documented as such in the API reference docs.

Antony hasn't entirely met my conditions, hence this second review. He
has instead implemented this changelog:

* Reimplemented boost::stacktrace::basic_stacktrace class to accept
allocators and to have a small size
* Added outputting of the path to the binary object into the
stacktrace, when source location is not available
* Allowed to use `libbacktrace` - a defacto standard for GCC/CLANG
backtracing that does not fork and has a permissive license
* Optimized stacktrace and frames ostreaming
* Removed backends and made the default tracing to have only platform
basic functionality. Added macros to enable additional functionality.
* Fixed (theoretically) MinGW compilation
* Added functions for async-safe dumping into memory or descriptor
* Changed signal handling example to be async-signal-safe
* Allowed users to choose how many frames to skip during stack capture
* Removed `boost::stacktrace::stacktrace` functions and other
internals from printed stack traces
* Updated docs:
    * examples now use Boost.Exception
    * removed all the references to "backend"
    * reduced macro count
    * "Build, Macros and Backends" section was rewritten and became
"Configuration and Build"
    * added note that library is C++03
    * added examples on storing traces into shared memory
    * updated all the human readable dumps

It is up to the Boost community as to whether this revised library is
now acceptable without any conditions, or with conditions.

Reviews should be submitted to the developer list
(boost_at_[hidden]), preferably with '[stacktrace]' in the
subject. Or if you don't wish to for some reason or are not
subscribed to the developer list you can send them privately to me at
's_sourceforge at nedprod dot com'. If so, please let me know whether
or not you'd like your review to be forwarded to the list.

For your review you may wish to consider the following questions:
      - What is your evaluation of the design?
      - What is your evaluation of the implementation?
      - What is your evaluation of the documentation?
      - What is your evaluation of the potential usefulness of the
        library?
      - Did you try to use the library? With what compiler? Did you
        have any problems?
      - How much effort did you put into your evaluation? A glance? A
        quick reading? In-depth study?
      - Are you knowledgeable about the problem domain?

And finally, every review should attempt to answer this question:

      - Do you think the library should be accepted as a Boost
library?

Be sure to say this explicitly so that your other comments don't
obscure your overall opinion.

Even if you do not wish to give a full review any technical comment
regarding the library is welcome as part of the review period and
will help me as the review manager decide whether the library should
be accepted as a Boost library. Any questions about the use of the
library are also welcome.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/