Skip to content

docs: cookbook entry for a long-running server entry point #133

Description

@joshrotenberg

Problem

The cookbook covers escripts and mix tasks. Both assume the process exits when
the command returns. Nothing covers the case where the command configures a
process that keeps running.

Two projects have now independently rediscovered the same facts:

  • Under Burrito, main_module in the release config is metadata only. Burrito
    boots the BEAM and never calls it. Application.start/2 is the real entry
    point, so that is where argv gets read and dispatched.
  • Cheer.run/3 returns rather than halting, which is what makes it usable from
    start/2. Cheer.main/3 halts and cannot be used there.
  • start/2 has to return {:ok, pid}, so help and version have to halt
    explicitly rather than falling through.

tinfoil_demo works this out in module docs on TinfoilDemo.Application.
hexpm-mcp is working it out again in joshrotenberg/hexpm-mcp#68. Both comments
exist because the answer was not written down anywhere findable.

Proposal

A cookbook page covering the server shape:

def start(_type, _args) do
  case Cheer.run(MyApp.CLI.Root, Cheer.argv(), prog: "myapp") do
    {:serve, opts}   -> Supervisor.start_link(children(opts), strategy: :one_for_one, name: MyApp.Supervisor)
    :ok              -> System.halt(0)
    {:error, :usage} -> System.halt(2)
  end
end

Points worth stating explicitly:

Depends on #131 and #132 for the final shape, so it is probably worth writing
after those settle.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions