Be able to allocate a formatter for stdout/stderr and use it instead of

using OCaml's formatter - fix some data-race when some parallel tasks
use the same formatter.

This commit tries to solve an issue about OCaml 5 and parallelism.
Alcotest uses OCaml's formatter which can be used by some libraries such
as Logs. In this situation and if Logs is used into a parallel task, a
data-race exists about the internal queue used by formatters.

This commit allows the user to allocate its own formatter for
stdout/stderr and give them to Alcotest.

src/alcotest-engine/alcotest_engine.ml

@@ -10,3 +10,5 @@ module Platform = Platform
 module Private = struct
   module Pp = Pp
 end
+
+module Global = Global

src/alcotest-engine/alcotest_engine.mli

@@ -54,3 +54,5 @@ module Platform = Platform
 module Private : sig
   module Pp = Pp
 end
+
+module Global = Global

src/alcotest-engine/cli.ml

@@ -86,7 +86,7 @@ module Make (P : Platform.MAKER) (M : Monad.S) :
       alcotest_columns;
     ]
 
-  let set_color =
+  let set_color stdout stderr =
     let env = Cmd.Env.info "ALCOTEST_COLOR" in
     let+ color_flag =
       let enum = [ ("auto", `Auto); ("always", `Ansi_tty); ("never", `None) ] in
@@ -112,49 +112,57 @@ module Make (P : Platform.MAKER) (M : Monad.S) :
             Some `Ansi_tty
           with Not_found -> None)
     in
-    P.setup_std_outputs ?style_renderer ()
+    P.setup_std_outputs ?style_renderer stdout stderr
 
   let default_cmd config args library_name tests =
     let and_exit = Config.User.and_exit config
     and record_backtrace = Config.User.record_backtrace config
-    and ci = Config.User.ci config in
+    and ci = Config.User.ci config
+    and stdout = Config.User.stdout config
+    and stderr = Config.User.stderr config in
     let exec_name = Filename.basename Sys.argv.(0) in
     let doc = "Run all the tests." in
     let term =
-      let+ () = set_color
-      and+ cli_config = Config.User.term ~and_exit ~record_backtrace ~ci
+      let+ () = set_color stdout stderr
+      and+ cli_config =
+        Config.User.term ~stdout ~stderr ~and_exit ~record_backtrace ~ci
       and+ args = args in
       let config = Config.User.(cli_config || config) in
       run_with_args' config library_name args tests
     in
     (term, Cmd.info exec_name ~doc ~envs)
 
   let test_cmd config args library_name tests =
-    let ci = Config.User.ci config in
+    let ci = Config.User.ci config
+    and stdout = Config.User.stdout config
+    and stderr = Config.User.stderr config in
     let doc = "Run a subset of the tests." in
     let term =
-      let+ () = set_color
+      let+ () = set_color stdout stderr
       and+ cli_config =
-        Config.User.term ~and_exit:true ~record_backtrace:true ~ci
+        Config.User.term ~stdout ~stderr ~and_exit:true ~record_backtrace:true
+          ~ci
       and+ args = args in
       let config = Config.User.(cli_config || config) in
       run_with_args' config library_name args tests
     in
     (term, Cmd.info "test" ~doc ~envs)
 
-  let list_cmd tests =
+  let list_cmd ~stdout ~stderr tests =
     let doc = "List all available tests." in
-    ( (let+ () = set_color in
+    ( (let+ () = set_color stdout stderr in
        list_tests tests),
       Cmd.info "list" ~doc )
 
   let run_with_args' (type a) ~argv config name (args : a Term.t)
       (tl : a test list) =
     let ( >>= ) = M.bind in
+    let stdout = Config.User.stdout config
+    and stderr = Config.User.stderr config in
     let choices =
       List.map
         (fun (term, info) -> Cmd.v info term)
-        [ list_cmd tl; test_cmd config args name tl ]
+        [ list_cmd ~stdout ~stderr tl; test_cmd config args name tl ]
     in
     let and_exit = Config.User.and_exit config in
     let exit_or_return exit_code =
@@ -172,11 +180,12 @@ module Make (P : Platform.MAKER) (M : Monad.S) :
     | Error (`Parse | `Term) -> exit_or_return Cmd.Exit.cli_error
     | Error `Exn -> exit Cmd.Exit.internal_error
 
-  let run_with_args ?and_exit ?verbose ?compact ?tail_errors ?quick_only
-      ?show_errors ?json ?filter ?log_dir ?bail ?record_backtrace ?ci ?argv =
-    Config.User.kcreate (run_with_args' ~argv) ?and_exit ?verbose ?compact
-      ?tail_errors ?quick_only ?show_errors ?json ?filter ?log_dir ?bail
-      ?record_backtrace ?ci
+  let run_with_args ?stdout ?stderr ?and_exit ?verbose ?compact ?tail_errors
+      ?quick_only ?show_errors ?json ?filter ?log_dir ?bail ?record_backtrace
+      ?ci ?argv =
+    Config.User.kcreate (run_with_args' ~argv) ?stdout ?stderr ?and_exit
+      ?verbose ?compact ?tail_errors ?quick_only ?show_errors ?json ?filter
+      ?log_dir ?bail ?record_backtrace ?ci
 
   let run =
     Config.User.kcreate (fun config ?argv name tl ->

src/alcotest-engine/config.ml

@@ -253,10 +253,22 @@ module User = struct
     bail : Bail.t option;
     record_backtrace : Record_backtrace.t option;
     ci : CI.t option;
+    stdout : Global.stdout;
+    stderr : Global.stderr;
   }
 
   let ( || ) a b =
     let merge_on f = Option.(f a || f b) in
+    let stdout =
+      merge_on @@ fun t ->
+      if t.stdout == Global.ocaml_stdout then None else Some t.stdout
+    in
+    let stderr =
+      merge_on @@ fun t ->
+      if t.stderr == Global.ocaml_stderr then None else Some t.stderr
+    in
+    let stdout = Option.value ~default:Global.ocaml_stdout stdout in
+    let stderr = Option.value ~default:Global.ocaml_stderr stderr in
     {
       and_exit = merge_on (fun t -> t.and_exit);
       verbose = merge_on (fun t -> t.verbose);
@@ -270,9 +282,11 @@ module User = struct
       bail = merge_on (fun t -> t.bail);
       record_backtrace = merge_on (fun t -> t.record_backtrace);
       ci = merge_on (fun t -> t.ci);
+      stdout;
+      stderr;
     }
 
-  let term ~and_exit ~record_backtrace ~ci =
+  let term ~stdout ~stderr ~and_exit ~record_backtrace ~ci =
     let+ verbose = Verbose.term
     and+ compact = Compact.term
     and+ tail_errors = Tail_errors.term
@@ -295,12 +309,15 @@ module User = struct
       bail;
       record_backtrace = Some record_backtrace;
       ci = Some ci;
+      stdout;
+      stderr;
     }
 
   (* Lift a config-sensitive function to one that consumes optional arguments that
      override config defaults. *)
   let kcreate : 'a. (t -> 'a) -> 'a with_options =
-   fun f ?and_exit ?verbose ?compact ?tail_errors ?quick_only ?show_errors ?json
+   fun f ?(stdout = Global.ocaml_stdout) ?(stderr = Global.ocaml_stderr)
+       ?and_exit ?verbose ?compact ?tail_errors ?quick_only ?show_errors ?json
        ?filter ?log_dir ?bail ?record_backtrace ?ci ->
     f
       {
@@ -316,6 +333,8 @@ module User = struct
         bail;
         record_backtrace;
         ci;
+        stdout;
+        stderr;
       }
 
   let create : (unit -> t) with_options = kcreate (fun t () -> t)
@@ -325,6 +344,8 @@ module User = struct
     Option.value ~default:Record_backtrace.default t.record_backtrace
 
   let ci t = Option.value ~default:CI.default t.ci
+  let stdout t = t.stdout
+  let stderr t = t.stderr
 end
 
 let apply_defaults ~default_log_dir : User.t -> t =
@@ -341,6 +362,8 @@ let apply_defaults ~default_log_dir : User.t -> t =
        bail;
        record_backtrace;
        ci;
+       stdout;
+       stderr;
      } ->
   let open Key in
   object (self)
@@ -365,4 +388,6 @@ let apply_defaults ~default_log_dir : User.t -> t =
       Option.value ~default:Record_backtrace.default record_backtrace
 
     method ci = Option.value ~default:CI.default ci
+    method stdout = stdout
+    method stderr = stderr
   end

src/alcotest-engine/config_intf.ml

@@ -1,12 +1,16 @@
 module Types = struct
+  type stdout = Global.stdout
+  type stderr = Global.stderr
   type bound = [ `Unlimited | `Limit of int ]
   type filter = name:string -> index:int -> [ `Run | `Skip ]
 
   type ci = [ `Github_actions | `OCamlci | `Unknown | `Disabled ]
   (** All supported Continuous Integration (CI) systems. *)
 
   type t =
-    < and_exit : bool
+    < stdout : stdout
+    ; stderr : stderr
+    ; and_exit : bool
     ; verbose : bool
     ; compact : bool
     ; tail_errors : bound
@@ -20,6 +24,8 @@ module Types = struct
     ; ci : ci >
 
   type 'a with_options =
+    ?stdout:stdout ->
+    ?stderr:stderr ->
     ?and_exit:bool ->
     ?verbose:bool ->
     ?compact:bool ->
@@ -51,7 +57,12 @@ module type Config = sig
         rather than returning directly. *)
 
     val term :
-      and_exit:bool -> record_backtrace:bool -> ci:ci -> t Cmdliner.Term.t
+      stdout:Global.stdout ->
+      stderr:Global.stderr ->
+      and_exit:bool ->
+      record_backtrace:bool ->
+      ci:ci ->
+      t Cmdliner.Term.t
     (** [term] provides a command-line interface for building configs. *)
 
     val ( || ) : t -> t -> t
@@ -63,6 +74,8 @@ module type Config = sig
     val and_exit : t -> bool
     val record_backtrace : t -> bool
     val ci : t -> ci
+    val stdout : t -> Global.stdout
+    val stderr : t -> Global.stderr
   end
 
   val apply_defaults : default_log_dir:string -> User.t -> t