20.2. Output Modes

Each line of abuild's output can come from one of two sources: either abuild can generate the output itself, or the output can come from one of the backends invoked on behalf of the individual job. The backend output would include output from programs like make or ant or from anything they may invoke, such as compilers. Abuild can either capture and process output from its backends, or it can just let the backends use the same standard input, output, and error as abuild itself. We refer to what abuild does with its output as its output mode.

Abuild has three output modes: raw mode, interleaved mode, and buffered mode. In interleaved and buffered modes, each job is run with standard input connected to the null device (/dev/null in UNIX environments and NUL in Windows environments) and with standard output and standard error redirected to two separate pipes. Abuild reads from each job's output and error pipes and process the results with its own logging facility.

In raw mode, abuild invokes backend processes without capturing their output. The backend processes just write to the same standard output and standard error as abuild itself uses. Additionally, each backend has access to abuild's standard input, which makes it possible for builds to prompt the user for input. For single-threaded builds, abuild's default behavior is to run in the raw mode. This was the only output mode available in versions of abuild prior to 1.1.3. To explicitly tell abuild to use raw output mode, specify the --raw-output flag when invoking abuild.

In interleaved mode, every job is assigned a specific job prefix, which is a fixed-length (possibly zero-filled) number enclosed in square brackets. Every line of output generated by abuild itself, as well as every complete line generated by the backend, is prefixed with the job prefix and then written to abuild's standard output or standard error as appropriate. Messages generated by abuild are written immediately, and lines generated by the jobs' backends are written as soon as they are received through the pipes. By using the job prefix, it is possible to unambiguously associate each line of abuild's output with the job (build item/platform) that generated it while still having each line of output written as soon as it is generated.

For multithreaded builds, abuild runs in interleaved mode by default. Interleaved mode may be specifically requested by passing the --interleaved-output flag to abuild. If --interleaved-output is specified for a single-threaded build, abuild still runs the backend through pipes and disconnected from standard input, but it does not prepend each line with a job prefix.

In buffered mode, rather than prefixing lines with a job prefix and outputting them as soon as they are available, abuild saves up (buffers) all the output from a particular job and outputs it all at once when the job completes. This ensures that, even for a multithreaded build, there is no interleaving of output from the builds of different build items. To enable buffered output, invoke abuild with the --buffered-output flag.