[PATCH v5 0/9] document and simplify use of cmdline

[Bruce Richardson <bruce.richardson@intel.com>]

The DPDK commandline library is widely used by apps and examples within
DPDK, but it is not documented in our programmers guide and it requires
a lot of boilerplate code definitions in order to used. We can improve
this situation by creating a simple python script to automatically
generate the boilerplate from a list of commands.

This patchset contains a new documentation chapter on cmdline library,
going through step-by-step how to add commands and create the necessary
token lists and parse contexts.

Following that initial doc patch, the set then contains a
boilerplate-generating script, as well as a set of four patches showing
its use, by converting four examples to use the script instead of
having the hard-coded boilerplate. Once the script is used, adding a new
command becomes as simple as adding the desired command to the .list
file, and then writing the required function which will be called for
that command. No other boilerplate coding is necessary.

Final two patches, new in V5, add support for option-lists in values,
and then use that support to convert over a fifth sample app - ntb.

Cmdline script obviously does not cover the full range of capabilities
of the commandline lib, but does cover the most used parts. The
code-saving to each of the examples by auto-generating the boilerplate
is significant, and probably more examples with commandlines can be
converted over in future.

The "cmdline" example itself, is not converted over, as it should
probably remain as a simple example of direct library use without the
script.

V5:
* Added copyright headers to command list files
* Add support for option lists
* Convert examples/ntb to use script

V4:
* Reworked script following feedback from Robin J.
   - formatted code with black
   - used multi-line strings
   - replaced sys.exit(1) with proper error handling
   - per-command function returns lists rather than printing directly
   - other small cleanups
* Added change to CI script so the cmdline script is in PATH
* Converted VDPA example to script, saving another 100 LOC

V3:
* Added lots of documentation
* Added support for help text for each command
* Cleaned up script a little so it passes pycodestyle and most flake8
  checks, when line-length is set to max 100.
* Removed RFC tag, as I consider this patchset stable enough for
  consideration in a release.

V2-RFC:
* Add support for IP addresses in commands
* Move to buildtools directory and make installable
* Convert 3 examples to use script, and eliminate their boilerplate

Bruce Richardson (9):
  doc/prog_guide: new chapter on cmdline library
  buildtools: script to generate cmdline boilerplate
  ci: allow use of DPDK tools when building examples
  examples/simple_mp: auto-generate cmdline boilerplate
  examples/hotplug_mp: auto-generate cmdline boilerplate
  examples/bond: auto-generate cmdline boilerplate
  examples/vdpa: auto-generate cmdline boilerplate
  buildtools/dpdk-cmdline-gen: support option strings
  examples/ntb: auto-generate cmdline boilerplate

 .ci/linux-build.sh                            |   1 +
 app/test/commands.c                           |   2 +
 buildtools/dpdk-cmdline-gen.py                | 197 ++++++++
 buildtools/meson.build                        |   7 +
 doc/guides/prog_guide/cmdline.rst             | 470 ++++++++++++++++++
 doc/guides/prog_guide/index.rst               |   1 +
 examples/bond/Makefile                        |  12 +-
 examples/bond/commands.list                   |   6 +
 examples/bond/main.c                          | 161 +-----
 examples/bond/main.h                          |  10 -
 examples/bond/meson.build                     |   8 +
 examples/multi_process/hotplug_mp/Makefile    |  12 +-
 examples/multi_process/hotplug_mp/commands.c  | 147 +-----
 examples/multi_process/hotplug_mp/commands.h  |  10 -
 .../multi_process/hotplug_mp/commands.list    |   8 +
 examples/multi_process/hotplug_mp/meson.build |   9 +
 examples/multi_process/simple_mp/Makefile     |  12 +-
 examples/multi_process/simple_mp/meson.build  |   9 +
 .../multi_process/simple_mp/mp_commands.c     | 106 +---
 .../multi_process/simple_mp/mp_commands.h     |  14 -
 .../multi_process/simple_mp/mp_commands.list  |   6 +
 examples/ntb/Makefile                         |  12 +-
 examples/ntb/commands.list                    |  11 +
 examples/ntb/meson.build                      |   7 +
 examples/ntb/ntb_fwd.c                        | 200 +-------
 examples/vdpa/Makefile                        |  12 +-
 examples/vdpa/commands.list                   |   8 +
 examples/vdpa/main.c                          | 131 +----
 examples/vdpa/meson.build                     |   7 +
 29 files changed, 863 insertions(+), 733 deletions(-)
 create mode 100755 buildtools/dpdk-cmdline-gen.py
 create mode 100644 doc/guides/prog_guide/cmdline.rst
 create mode 100644 examples/bond/commands.list
 delete mode 100644 examples/bond/main.h
 delete mode 100644 examples/multi_process/hotplug_mp/commands.h
 create mode 100644 examples/multi_process/hotplug_mp/commands.list
 delete mode 100644 examples/multi_process/simple_mp/mp_commands.h
 create mode 100644 examples/multi_process/simple_mp/mp_commands.list
 create mode 100644 examples/ntb/commands.list
 create mode 100644 examples/vdpa/commands.list

--
2.39.2