Stdlib variants: better names, structure, and an alerting thread/event replacement

index.mld

@@ -8,7 +8,12 @@ This framework consists of a number of libraries and executables for testing unt
 
 The following public components are included in the package:
 
-{!modules: Ast_check Stdlib_variants Test_lib Test_runner}
+{!modules: Ast_check Test_lib Test_runner}
+
+{{!page-variants_and_overrides} [Stdlib] variants and overrides}:
+{!modules: Stdlib_alerts Stdlib_components Overrides}
+
+{1 Internal Components}
 
 The following components are intended for use within framework code only:
 

src/stdlib-variants/dune

@@ -1,5 +1 @@
-(library
- (name stdlib_variants)
- (public_name less-power.stdlib-variants)
-
- (libraries common stdlib_components stdlib_alerts))
+(documentation)

src/stdlib-variants/signature-builder/dune

@@ -91,3 +91,13 @@
     %{lib:stdlib:uchar.mli}
     %{lib:stdlib:unit.mli}
     %{lib:stdlib:weak.mli}))))
+
+(rule
+ (target threads_signature_info.ml)
+ (action
+  (with-stdout-to
+   %{target}
+   (run
+    lp-make-interface-description
+    %{lib:stdlib:threads/event.mli}
+    %{lib:stdlib:threads/thread.mli}))))

src/stdlib-variants/signature-builder/signature_builder.ml

@@ -41,10 +41,12 @@ let load_signature_info (raw_info : raw_signature_info) =
     (fun n (path, raw_sig) -> info_add_signature path (load_raw_signature raw_sig) n)
     (Node (None, [])) raw_info
 
-(** {1 Signature of {!Stdlib}} *)
+(** {1 Signature of {!Stdlib} and {!Thread}/{!Event}} *)
 
 let stdlib_signature_info = Stdlib_signature_info.signature_info |> load_signature_info
 
+let threads_signature_info = Threads_signature_info.signature_info |> load_signature_info
+
 (** {1 PPX rewriter} *)
 
 [@@@warning "-4"]
@@ -298,9 +300,15 @@ and eval_include_spec sig_infos = function
       eval_include_specs sig_infos spec_items
       |> List.map (modify_attributes (fun attr -> attr @ attributes))
 
+let default_sig_infos = [
+  ("stdlib", stdlib_signature_info);
+  ("threads", threads_signature_info);
+]
+
 (** PPX intended for use an a Ppxlib extender. The default [sig_infos] argument
-    contains descriptions for the standard library under ["stdlib"]. *)
-let ppx_include ?(sig_infos = ["stdlib", stdlib_signature_info]) ~ctxt exp =
+    contains descriptions for the standard library under ["stdlib"]
+    and for threads/events under ["threads"]. *)
+let ppx_include ?(sig_infos = default_sig_infos) ~ctxt exp =
   let loc = Expansion_context.Extension.extension_point_loc ctxt in
   let module B = Ast_builder.Make (struct let loc = loc end) in
   let sig_items = Parse.include_specs exp |> eval_include_specs sig_infos in

src/stdlib-variants/std-overrides/dune

@@ -0,0 +1,4 @@
+(library
+ (name std_overrides)
+ (public_name less-power.std-overrides)
+ (libraries stdlib_alerts stdlib_components))

src/stdlib-variants/std-overrides/std_overrides.ml

@@ -0,0 +1,41 @@
+(** Ready-to-use modules for replacing the default pervasives, using [-open]. *)
+
+module Hide_stdlib_variants = struct
+  (** Prevent access to the full variant library. Intended to be opened at the top level
+      to hide the [Stdlib_variants] module, and a couple others.
+
+      This is included in the other overrides modules, so you usually don't need
+      to pass it to the [-open] flag yourself. However, you should use it
+      if you define your own override module based on less-power stdlib variants. *)
+
+  (** {i These modules are intentionally empty.} *)
+
+  module Stdlib_variants = struct end
+
+  (* Shouldn't be necessary with (implicit_transitive_deps false), but to be safe... *)
+  module Stdlib_components = struct end
+  module Stdlib_alerts = struct end
+  module Threads_alerts = struct end
+
+end
+
+
+(** Puts the safe parts of [Stdlib] into scope,
+    from {!Stdlib_components.Stdlib_safe} *)
+module Stdlib_safe = struct
+
+  module Stdlib = Stdlib_components.Stdlib_safe
+  include Stdlib_components.Stdlib_safe
+
+  include Hide_stdlib_variants
+end
+
+(** Puts an alerting [Stdlib] into scope,
+    from {!Stdlib_alerts.Stdlib_alerting}. *)
+module Stdlib_alerting = struct
+
+  module Stdlib = Stdlib_alerts.Stdlib_alerting
+  include Stdlib_alerts.Stdlib_alerting
+
+  include Hide_stdlib_variants
+end

src/stdlib-variants/stdlib-alerts/dune

@@ -1,5 +1,13 @@
 (library
  (name stdlib_alerts)
  (public_name less-power.stdlib-alerts)
+ (modules stdlib_alerts)
  (preprocess (pps signature_builder_ppx))
  (libraries signature_builder))
+
+(library
+ (name threads_alerts)
+ (public_name less-power.threads-alerts)
+ (modules threads_alerts)
+ (preprocess (pps signature_builder_ppx))
+ (libraries signature_builder threads unix))