The parcel contains its own string

A library package ought to contain what its neighbours need to build it. Asking the recipient to fetch a second mystery parcel is a poor way to make introductions.

Pack the helpers with their owner

A publication archive includes both the library and what another BEAM build tool needs:

package archive
  pooka.toml
  rebar.config
  src/
    generated Erlang modules
    package-scoped runtime helper
    application descriptor

This is a layout sketch; the archive also contains the package’s sources, metadata and configured assets.

Pooka has a few runtime helpers: machinery generated programs call for language behaviour that does not lower to a single ordinary operation. There is no separate runtime Hex dependency for the user to add.

Instead, the compiler embeds the needed runtime source into each package’s publication output. The helper module belongs to that package’s generated namespace. Two libraries should not both unpack a different module under the same global name and hope the loader takes turns.

Give the neighbour something it can compile

This is especially important for Erlang interop. An ordinary Pooka build produces BEAM code from abstract forms. A package published for other BEAM build tools also carries generated Erlang source, so those tools can compile it without first installing Pooka.

The two routes serve different jobs. Generated .erl files are part of the publication archive; they do not need to clutter the normal development build directory.

The package metadata matters just as much as the code. The application name, included modules, dependencies and licences should describe the package that actually arrived. A pleasant README cannot repair an application descriptor that asks Erlang to start a nonexistent dependency.

Inspect before it leaves

pooka publish --dry-run

This prepares the package and documentation archives without uploading them. Open the prepared archive before trusting its file list.

A good interop test therefore changes the reader. Instead of asking Pooka whether its own parcel looks plausible, let another build tool compile the contents.

That catches assumptions the original compiler might politely share with itself: an implicit search path, an unshipped helper, or a generated call that depends on something outside the archive.

The source language can keep its own ideas about classes and patterns. The package boundary should be ordinary enough for the neighbour to open.

I have included the string. You should not need a Pooka installation merely to untie it.

— Peregrine Finch