v1.0 on master missing essential API from v0.1

[IanButterworth]

The v1.0 rewrite on master (unreleased currently) removed several essential API functions that downstream packages (like BinaryBuilderBase) depend on:

Missing from v1.0:

• OutputCollector(cmd; verbose, tee_stream, tail_error) constructor - the main way to use the package
• wait(::OutputCollector) returning success status (Bool)
• merge(::OutputCollector) - merge stdout/stderr by timestamp
• collect_stdout(::OutputCollector) / collect_stderr(::OutputCollector)
• tail(::OutputCollector)
• tee(::OutputCollector)

v1.0 provides instead:

• collect_output(cmd, outputs) - returns (pipeline, collector) tuple
• wait(::OutputCollector) returns nothing

The v1.0 API requires significantly more boilerplate and doesn't store output for later retrieval.

Before releasing v1.0 to General, we should either:

1. Restore the v0.1 API (the release-0.1 branch has thread-safety fixes that could be forward-ported), or
2. Document the breaking changes and provide a migration guide

cc @staticfloat - Not sure if there's a direction you intended BBB to take with this V1 rewrite?

[staticfloat]

Hey!

So I rewrote OutputCollectors to be significantly simpler (and in my opinion, easier to understand) as part of my BB2 efforts. I'm certainly open to making the changes on v1.0 easier to deal with for BBB, I've so far been optimizing for what BB2 needs, and I can see why you say it requires more boilerplate, as the caller is expected to hook up the pipes to the Cmd object. This means that what BBB currently does:

oc = OutputCollector(setenv(sandbox_cmd, ur.env); verbose=verbose, tee_stream=tee_stream)
did_succeed = wait(oc)
print(logger, merge(oc))

Instead becomes something like:

pipes = Dict("stdout" => PipeEndpoint(), "stderr" => PipeEndpoint())
styles = Dict("stderr" => :red)
outputs = IO[log_io, stdout]
collector = OutputCollector(
    pipes,
    outputs,
    styles,
)
run(pipeline(cmd, stdout=pipes["stdout"], stderr=pipes["stderr"]))

This allows for much more flexible pipe/output routing (e.g. you can now have multiple outputs, you can define colors for each pipe passed to a process, not just stdout and stderr, etc...). Merging is done automatically, (no need to call merge) and return code status is given by the actual run() command, rather than being hidden by the OutputCollector object, and needing to call wait() on that.

We already have an opinionated helper function that is meant to make this easier, the collect_output() function, which you use like:

cmd, oc = collect_output(cmd, [log_io, stdout])
run(cmd)
wait(oc)

Perhaps that's enough for BBB to use?