Kettlecorn.Cook (kettlecorn v0.1.0)

Copy Markdown View Source

Packages a compiled Mix application and its dependencies for the guest.

Cooking evaluates configuration on the host. The Mix task also compiles the project and its dependencies there. Cook trusted projects or isolate the build separately; guest isolation starts when the bundle runs.

A cooked application is a directory that is copied to the guest's /app when a VM starts:

<out>/kettlecorn.json       protocol and compiler compatibility
<out>/app                   the entrypoint application's name
<out>/sys.config            its configuration (config/config.exs, read at cook time)
<out>/lib/<app>/ebin         the application and its dependencies
<out>/lib/<app>/priv         their priv/ files

Start the application with Kettlecorn.start_link(app: "<out>") or kettlecorn-run --app <out> .... The entrypoint starts before the VM reports that it booted. Cooked applications replace the runtime's copies of the same name, so a bundle can supply its own Req version, for example.

The guest loads sys.config before starting these applications. kernel and stdlib are already running; their settings only affect subsequent configuration reads.

Use it through mix kettlecorn.cook inside the project.

Compile guest code with the runtime's OTP major release and exact Elixir version. Guest applications cannot load native NIFs or start OS processes. The packager warns about .so files in priv/. config/runtime.exs is not evaluated: the guest has no Mix.

Summary

Functions

Cooks an application. Options

Functions

cook(opts)

Cooks an application. Options:

  • :app (required) - the entrypoint application.
  • :build (required) - the build's lib directory, e.g. _build/prod/lib.
  • :out (required) - output path. Cooking publishes a symbolic link and replaces it atomically on subsequent cooks; a failed cook preserves it. Move an existing ordinary directory aside first. Previous copies stay in <out>.versions until removed after their readers have finished.
  • :config - a config file to read into sys.config, e.g. config/config.exs.
  • :env - the Mix environment for :config (default :prod).
  • :roots - more applications in :build to cook with their dependencies, which the entrypoint doesn't depend on (plugins, say, started with Kettlecorn.start_link(apps: ...)).
  • :runtime - check that required dependencies are either cooked or available in this runtime directory.

The bundle includes the entrypoint, extra roots, and their dependencies from :build, as listed in their .app files (applications and included_applications). Available optional dependencies are included too. Unrelated build applications, such as Hex and dependencies marked runtime: false, are omitted. When :runtime is supplied, required dependencies absent from the build must be present in that runtime.

Returns {:ok, %{app: app, apps: cooked_apps}} or {:error, message}.