# `Kettlecorn.Cook`
[🔗](https://github.com/mjrusso/kettlecorn/blob/v0.1.0/host/lib/kettlecorn/cook.ex#L1)

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.

# `cook`

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}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
