doc: explain progress status line

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

doc/reference/config/display.rst

@@ -19,3 +19,40 @@ where ``<setting>`` 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``.

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