Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.
src/report.x
Command progress and completion receipts.
Functions
| Function | Summary |
|---|---|
report_configure | Resets process reporting for one command. |
report_duration | Formats microseconds as integer us, rounded whole ms, or seconds with two decimal places. |
report_generated | Writes the muted receipt for n generated C files and as many headers, bytes in all, when receipts are enabled. |
report_line | Writes one newline-terminated receipt to stderr when receipts are enabled. |
report_now_us | Returns monotonic time in microseconds, or zero when the clock read fails. |
report_phase | Writes a muted phase receipt when receipts are enabled. |
report_progress | Updates the terminal’s transient progress line when transient mode is active. |
report_receipts | Returns whether stable completion receipts are currently enabled. |
report_size | Formats bytes as B, KiB, or MiB using binary unit boundaries. |
report_suspend | Clears the active transient line from stderr, if this process drew one. |
Path.regular_bytes | Returns the size of a regular file. |
Functions
report_configure
void report_configure( int quiet, int plain, Symbol color_mode, int verbose, int dry_run, int inspecting)
Resets process reporting for one command.
Quiet, verbose, dry-run, and inspection modes disable receipts. Transient
progress additionally requires terminal stderr and non-plain output.
Plain output disables color; automatic color respects terminal capability
and NO_COLOR.
Source: src/report.x:48
report_duration
String report_duration(unsigned long microseconds)
Formats microseconds as integer us, rounded whole ms, or seconds with
two decimal places.
Source: src/report.x:258
report_generated
void report_generated(int n, unsigned long long bytes)
Writes the muted receipt for n generated C files and as many headers,
bytes in all, when receipts are enabled.
Source: src/report.x:193
report_line
void report_line(Symbol tone, String line)
Writes one newline-terminated receipt to stderr when receipts are enabled.
In transient mode the receipt first clears the terminal line, which
another process may be drawing, and line must be non-NULL.
Source: src/report.x:165
report_now_us
unsigned long report_now_us(void)
Returns monotonic time in microseconds, or zero when the clock read fails. The value measures elapsed time; it is not a wall-clock timestamp.
Source: src/report.x:239
report_phase
void report_phase( Symbol phase, int count, String noun, int cached, unsigned long microseconds)
Writes a muted phase receipt when receipts are enabled. A fully cached nonempty phase is marked up to date; a partial cache reports its cached count, and every receipt includes the elapsed time.
Source: src/report.x:176
report_progress
void report_progress(Symbol phase, int done, int total, String detail)
Updates the terminal’s transient progress line when transient mode is
active. Updates start after 125 ms and incomplete work is limited to one
update per 50 ms. detail may be NULL; output is clipped to the configured
terminal width and has no newline.
Source: src/report.x:91
report_receipts
int report_receipts(void)
Returns whether stable completion receipts are currently enabled.
Source: src/report.x:80
report_size
String report_size(unsigned long long bytes)
Formats bytes as B, KiB, or MiB using binary unit boundaries.
Byte counts are exact; larger units use one decimal place.
Source: src/report.x:267
report_suspend
void report_suspend(void)
Clears the active transient line from stderr, if this process drew one. Forked workers inherit the state but leave the line to their parent.
Source: src/report.x:153
Path
Path.regular_bytes
unsigned long long Path.regular_bytes(String path)
Returns the size of a regular file.
NULL, a failed stat, or a non-regular path returns zero.
Source: src/report.x:249
Design notes
The reporter writes only to stderr. Its transient mode uses one carriage- return line and never takes terminal input or changes terminal modes. Processes sharing a terminal, such as parallel Make recipes, take turns owning that line through a lock on the terminal device.