mirage

CHANGES:

• BREAKING re-introduce ?deps argument into Mirage.main function to be
  able to track how to compile some artifacts for an unikernel without emitting
  modules/functors used by these artifacts (#1555, @dinosaure) - this was
  removed in mirage 4.5.0, and is back now
• Allow tar 3.0.0 (#1557, @hannesm)

CHANGES:

• BREAKING adapt to happy-eyeballs and dns-client devices where dependencies
  got reversed (#1543 @dinosaure @hannesm)

  Adapting unikernels requires to notice that the generic_dns_client now
  takes a happy_eyeballs, and happy_eyeballs does no longer take a dns_client:

  -let dns_client = generic_dns_client ~nameservers stackv4v6
  -let happy_eyeballs = generic_happy_eyeballs stackv4v6 dns_client
  +let happy_eyeballs = generic_happy_eyeballs stackv4v6
  +let dns_client = generic_dns_client ~nameservers stackv4v6 happy_eyeballs

• allow mirage-qubes 0.10 series (#1548 @dinosaure)

• revise "job without arguments" to take runtime arguments into consideration
  (#1544 @hannesm)

• provide Mirage.ethif (alias to Mirage.etif - which is now deprecated)
  (#1546 @reynir @hannesm)

• update tests for cmdliner 1.3.0 (#1545 @hannesm)

• allow paf 0.6.0 (#1542 @hannesm)

CHANGES:

• BREAKING: remove ~name parameter from Mirage.Runtime_args.create
  (#1541 @samoht, fixes #1532)
• BREAKING: remove ~name parameter from Mirage.runtime_arg, and use a
  string (instead of a format string) as third parameter (#1541 @samoht)
• constrain the start function to unit Lwt.t. Previously, there was no
  restrictions, and lots of time was spent in debugging when a unikernel
  resulted in unit Lwt.t Lwt.t (@Julow #1524)
• revise man page sections and ordering: ARGUMENTS, OPTIONAL, NETWORK OPTIONS,
  DISK OPTIONS, LOG AND MONITORING OPTIONS, OCAML RUNTIME OPTIONS. Previously,
  the ARGUMENTS and OPTIONS were put later, and were hard to find. These are
  the sections where unikernel-specific arguments are put by default
  (#1531 @hannesm @reynir)
• add --net=host and --net=ocaml to reduce confusion. --net=host uses the
  TCP/IP socket stack, --net=ocaml the OCaml network stack (#1525 @hannesm)
• quote Runtime_arg.call (#1522 @Julow)
• documentation fixes (inline examples @Julow #1523, @hannesm #1537 (fixes
  #1512 reported by @reynir), Runtime_args.create #1541 @samoht)
• fix the build instructions of the generated opam file: since 4.5.0
  mirage build is no longer available, use make "build" (#1527 @hannesm)
• add RELEASE.md, a guide on how to cut a mirage release (#1519 @samoht)
• allow git 3.16 (#1536 @hannesm)
• use mirage-bootvar (using dune variant) instead of parse-argv and
  mirage-bootvar-xen, mirage-bootvar-solo5, mirage-bootvar-unix
  (#1533 @hannesm)
• BUGFIX: reset the lexer location before applying functors in generated code
  (#1539 @samoht, fixes #1520 @hannesm)
• BUGFIX: fix off-by-one locations for mirage/main.ml (#1540 @samoht, fixes
  #1528 @hannesm)

CHANGES:

• This release introduces a significant change in the Mirage tool by
  splitting the definition of command-line arguments used at
  configure-time and runtime. Command-line arguments used in the
  configure script (also called 'configuration keys' and defined in
  the Key module) are essential during the setup of module
  dependencies for the unikernel, allowing for a specialized
  production of a unikernel for a given target runtime environment. On
  the other hand, command-line arguments that the unikernel can use at
  runtime (defined in the Runtime_arg module) are useful for
  customizing deployments without altering the dependencies of the
  unikernels. (#1449, #1450, #1451, #1455 @samoht, review by @hannesm)

  • API changes:

    • There is no more ~stage parameter for Key.Arg.info.
    • Key now define command-line arguments for the configuration tool.
    • There is a new module Runtime_arg to define command-line arguments
      for the unikernel.
    • As there are no more keys type 'Both, users are now expected to create
      two separated keys in that case (one for configure-time, one for runtime)
      or decide if the key is useful at runtime of configure-time.

  • Intended use of configuration keys (values of type 'a key):

    • Used to set up module dependencies of the unikernel, such as the
      target (hvt, xen, etc.) and whether to use DHCP or a fixed IP address.
    • Enable the production of specialized unikernels suitable for
      specific target runtime environments and dedicated network and
      storage stacks.
    • Similar keys will produce reproducible binaries to be uploaded to artifact
      repositories like Docker Hub or https://builds.robur.coop/.

  • Intended use of command-line runtime arguments (values of type
    a runtime_arg):

    • Allow users to customize deployments by changing device
      configuration, like IP addresses, secrets, block device names,
      etc., post downloading of binaries.
    • These keys don’t alter the dependencies of the unikernels.
    • A runtime keys is just a reference to a normal Cmdliner term.

  • key_gen.ml is not generated anymore, so users cannot refer to
    Key_gen.<key_name> directy.

    • Any runtime argument has to be declared (using runtime_arg and
      registered on the device (using ~runtime_args). The value of that
      argument will then be passed as an extra parameter of the connect
      function of that device.
    • Configuration keys are not available at runtime anymore. For
      instance, Key_gen.target has been removed.

• Code migration:

  (* in config.ml *)
  let key =
    let doc = Key.Arg.info ~doc:"A Key." ~stage:`Run [ "key" ] in
    Key.(create "key" Arg.(opt_all ~stage:`Run string doc))
  

  becomes:

  (* in unikernel.ml *)
  open Cmdliner
  
  let key =
    let doc = Arg.info ~doc:"A Key." [ "key" ] in
    Arg.(value & opt_all string [] doc)
  

  (* in unikernel.ml *)
  let start _ =
    let key = Key_gen.hello () in
    ...
  

  becomes:

  (* in config.ml *)
  let hello = runtime_arg ~pos:__POS__ "Unikernel.hello"
  let main = main ~runtime_args:[hello] ...
  

  (* in unikernel.ml *)
  let hello =
    let open Cmdliner in
    let doc = Arg.info ~doc:"How to say hello." [ "hello" ] in
    Arg.(value & opt string "Hello World!" doc)
  
  let start _ hello =
    ...
  

• bump minimal ocaml-solo5 version bound to 0.8.2 to avoid fast memory usage
  error (#1507, @palainp)
• BREAKING: the packages functoria and functoria-runtime are removed. The
  respectives libraries became mirage.functoria and mirage-runtime.functoria
  (#1509, @samoht)
• BREAKING: Mirage.keys is renamed to Mirage.runtime_args (#1506, @samoht)
• BREAKING: remove Mirage.foreign. Use Mirage.main` instead (#1505, @samoht)
• BREAKING: Mirage.main does not take a ?extra_deps parameter anymore
  (#1505, @samoht)
• BREAKING: the Mirage.connect functions passed to create devices
  (with Mirage.impl) now take values of type 'a Mirage.code instead
  of string. Value of type code are created using a new Mirage.code
  function, that takes ~pos:__POS__ as parameter. This is used to generate
  better locations in the generated code, leading to better error messages
  (#1504, @samoht)
• BUGFIX: fix mirage describe output (#1446 @samoht), add test (#1458 @samoht)
• Remove ipaddr from runtime (#1437 @samoht, #1465 @hannesm)
• BREAKING: Mirage.register no longer have ?packages and ?keys arguments
  (#1433, #1434 @hannesm)
• BREAKING: Remove deprecated bindings and types (#1461 @hannesm)
• BREAKING: Remove mirage build subcommand, use dune build in Makefile
  (#1404 @hannesm), put --profile release in Makefile instead of
  dune-workspace (#1470 @hannesm)
• Increase dune version to 2.9 in generated dune-project (#1443 @samoht)

CHANGES:

• Fix GC documentation (space overhead is 120 since best-fit is default)
  (#1491 @hannesm)
• use Option in printing of GC keys (#1491 @hannesm)
• allow to use git 3.15 (#1491 @hannesm)
• allow empty noop job (addresses an issue with #1428)
  solves an issue reported by @MisterDA in mirage/mirage-www#815
  (#1491 @hannesm)

CHANGES:

• Document exit codes in --help (#1485 @hannesm)
• Avoid dependency on environment variable (removing MIRAGE_LOGS #1484 @hannesm)
• BUGFIX: dune.config mark "dist" as data-only-dir to allow config.ml being
  compiled (#1475 @memst)
• Allow git 3.14 (#1474 @hannesm)
• Default to best-fit allocation (#1473 @hannesm)
• FEATURE: Add a key "--delay" to all unikernels (#1472 @hannesm, fixes #1468)
• Fix Unix target dune rule (add a deps) (#1469 @hannesm)
• Optionally pass tcp in direct_stackv4v6, static_ipv4v6, generic_stackv4v6
  (#1467 @hannesm)
• FEATURE: Support mirage version indication in first line of config.ml:
  (* mirage >= 2.3.4 & < 5.0.0 *) (#1466 @hannesm, fixes #1381)
• Use \033 instead of \e in generated Makefile (fixes the output on non-Linux
  systems #1464 @hannesm)
• Adapt to mirage-logs 2.0.0 (#1460 @hannesm)
• Allow version 0.8.0 of solo5 (#1432 #1490 @hannesm @palainp)

CHANGES:

• Fail configure if jobs without arguments are present
  (fixes #873 #1426, #1428 @hannesm)
• mirage-runtime & functoria-runtime: remove fmt dependency (#1417 @hannesm)
• Fix tests on macOS (#1425 @samoht)
• Adapt to happy-eyeballs 0.6.0 release (#1427 @hannesm)
• Adapt to logs-syslog 0.4.0 release (#1424 @hannesm)
• Adapt to docteur 0.0.6 release (#1419 @dinosaure)
• Upgrade tests to cmdliner 1.2.0 (#1418 @hannesm)
• Fail if jobs without arguments are registered (reported #873 @kit-ty-kate
  #1426 @reynir @PizieDust, fixed #1428 @hannesm and #1431 @reynir)
• Console is marked as deprecated (#1429 @hannesm)
• Tracing has been removed, since it was not used anymore and not supported with
  solo5-xen-pvh (#1430 @hannesm)

CHANGES:

• Allow paf 0.4 and 0.5 (#1414 @hannesm)
• Remove bytes dependency from functoria-runtime (#1411 @hannesm)
• Allow git-mirage 3.13 (#1412 @dinosaure @hannesm)

CHANGES:

Changed

• Remove OCaml dependency to allow OCaml 5 being chosen (#1409 @palainp)
• Disallow empty key names (#1407 @reynir)
• Allow tls-mirage 0.17 (#1405 @hannesm)
• Allow tcpip 8.0 (#1410 @hannesm)
• Fix typo in generated Makefile (#1406 @hannesm)

CHANGES:

Fixed

• Add -f to Makefile output (#1394 @hannesm)

Added

• Add tar_kv_ro and tar_kv_rw (#1389 @reynir)

Changed

• Improved documentation of mirage.mli (#1390 #1391 @reynir)
• Deprecate Mirage.archive (use tar_kv_ro, #1389 @reynir)
• Removed deprecated device git_happy_eyeballs (#1388 @TaeminHa)
• Adapt bounds: mirage-crypto 0.11.0 (#1392 @hannesm) git-mirage 2.13.0
  (#1396 @hannesm) dns 7.0.0 tls 0.16.0 (#1399 @hannesm)
  mirage-block-ccm (#1400 @hannesm)
• mirage-runtime: conflict with ppxlib 0.29 (#1397 @hannesm)
• add upper bound to dune 3.7 until a release of chamelon with fixes lands (see
  https://github.com/mirage/mirage/pull/1401#issuecomment-1440762994)

CHANGES:

Fixed

• add (merlin) to the dune-workspace file -- this allows merlin to properly work
  with unikernels (#1385, fixes #1384 @TheLortex @hannesm)
• add "build" stanzas to packages that are supposed to be vendored (#1383,
  @Leonidas-from-XIV) for "opam-monorepo 0.3.5" compatibility

Changed

• raise upper bound for git to 3.12 (#1387 @dinosaure)

CHANGES:

Fixed

• use "printf" instead of "echo -e" in Makefiles for macOS support (#1370,
  @gridbugs)

Changed

• raise lower bound of solo5 to 0.7.5 (#1380 @dinosaure)
• remove "-warn-error -A" from generated dune file (for config) (#1379 @hannesm)

Added

• CCM device for block device encryption (#1364 @dinosaure)
• ALPN client and mimic device (#1376 @dinosaure)

CHANGES:

Fixed

• adapt to conduit 6.0.1 API (delay the parsing of the nameserver list)
  (#1362 #1369, @reynir @hannesm, fixes #1360)
• improve the generic_dns_client documentation (#1365, @dinosaure)
• upgrade to git 3.10.0 (#1366, @dinosaure)

Changed

• mirage-runtime: use Logs.level_of_string / level_to_string, avoid manual
  construction of Cmdliner.Arg.conv types (use the Cmdliner.Arg.conv function
  instead) (#1358, @hannesm)

Added

• functoria-runtime: provide argument_error exit code (#1361, @hannesm)
• add a http_server device using paf (#1367, @dinosaure)

CHANGES:

Fixed

• The chamelon format example invocation had the arguments in the wrong order
  (#1351, @hannesm)
• tar-mirage: allow the 2.x release series (#1352, @hannesm)
• Fix the separator for list and pair combinator (command-line arguments, #1354,
  @dinosaure, reported in #1349 #1348 by @rand00)
• Update references (hyperlinks) to erratique.ch documentation (#1343, @reynir)

Changed

• Allow more log levels (None / quiet) (#1275, @reynir, closes #1273 & #1274)
• Improve Functoria CLI: don't fail if context cache is invalid, handle
  situation when global arguments have a parse error (#1359, @TheLortex)
• Remove v4 & v6 stack, and other deprecated bindings (#1341, @hannesm)
• Remove FS remnants, and kv_ro of archive, and brittle shell scripts
  that used to generate FAT block storage devices (#1353, @hannesm)
• Update to OCamlFormat 0.23.0 (#1351, @dinosaure)

CHANGES:

Fixed

• In the generated opam file, also run "depext-lockfile" (#1342, @hannesm)

CHANGES:

Fixed

• Remove non-existing mirage-repo-add and mirage-repo-rm from PHONY in generated
  Makefile (#1332, @hannesm)
• Update deprecated references (#1337, @reynir)

Changed

• Prepare for reproducing unikernels with generated opam file (#1335, @hannesm)
  • split x-mirage-configure (mirage configure), x-mirage-pre-build
    (make lock pull), and build instructions in opam file
  • embed x-mirage-extra-repo (a list of opam repositories to use)
  • take relative paths up to git repository into account
  • include x-mirage-opam-lock-location (relative to git repository root)
• Adapt constraints for mirage-solo5 0.9.0 and mirage-xen 8.0.0 (ocaml-solo5
  0.8.1 with trim and improved memory metrics) (#1338, @hannesm, based on
  @palainp work)
• Require opam-monorepo 0.3.2 (#1332 #1334, @hannesm @dinosaure)
• Use OPAMVAR_monorepo instead of OPAMVAR_switch in generated opam file (#1332,
  @hannesm)
• Remove name from opam file (#1332, @hannesm)

CHANGES:

Fixed

• Update constraints on generated OPAM files (d21de15, @dinosaure)

CHANGES:

Changed

• Be able to make a docteur image with a relative path (@dinosaure, #1324)

• Update the project with ocamlformat.0.21.0 (@gpetiot, @dinosaure, #1286)

• Upgrade the mirage tool with opam-monorepo.0.3.0 and generate
  a single OPAM file (@TheLortex, @hannesm, @dinosaure, #1327)

  You should check the opam-monorepo.0.3.0 release to get more details about
  updates and fixes.

Added

• Add chamelon device, a filesystem with littlefs (@dinosaure, @yomimono, #1300)
• Add pair combinator for MirageOS key (@dinosaure, #1328)

CHANGES:

Fixed

• use --solo5-abi=xen for qubes target (#1312, @hannesm)
• Support using a different filename than config.ml with -f
  (#1309, @dinosaure)
• Fix build with dune 3.0 (#1296, @dinosaure)
• Check that the package name respects opam conventions
  (#1287, #1304, @TheLortex)
• Allow to specify version of pinned packages (#1295, @Julow)

Changed

• Use the same compilation as dune (#1313, #1316, #1317, @samoht, @hannesm)
• Remove unused --warn-errors and --debug flags (#1320, @samoht)
• Remove the deprecated --target=ukvm (#1321, @hannesm)
• Require cmdliner 1.1 (#1289, @samoht, @dinosaure, @dbuenzli)
• Require opam 2.1 to use MirageOS (#1239, 1311, @hannesm)
• Require conduit 5.1 (#1297, @hannesm)
• Rename ocaml-freestanding to ocaml-solo5
  (#1314, @dinosaure, @samoht, @hannesm)

Added

• Add Key.opt_all to allows usage of an argument multiple times
  (#1292, #1301, @dinosaure, @Drup)
• Add Git devices (#1291, @dinosaure, @samoht, @hannesm, @yomimono)
• Add happy-eyeballs devices (#1307, @dinosaure, @hannesm)
• Add docteur device to manage read-only persistent key-value stores
  (#1298, @dinosaure, @samoht)
• Add tcpv4v6_of_stackv4v6 device (#1293, @dinosaure)
• Add int64 converter (#1305, @dinosaure)
• Add dns_client device (#1302, #1306, @dinosaure, @hannesm)

CHANGES:

• Lint constraints on few packages to split the world between MirageOS 3.0 and
  MirageOS 4.0 (#1280, @dinosaure)