CLI: add `run` command and make `convert` command use it
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Fri, 3 Mar 2017 05:13:36 +0000 (00:13 -0500)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Sun, 28 May 2017 16:57:38 +0000 (12:57 -0400)
commitdb0f160afd671de44e52d2b364de957ddccdac02
tree841b3ccab032fdc6f0b582b32c0e648e927fcef5
parente027ff8c5de4bcf3584fc7de7615af295024e90c
CLI: add `run` command and make `convert` command use it

This patch adds the babeltrace(1) command `run` which is essentially the
same as the current `convert` command without the magic stuff (legacy
options and their interesting constraints), plus this:

* You can set the name of a component by prefixing the --source,
  --filter, or --sink option's argument with `NAME:`. You can escape
  `.`, `:`, and `\` with `\`. Example:

      --source=instance:ctf.fs --sink=my-text:text.text
      --filter='my\.name:my\.plugin.my\.comp\.cls'

  This is the equivalent of:

      --source=ctf.fs --name=instance --sink=text.text --name=my-text
      --filter='my\.plugin.my\.comp\.cls' --name my.name

  The --name option still exists: it sets the current name of the
  current component, so that, with this:

      --sink=a:b.c --name=salut --name=bonjour

  the effective name of this component is `bonjour`.

* You can use the new --key and --value options to add one string
  initialization parameter to the current component. The name of this
  parameter is given by the last --key option's argument, and its value
  by the --value option's argument. Examples:

      --source=ctf.fs --key=path --value ~/lttng-traces/...
      --key=path --source=ctf.fs --value ~/lttng-traces/...

  This is useful to not care about the specific escaping required by the
  --params option format for a string parameter, to use any parameter
  name, and to use shell expansion for the value (tilde expansion for
  example, as --path is not a `run` command's option).

The `convert` command is now a specialization of the `run` command,
specific to a _conversion graph_ (whereas the terminology for what you
build with the `run` command is a _processing graph_). The conversion
graph that the `convert` command builds always has the following
topology:

    sources -> utils.muxer -> [utils.trimmer] -> lttng-utils.debug-info -.
           .-------------------------------------------------------------'
           '-> [user filters] -> sinks

There's no more --connect option in the `convert` command. When you run
the `convert` command, it prepares the equivalent `run` command
arguments and invokes the latter directly. However if `-o ctf-metadata`
exists, a new "print CTF metadata" command configuration is created, and
if `-o lttng-live` exists with a URL missing a session name, a new
"print LTTng-live sessions" command configuration is created.

New `convert` options are:

--color=(always | auto | never)
    Adds the `color` initialization parameter set to the corresponding
    value to the implicit text.text sink component.

--no-debug-info
    Do not add an implicit lttng-utils.debug-info filter component to
    the filter chain. The lttng-utils.debug-info filter always exists
    otherwise.

--run-args
    Instead of invoking the `run` command, prints to the standard output
    the equivalent `run` command arguments, formatted for a shell. This
    means you can copy the whole output and use it as is to execute
    `babeltrace run` without escaping, so that the two following
    commands are equivalent:

        babeltrace convert [...]
        babeltrace run $(babeltrace convert --run-args [...])

    You can also use this trick to augment the conversion graph with the
    `run` command, for example:

        babeltrace run --base-params common-to-each-convert-comp=23
                       $(babeltrace convert --run-args /path/to/trace
                         --source=src:my.source [...])
                       --reset-base-params
                       --sink=special-sink:my.sink
                       --connect=src.some-port:special-sink

--run-args-0
    Like --run-args, but does not escape the individual arguments for a
    shell, and uses the null character as the argument delimiter. This
    is useful to get the list of equivalent raw arguments outside a
    shell (in a user program), or to use `xargs -0`.

--url=URL
    Set the `url` initialization parameter of the current user component
    to URL.

Lost `convert` options are:

* --base-params
* --connect
* --reset-base-params

Note that --clock-force-correlate sets the boolean `force-correlate`
initialization parameter of the implicit utils.muxer filter to true.

The necessary conditions to instantiate implicit components are now:

* Implicit ctf.fs source: any of:
  * Leftover argument and no --input-format
  * Leftover argument and --input-format=ctf
  * Leftover argument and --clock-offset
  * Leftover argument and --clock-offset-ns
  * Leftover argument and --stream-intersection

* Implicit ctf.lttng-live source: any of:
  * Leftover argument and --input-format=lttng-live

* Implicit utils.muxer filter: always exists

* Implicit utils.trimmer filter: any of:
  * --begin
  * --end
  * --timerange

* Implicit lttng-utils.debug-info filter:
  * No --no-debug-info

* Implicit utils.dummy sink:
  * --output-format=dummy

* Implicit text.text sink: any of:
  * No --output-format and no --sink
  * --output-format=text
  * --clock-cycles
  * --clock-date
  * --clock-gmt
  * --clock-seconds
  * --color
  * --fields
  * --names
  * --no-delta
  * --output

The default names of the implicit components, given by the `convert`
command, to be used by the `run` command, are:

* Implicit ctf.fs source: `ctf`
* Implicit ctf.lttng-live source: `lttng-live`
* Implicit utils.muxer filter: always exists `mux`
* Implicit utils.trimmer filter: `trim`
* Implicit lttng-utils.debug-info filter: `debug-info`
* Implicit utils.dummy sink: `dummy`
* Implicit text.text sink: `text`

If any name is already taken by an explicit user component (--source,
--filter, and --sink), the rule is to try `NAME-0`, then `NAME-1`, then
`NAME-2`, etc. The same rule applies to unnamed user components.
Implicit components are always automatically named after automatically
naming the unnamed user components.

This patch also adds the following:

* Connection cycle detection in babeltrace-cfg-connect.c.
* bt_common_string_until() which returns a substring from a given point
  to one of a set of terminating characters, possibly with escapable
  characters.
* bt_common_shell_quote() which quotes a string (if necessary) for a
  shell.
* bt_common_string_is_printable() which checks if a string contains
  only printable characters, including whitespaces.
* bt_common_parse_lttng_live_url() to parse a LTTng-live URL. This is
  needed in both the LTTng-live plugin itself and babeltrace-cfg.c to
  know if the command is a `run` command or a "print LTTng-live
  sessions" command.
* The --name, --source, --filter, --sink, and --connect arguments are
  checked with bt_common_string_is_printable().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
common/common.c
converter/babeltrace-cfg-connect.c
converter/babeltrace-cfg.c
converter/babeltrace-cfg.h
converter/babeltrace.c
include/babeltrace/common-internal.h
This page took 0.027254 seconds and 4 git commands to generate.