MirageOS 3 description of changes.

gistfile1.txt

Less Code, Less Magic, More Results

## Major Changes

* The solo5 targets `ukvm` and `virtio` (see [https://mirage.io/blog/introducing-solo5]), which allow unikernels to run on KVM hypervisors and on FreeBSD via bhyve, are now available in the mainline `mirage` package.  These targets use a newly refactored freestanding OCaml runtime (see [https://github.com/mirage/ocaml-freestanding]).
* The `V1` and `V1_LWT` modules, which contained module type definitions agreed upon by implementations used in `mirage`, have been renamed to `Mirage_types` and `Mirage_types_lwt`.  The module type definitions themselves are no longer contained in this repository, but have been moved to their own independently-versioned repositories and are merely referenced from `Mirage_types` and `Mirage_types_lwt`.
* Across the universe of module type definitions, errors in computation are now signalled by a `result` type and a set of polymorphic variants representing common errors that might occur.  Individual implementations may extend this set, and users can always count on the provided module to provide a pretty-printer for these errors.
* The `CLOCK` module type has been replaced with `PCLOCK` and `MCLOCK`, which represent a POSIX-style wall clock and a monotonically-increasing clock respectively.  The `Mirage` module provides `default_posix_clock` and `default_monotonic_clock` for getting an `impl` of each clock.  Existing functions which took a `clock impl` argument now take an `mclock impl` wherever this is reasonable (in practice, everywhere except for `logs`).
* `mirage-types-lwt` is now its own opam package, rather than an optionally installed sub-library bundled with `mirage-types`.
* `mirage configure` no longer automatically attempts to install packages.  Rather, it generates a `.opam` file representing the dependencies that have been discovered based on the `config.ml` and the arguments passed to `mirage configure`.  Running `make depend` against the Makefile generated by `mirage configure` will attempt to install these dependencies via opam.
* Documentation for the project is now automatically built and provided via `odig`.
* The build system for `mirage` and many other libraries has been changed from OASIS to `topkg`.

### Less Major API changes to `Mirage` module

* `Mirage.register` and `Mirage.foreign` no longer take a `libraries` argument.  Their `packages` argument is now of type `Functoria.package list`, and the `library` information is included in `package`.
* `connect` functions provided by individual implementations are no longer expected to return a `t result` or `Ok t` by the `mirage` front-end tool's code generation.  Rather, they are expected to raise an exception on failure and return the value directly on success.
* Two `random` impls are now available - `stdlib_random`, which wraps the OCaml `Random` module, and `nocrypto_random`, which is a passthrough to the Fortuna PRNG implemented in the nocrypto library.  `default_random` is available for accessing `stdlib_random` by default, but can be told to use `nocrypto_random` at compile or runtime via the `prng` key.
* A `syslog` implementation is usable from `mirage`.  Construct a record of type `Mirage.syslog_config` and call `Mirage.syslog_udp`, `Mirage.syslog_tcp`, or `Mirage.syslog_tls` to obtain a `syslog impl`.
* Functions for interfacing with the `mirage-qubes` library are now included: `Mirage.qubes_ipv4_stack` and `Mirage.ipv4_qubes`, as well as `Mirage.default_qubesdb`.  Unikernels which are built with these functions will fail unless `mirage configure` is invoked with `-t qubes`.
* `Mirage.tap0` has been renamed to `Mirage.default_network` and now works as expected on Xen targets.
* `Mirage.farp` is available as an alternative to `Mirage.arp`, and will use [https://github.com/hannesm/arp] instead of the ARP implementation in mirage-tcpip.
* The `Mirage.ipv4_config` and `Mirage.ipv6_config` types have been changed to reflect reasonable configuration assumptions rather than attempt to mirror one another's structure.
* `Mirage.create_ipv4` now takes `ethernet impl` and `arpv4 impl` arguments, rather than creating an `ipv4 impl` directly from a `network impl` and hiding the intermediate `ethernet` and `arpv4` from the caller.
* `Mirage.create_ipv6` now takes an `ethernet impl` argument rather than a `network impl` argument.
* `Mirage.default_ipv4` has been removed.
* `Mirage.direct_udp` now takes an optional `random impl` argument.
* Functions which yield a `stackv4 impl` now take an `ipv4 impl` argument instead of a `network impl`.
* `Mirage.direct_stackv4_with_default_ipv4` and `direct_stackv4_with_static_ipv4` no longer exist.  Instead, consider using `direct_stackv4`, `static_ipv4_stack`, or `dhcp_ipv4_stack`.
* Network-related functions which took a `console impl` argument no longer do so.
* `Mirage.get_mode`, `Mirage.add_to_opam_packages`, and `Mirage.add_to_ocamlfind_libraries` have been removed (as warned in the 2.9.1 release).

### Less Major API changes to `Mirage_key` module

* `Mirage_key.is_xen` has been removed and `Mirage_key.is_unix` added, as that is the more exceptional case.
* `Mirage_key.ipv4` is now an (Ipaddr.V4.Prefix.t * Ipaddr.V4.t) converter.  For an `Ipaddr.V4.t converter`, use the new `Mirage_key.ipv4_address`.
* A type `Mirage_key.mode` is available for referring to the set of polymorphic variants including Unix, Xen, MacOSX, Ukvm, Virtio, and Qubes.
* `Mirage_key.no_ocaml_check` has been removed.
* `Mirage_key.kv_ro` may now produce a `direct` key in addition to `Archive`, `Crunch`, and `Fat` keys.
* `Mirage_key.prng` is available for choosing between the standard library and nocrypto random implementations.
* `Mirage_key.network` has been renamed to `Mirage_key.interface`, as `network` has been repurposed in the `Mirage_key.V4` and `Mirage_key.V6` modules.
* `Mirage_key.V4.ip` and `Mirage_key.V4.netmask` have been replaced with `Mirage_key.V4.network`, which treats the IP and netmask as a single item.
* `Mirage_key.V4.gateways` has been replaced with `Mirage_key.V4.gateway`, which is a `t option` instead of the previous `t list`.
* `Mirage_key.V6.ip` and `Mirage_key.V6.netmask` have been replaced with `Mirage_key.V6.ips` and `Mirage_key.V6.netmasks` respectively, which accept lists instead of single items.

### Less Major API changes outside of `mirage`

* `format` function and `Format_unknown` error have been removed from the FS module type in `mirage-fs`.
* `read_stream`, `io_stream`, and `read_until` have been removed from the CHANNEL module type in `mirage-channel`.
* `log` has been removed from the CONSOLE module type in `mirage-console`.  `log_s` has been renamed to `log` to replace it.
* `id` has been removed from the DEVICE module type in `mirage-device`.
* The RANDOM module type provided by `mirage-random` now includes a function `generate` that provides random bytes as a buffer (currently a `Cstruct.t`), replacing the previous `int`-based interface.
* A `mem` function is now required by the KV_RO module type in `mirage-kv`.
* The `read` and `size` functions required by the KV_RO module type in `mirage-kv` now take `int64`s rather than `int`s.
* `sleep` (which took a float argument representing the number of seconds) has been replaced by `sleep_ns` (which takes an int64 representing the numer of nanoseconds) in the module type TIME provided by `mirage-time`.
* IP source and destination argument names have been standardized to `src` and `dst`, and source and destination ports to `src_port` and `dst_port`, in the module types provided by `mirage-protocols`.
* The `pseudoheader` function is now required for IP module types in `mirage-protocols`.

### Less Major Usage Changes

* An additional target `qubes` exists for automatically packaging the additional libraries and initialization logic necessary for running MirageOS on QubesOS.  The `qubes` target is at its heart `xen plus some other stuff`.
* `mirage configure -f` will no longer traverse into subdirectories. `mirage configure` needs to be called with a working directory the same as the configuration file.
* `mirage configure --unix` and `mirage configure --xen` are no longer understood, as warned in the 2.9.1 release.  Instead, use `mirage configure -t unix` and `mirage configure -t xen` respectively.
* The artifact generated by `make` is no longer prefixed with `mir-`, and the name given to `register` will be stripped of OCaml-unfriendly characters before files are written.

### Bugfixes and Other Improvements

* Functions used by `mirage`-generated programs at runtime have been split off into the `mirage-runtime` package, which will be linked instead of the full `mirage` package.  (This is largely the collection of parsers for runtime keys.)
* The mirage command-line utility is now at `mirage_cli.ml` for easier discovery.
* It's now possible to get an `ipv6 impl`.
* Tar file generators for use with `tar-format` implementations are less broken.
* The `Str` module is no longer included in the OCaml runtime.
* Emit an ocamlfind predicate that matches the target.
* Improvements to nocrypto handling.
* Using `crunch` always requires `io-page`.
* Xen unikernels will no longer refuse to start when they receive unexpected boot parameters.
* Disable warning #42 in generated code.
* `mirage-fs` provides transforming FS into KV_RO, rather than requiring `fat-filesystem`.
* UDP now provides source port randomization even with the direct stack.
* DHCP is now provided by `charrua-client` and `charrua-core` rather than `tcpip`.
* Link libgcc.a only when building on ARM.
* Stop generating so many unnecessary artifacts.
* `clean` target removes more artifacts.
* Comply with `mirage-clock-xen`'s rename to `mirage-clock-freestanding`.