unikernel/duniverse/cmdliner-stdlib/.gitignore

@@ -0,0 +1,6 @@
+_build
+*~
+\.\#*
+\#*#
+_opam
+.DS_Store

unikernel/duniverse/cmdliner-stdlib/.ocamlformat

@@ -0,0 +1,4 @@
+version = 0.25.1
+profile = conventional
+break-infix = fit-or-vertical
+parse-docstrings = true

unikernel/duniverse/cmdliner-stdlib/CHANGES.md

@@ -0,0 +1,8 @@
+## 1.0.1 (2024-10-11)
+
+- use "OCAML RUNTIME OPTIONS" as section header (not "OCAML RUNTIME PARAMETERS")
+  #2 @hannesm
+
+## 1.0.0 (2023-07-04)
+
+- Initial release

unikernel/duniverse/cmdliner-stdlib/LICENSE.md

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (X) 2011-2023, the [MirageOS contributors](https://mirage.io/community/#team)
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

unikernel/duniverse/cmdliner-stdlib/README.md

@@ -0,0 +1,63 @@
+# cmdliner-stdlib
+
+The `cmdliner-stdlib` package is a collection of cmdliner terms that
+help control OCaml runtime parameters, usually configured through the
+`OCAMLRUNPARAM` environment variable. The package provides command-line
+options for controlling features like backtrace, hash table
+randomization, and garbage collector tuning.
+
+## Installation
+
+You can install the package using `opam`:
+
+```bash
+opam install cmdliner-stdlib
+```
+
+## Usage
+
+You can use these command-line arguments to:
+- enable/disable backtraces;
+- enable/disable table randomization, for better security and prevent
+  collision attacks; and
+- control the OCaml garbage collector as described in detail in the
+  [GC
+  control](http://caml.inria.fr/pub/docs/manual-ocaml/libref/Gc.html#TYPEcontrol)
+  documentation.
+
+```ocaml
+open Cmdliner
+
+let cmd = Cmd.v (Cmd.info "hello") (Cmdliner_stdlib.setup ())
+let () = exit (Cmd.eval cmd)
+```
+
+You can then use command-line options to change parameters of the
+OCaml runtime. For instance, to enable backtraces and change the GC
+allocation policy to "first fit":
+
+```sh
+$ dune exec -- ./hello.exe --allocation-policy=first-fit --backtrace=true
+```
+
+You can disable some of these arguments. For instance, to disable GC control use:
+
+```ocaml
+   Cmdliner_stdlib.setup ~gc_control:None ()
+```
+
+Or to change the default allocation policy to be `first-fit`:
+
+
+```ocaml
+  let default = Gc.get () in
+  let gc_control = Some { default with allocation_policy = 1 } in
+  Cmdliner_stdlib.setup ~gc_control ()
+```
+
+## Contributions
+
+We welcome contributions, bug reports, and feature requests. Please
+visit our [GitHub
+repository](https://github.com/mirage/cmdliner-stdlib) for more
+information.

unikernel/duniverse/cmdliner-stdlib/cmdliner-stdlib.opam

@@ -0,0 +1,31 @@
+version: "1.0.1"
+opam-version: "2.0"
+maintainer:   ["thomas@gazagnaire.org"]
+authors:      ["Thomas Gazagnaire"  "Hannes Mehnert"]
+homepage:     "https://github.com/mirage/cmdliner-stdlib"
+bug-reports:  "https://github.com/mirage/cmdliner-stdlib/issues/"
+dev-repo:     "git+https://github.com/mirage/cmdliner-stdlib.git"
+license:      "ISC"
+tags:         ["org:mirage"]
+doc:          "https://mirage.github.io/cmdliner-stdlib/"
+
+build: [
+  ["dune" "subst"] {dev}
+  ["dune" "build" "-p" name "-j" jobs]
+  ["dune" "runtest" "-p" name "-j" jobs] {with-test}
+]
+
+depends: [
+  "ocaml" {>= "4.08.0"}
+  "dune" {>= "2.9.0"}
+  "cmdliner" {>= "1.0.0"}
+]
+synopsis: "A collection of cmdliner terms to control OCaml runtime parameters"
+description: """
+Cmdliner-stdlib is a package that provides a collection of cmdliner terms
+to control the OCaml runtime parameters. This is typically done with environment
+variables, but there are situations where such an environment is not accessible,
+like in MirageOS. This package enables the configuration and manipulation of
+runtime parameters in these contexts, improving the flexibility of applications
+built on these platforms.
+"""

unikernel/duniverse/cmdliner-stdlib/dune-project

@@ -0,0 +1,3 @@
+(lang dune 2.9)
+(name cmdliner-stdlib)
+(version 1.0.1)

unikernel/duniverse/cmdliner-stdlib/lib/cmdliner_stdlib.ml

@@ -0,0 +1,210 @@
+(*
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *)
+
+open Cmdliner
+
+let ocaml_section = "OCAML RUNTIME OPTIONS"
+
+let backtrace ~default =
+  let doc =
+    "Trigger the printing of a stack backtrace when an uncaught exception \
+     aborts the unikernel."
+  in
+  let doc = Arg.info ~docs:ocaml_section ~docv:"BOOL" ~doc [ "backtrace" ] in
+  Arg.(value & opt bool default doc)
+
+let randomize_hashtables ~default =
+  let doc = "Turn on randomization of all hash tables by default." in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"BOOL" ~doc [ "randomize-hashtables" ]
+  in
+  Arg.(value & opt bool default doc)
+
+let policy_of_int = function
+  | 0 -> `Next_fit
+  | 1 -> `First_fit
+  | 2 -> `Best_fit
+  | _ -> assert false
+
+let int_of_policy = function `Next_fit -> 0 | `First_fit -> 1 | `Best_fit -> 2
+
+let allocation_policy d =
+  let policy =
+    Arg.enum
+      [
+        ("next-fit", `Next_fit);
+        ("first-fit", `First_fit);
+        ("best-fit", `Best_fit);
+      ]
+  in
+  let doc =
+    "The policy used for allocating in the OCaml heap. Possible values are: \
+     $(i,next-fit), $(i,first-fit), $(i,best-fit). Best-fit is only supported \
+     since OCaml 4.10."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"ALLOCATION" ~doc [ "allocation-policy" ]
+  in
+  Arg.(value & opt policy (policy_of_int d.Gc.allocation_policy) doc)
+
+let minor_heap_size d =
+  let doc = "The size of the minor heap (in words)." in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"WORDS" ~doc [ "minor-heap-size" ]
+  in
+  Arg.(value & opt int d.Gc.minor_heap_size doc)
+
+let major_heap_increment d =
+  let doc =
+    "The size increment for the major heap (in words). If less than or equal \
+     1000, it is a percentage of the current heap size. If more than 1000, it \
+     is a fixed number of words."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"PERCENT/WORDS" ~doc
+      [ "major-heap-increment" ]
+  in
+  Arg.(value & opt int d.Gc.major_heap_increment doc)
+
+let space_overhead d =
+  let doc =
+    "The percentage of live data of wasted memory, due to GC does not \
+     immediately collect unreachable blocks. The major GC speed is computed \
+     from this parameter, it will work more if smaller."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"PERCENT" ~doc [ "space-overhead" ]
+  in
+  Arg.(value & opt int d.Gc.space_overhead doc)
+
+let max_space_overhead d =
+  let doc =
+    "Heap compaction is triggered when the estimated amount of wasted memory \
+     exceeds this (percentage of live data). If above 1000000, compaction is \
+     never triggered."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"PERCENT" ~doc [ "max-space-overhead" ]
+  in
+  Arg.(value & opt int d.Gc.max_overhead doc)
+
+let gc_verbosity d =
+  let doc =
+    "GC messages on standard error output. Sum of flags. Check GC module \
+     documentation for details."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"VERBOSITY" ~doc [ "gc-verbosity" ]
+  in
+  Arg.(value & opt int d.Gc.verbose doc)
+
+let gc_window_size d =
+  let doc =
+    "The size of the window used by the major GC for smoothing out variations \
+     in its workload. Between 1 and 50."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"INT" ~doc [ "gc-window-size" ]
+  in
+  Arg.(value & opt int d.Gc.window_size doc)
+
+let custom_major_ratio d =
+  let doc =
+    "Target ratio of floating garbage to major heap size for out-of-heap \
+     memory held by custom values."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"RATIO" ~doc [ "custom-major-ratio" ]
+  in
+  Arg.(value & opt int d.Gc.custom_minor_ratio doc)
+
+let custom_minor_ratio d =
+  let doc =
+    "Bound on floating garbage for out-of-heap memory held by custom values in \
+     the minor heap."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"RATIO" ~doc [ "custom-minor-ratio" ]
+  in
+  Arg.(value & opt int d.Gc.custom_minor_ratio doc)
+
+let custom_minor_max_size d =
+  let doc =
+    "Maximum amount of out-of-heap memory for each custom value allocated in \
+     the minor heap."
+  in
+  let doc =
+    Arg.info ~docs:ocaml_section ~docv:"BYTES" ~doc [ "custom-minor-max-size" ]
+  in
+  Arg.(value & opt int d.Gc.custom_minor_max_size doc)
+
+let stack_limit d =
+  let doc = "The maximum size of the fiber stacks (in words)." in
+  let doc = Arg.info ~docs:ocaml_section ~docv:"WORDS" ~doc [ "stack-limit" ] in
+  Arg.(value & opt int d.Gc.stack_limit doc)
+
+let gc_control ~default =
+  let f minor_heap_size major_heap_increment space_overhead verbose max_overhead
+      stack_limit allocation_policy window_size custom_major_ratio
+      custom_minor_ratio custom_minor_max_size =
+    let allocation_policy = int_of_policy allocation_policy in
+    {
+      Gc.minor_heap_size;
+      major_heap_increment;
+      space_overhead;
+      verbose;
+      max_overhead;
+      stack_limit;
+      allocation_policy;
+      window_size;
+      custom_major_ratio;
+      custom_minor_ratio;
+      custom_minor_max_size;
+    }
+  in
+  Term.(
+    const f
+    $ minor_heap_size default
+    $ major_heap_increment default
+    $ space_overhead default
+    $ gc_verbosity default
+    $ max_space_overhead default
+    $ stack_limit default
+    $ allocation_policy default
+    $ gc_window_size default
+    $ custom_major_ratio default
+    $ custom_minor_ratio default
+    $ custom_minor_max_size default)
+
+let setup ?backtrace:(b = Some false) ?randomize_hashtables:(r = Some false)
+    ?gc_control:(c = Some (Gc.get ())) () =
+  let f backtrace randomize_hashtables gc_control =
+    let () =
+      match backtrace with None -> () | Some b -> Printexc.record_backtrace b
+    in
+    let () =
+      match randomize_hashtables with
+      | None | Some false -> ()
+      | Some true -> Hashtbl.randomize ()
+    in
+    let () = match gc_control with None -> () | Some c -> Gc.set c in
+    ()
+  in
+  let some c = Term.(const Option.some $ c) in
+  let none = Term.const None in
+  let fold f d = Option.fold ~none ~some:(fun d -> some (f ~default:d)) d in
+  let b = fold backtrace b in
+  let r = fold randomize_hashtables r in
+  let c = fold gc_control c in
+  Term.(const f $ b $ r $ c)

unikernel/duniverse/cmdliner-stdlib/lib/cmdliner_stdlib.mli

@@ -0,0 +1,61 @@
+(*
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *)
+
+open Cmdliner
+
+(** {2 OCaml runtime keys}
+
+    The OCaml runtime is usually configurable via the [OCAMLRUNPARAM]
+    environment variable. We provide boot parameters covering these options. *)
+
+val backtrace : default:bool -> bool Term.t
+(** [--backtrace]: Output a backtrace if an uncaught exception terminated the
+    application. [default] is the default value if the parameter is not provided
+    on the command-line. *)
+
+val randomize_hashtables : default:bool -> bool Term.t
+(** [--randomize-hashtables]: Randomize all hash tables. [default] is the
+    default value if the parameter is not provided on the command-line. *)
+
+val gc_control : default:Gc.control -> Gc.control Term.t
+(** [gc_control] is a term that evaluates to a value of type [Gc.control].
+    [default] is the default value if the parameter is not provided on the
+    command-line..
+
+    The OCaml garbage collector can be configured, as described in detail in
+    {{:http://caml.inria.fr/pub/docs/manual-ocaml/libref/Gc.html#TYPEcontrol} GC
+      control}. *)
+
+val setup :
+  ?backtrace:bool option ->
+  ?randomize_hashtables:bool option ->
+  ?gc_control:Gc.control option ->
+  unit ->
+  unit Term.t
+(** [setup ?backtrace ?randomize_hashtables ?gc_control ()] is the term that set
+    the corresponding OCaml runtime parameters:
+
+    - if [backtrace] is set to [Some d], adding [--backtrace] on the
+      command-line will call [Printexc.record_backtrace]. [d] is the default if
+      case no parameters are provided. If not set, [backtrace] is [Some false]
+      to match the default OCaml runtime behavior.
+    - if [randomize_hashtables] is set to [Some d], adding
+      [--randomize-hashtables] to the command-line will call
+      [Hashtable.randomize ()]. [d] is the default if no paramaters are
+      provided. If not set, [randomize_hashtables] is set to [Some false] to
+      match the default OCaml runtime behavior.
+    - if [gc_control] is set to [Some d], various control parameters are added
+      to the command-line options that will cause [Gc.set] with the right
+      parameters. [d] is the default if no parameters are provided. If not set,
+      [gc_control] is [Some (Gc.get ())]. *)

unikernel/duniverse/cmdliner-stdlib/lib/dune

@@ -0,0 +1,4 @@
+(library
+ (public_name cmdliner-stdlib)
+ (name cmdliner_stdlib)
+ (libraries cmdliner))