From c70aa0f76e4a4f4d3d6cdb9346c53681299fcf64 Mon Sep 17 00:00:00 2001 From: Ali Caglayan Date: Fri, 11 Sep 2026 18:17:00 +0200 Subject: [PATCH] doc: explain progress status line Signed-off-by: Ali Caglayan --- bin/help.ml | 43 +++++++++++++++++++++++++++++++- doc/reference/config/display.rst | 37 +++++++++++++++++++++++++++ doc/rpc.rst | 13 ++++++++++ 3 files changed, 92 insertions(+), 1 deletion(-) diff --git a/bin/help.ml b/bin/help.ml index e3d4dbf44cd..2dc9e0d1b71 100644 --- a/bin/help.ml +++ b/bin/help.ml @@ -39,7 +39,7 @@ let config = (List.map ~f:(fun (x, desc) -> `I (sprintf "$(b,%s)" x, desc)) [ ( "progress" - , {|This is the default, Dune shows and update a + , {|This is the default, Dune shows and updates a status line as build goals are being completed.|} ) ; "quiet", {|Only display errors.|} @@ -54,6 +54,47 @@ let config = programs.|} ) ]) + ; `S "PROGRESS STATUS LINE" + ; `P {|In $(b,progress) mode, a running build displays a line similar to:|} + ; `Pre "Done: 75% (3/4, 1 left) (jobs: 1) | [1.2s] [0.8x] [2] | [rpc 1]" + ; `P "Its components are:" + ; `Blocks + [ `I + ( "$(b,Done)" + , {|The percentage and number of build rules completed, the total + number discovered so far, and the number remaining. The total + can increase as Dune discovers rules, and rules that are already + up to date still count as completed. A failure count is added + when a rule fails.|} + ) + ; `I ("$(b,jobs)", "The number of jobs currently running.") + ; `I + ( "$(b,[1.2s])" + , {|The elapsed time for the current build. In watch mode, it is + the duration of the most recently completed build while Dune + waits for changes.|} + ) + ; `I + ( "$(b,[0.8x])" + , {|The average process parallelism: the accumulated CPU time of + build processes divided by the elapsed build time. On Windows, + where process CPU time is unavailable, Dune uses accumulated + process wall-clock time.|} + ) + ; `I ("$(b,[2])", "The current build number in watch mode, starting at 1.") + ; `I + ( "$(b,[rpc 1])" + , {|The number of RPC clients currently connected to this Dune + process. It is shown only while at least one client is + connected.|} + ) + ] + ; `P + {|Bracketed components are displayed only when applicable. When a + command sends its request to an existing watch-mode Dune process, + its own status line displays $(b,Connected to RPC server); the + detailed build status remains in the server's output and is also + available through $(b,dune monitor).|} ; `P {|Note that when the selected display mode is $(b,progress) and the output is not a terminal then the $(b,quiet) mode is selected diff --git a/doc/reference/config/display.rst b/doc/reference/config/display.rst index f28a5cf2e2b..f8d76c61949 100644 --- a/doc/reference/config/display.rst +++ b/doc/reference/config/display.rst @@ -19,3 +19,40 @@ where ```` is one of: left and the targets of the action on the right. - ``quiet`` only display errors. + +Progress Status Line +~~~~~~~~~~~~~~~~~~~~ + +In ``progress`` mode, a running build displays a line similar to: + +.. code:: text + + Done: 75% (3/4, 1 left) (jobs: 1) | [1.2s] [0.8x] [2] | [rpc 1] + +Its components are: + +- ``Done: 75% (3/4, 1 left)`` reports the percentage and number of + build rules completed, the total number discovered so far, and the number + remaining. The total can increase as Dune discovers rules, and rules that + are already up to date still count as completed. A failure count is added + when a rule fails. + +- ``jobs: 1`` is the number of jobs currently running. + +- ``[1.2s]`` is the elapsed time for the current build. In watch mode, it is + the duration of the most recently completed build while Dune waits for + changes. + +- ``[0.8x]`` is the average process parallelism: the accumulated CPU time of + build processes divided by the elapsed build time. On Windows, where process + CPU time is unavailable, Dune uses accumulated process wall-clock time. + +- ``[2]`` is the current build number in watch mode, starting at 1. + +- ``[rpc 1]`` is the number of RPC clients currently connected to this Dune + process. It is shown only while at least one client is connected. + +Bracketed components are displayed only when applicable. When a command sends +its request to an existing watch-mode Dune process, its own status line displays +``Connected to RPC server``; the detailed build status remains in the server's +output and is also available through ``dune monitor``. diff --git a/doc/rpc.rst b/doc/rpc.rst index 2bf82e1997c..a740c2fef64 100644 --- a/doc/rpc.rst +++ b/doc/rpc.rst @@ -68,6 +68,19 @@ are two ways of doing this: Then ``dune rpc build .`` will connect to it, trigger a build, and report status. +Status Line +=========== + +With ``progress`` display enabled, the server's status line includes +``[rpc N]`` while RPC clients are connected, where ``N`` is the number of +clients. A command whose build is forwarded to the server displays +``Connected to RPC server`` in its own status line. ``dune monitor`` connects +as an RPC client and displays the server's build-rule progress, running job +count, and diagnostics. + +See :doc:`reference/config/display` for a description of all status-line +components. + .. _lwt: https://github.com/ocsigen/lwt .. _Dune_rpc: https://github.com/ocaml/dune/blob/main/otherlibs/dune-rpc/dune_rpc.mli .. _rpc_client_example: https://github.com/ocaml/dune/tree/main/otherlibs/dune-rpc-lwt/examples/rpc_client