Re: [libgpiod][PATCH 0/4] dedicated examples

[Bartosz Golaszewski <brgl@xxxxxxxx>]

On Wed, Jun 14, 2023 at 5:54 AM Kent Gibson <warthog618@xxxxxxxxx> wrote:
>
> This series forms the basis of a proposal to rework the libgpiod
> examples.
>
> IMHO, the examples have a number of issues including:
>  - no C examples other than the tools - which have become too complicated
>    to be fit for that purpose.
>  - bindings examples focus on simplifications of the tools rather than
>    demonstrating typical use cases.
>  - being more complex than necessary to demonstrate a particular use case.
>  - naming that does not help new users identify the example that
>    demonstrates a particular use case.
>
> To address these issues I propose adding a set of dedicated examples,
> each of which demonstrates one primary use case with as little
> additional fat as possible.  Each example should be named after the use
> case it demonstrates.  Each examples should be implemented for all
> supported languages, to provide examples for users considering
> language choice and for developers to compare the APIs and identify
> areas for improvement.
>
> The examples are explicitly intended to answer "how do I use libgpiod to
> do xxx" questions, with as few distractions as possible.
>
> The examples may demonstrate ancillary features, as long as that is
> relevant to the primary use case. e.g. the watch_line_value examples
> set the line bias and debounce.
>
> The examples should hard code input parameters, not pull them from the
> command line or environment, as that is distracting and frequently more
> complicated than the example itself.
>
> The examples should be standalone - they should not share code.  Large
> chunks of shared code are an indicator that libgpiod probably needs to
> provide additional functionality to simplify use cases.
>
> The examples are not intended to be distributed in binary form, but
> could be incorporated into the documentation.
>
> The set of examples provided is a starter set that answer the following
> questions:
>  - how do you get the value of a line?
>  - how do you set the value of a line?
>  - how do you watch for edge events on a line?
>  - how do you watch for edge events asynchronously (e.g. using poll())?
>
> I didn't add the latter in Rust as that should be done using one of the
> many available async reactors and I didn't want to pick one or pull in
> any dependencies.
>
> I expect that this proposal may be contraversial, and that is one of the
> reasons I've kept the starter set small.
>
> Cheers,
> Kent.
>
> Kent Gibson (4):
>   core: examples: add dedicated examples
>   bindings: cxx: examples: add dedicated examples
>   bindings: python: examples: add dedicated examples
>   bindings: rust: examples: add dedicated examples
>
>  Makefile.am                                   |   6 +
>  bindings/cxx/examples/.gitignore              |   4 +
>  bindings/cxx/examples/Makefile.am             |  14 +-
>  .../cxx/examples/async_watch_line_value.cpp   |  78 ++++++++++
>  bindings/cxx/examples/get_line_value.cpp      |  29 ++++
>  bindings/cxx/examples/toggle_line_value.cpp   |  45 ++++++
>  bindings/cxx/examples/watch_line_value.cpp    |  62 ++++++++
>  .../python/examples/async_watch_line_value.py |  47 ++++++
>  bindings/python/examples/get_line_value.py    |  26 ++++
>  bindings/python/examples/toggle_line_value.py |  47 ++++++
>  bindings/python/examples/watch_line_value.py  |  42 ++++++
>  .../rust/libgpiod/examples/get_line_value.rs  |  28 ++++
>  .../libgpiod/examples/toggle_line_value.rs    |  43 ++++++
>  .../libgpiod/examples/watch_line_value.rs     |  50 +++++++
>  configure.ac                                  |   1 +
>  examples/.gitignore                           |   7 +
>  examples/Makefile.am                          |  17 +++
>  examples/async_watch_line_value.c             | 136 ++++++++++++++++++
>  examples/get_line_value.c                     |  97 +++++++++++++
>  examples/toggle_line_value.c                  | 106 ++++++++++++++
>  examples/watch_line_value.c                   | 127 ++++++++++++++++
>  21 files changed, 1011 insertions(+), 1 deletion(-)
>  create mode 100644 bindings/cxx/examples/async_watch_line_value.cpp
>  create mode 100644 bindings/cxx/examples/get_line_value.cpp
>  create mode 100644 bindings/cxx/examples/toggle_line_value.cpp
>  create mode 100644 bindings/cxx/examples/watch_line_value.cpp
>  create mode 100755 bindings/python/examples/async_watch_line_value.py
>  create mode 100755 bindings/python/examples/get_line_value.py
>  create mode 100755 bindings/python/examples/toggle_line_value.py
>  create mode 100755 bindings/python/examples/watch_line_value.py
>  create mode 100644 bindings/rust/libgpiod/examples/get_line_value.rs
>  create mode 100644 bindings/rust/libgpiod/examples/toggle_line_value.rs
>  create mode 100644 bindings/rust/libgpiod/examples/watch_line_value.rs
>  create mode 100644 examples/.gitignore
>  create mode 100644 examples/Makefile.am
>  create mode 100644 examples/async_watch_line_value.c
>  create mode 100644 examples/get_line_value.c
>  create mode 100644 examples/toggle_line_value.c
>  create mode 100644 examples/watch_line_value.c
>
> --
> 2.40.1
>

Great idea! I applied patches 1-3 with some tweaks (coding style, C++
comments, statify functions, put local functions into anonymous
namespaces for C++, apply black to python code etc. etc.).

You can respin the rust patch separately.

Thanks
Bart