Batamanta.EscriptPackager (batamanta v1.5.0)

Copy Markdown View Source

Packages escripts for batamanta distribution.

This module creates a tarball containing the escript and minimal ERTS runtime, optimized for size. Unlike releases, escripts embed the Elixir runtime directly, so we only need a minimal ERTS subset.

The payload is extracted to a release/ directory and matches the structure expected by the Rust wrapper:

payload.tar.zst
    ├── bin/
    │   └── <app_name>      # the compiled escript
    └── erts/
        ├── bin/
        │   ├── erlexec
        │   ├── erl
        │   ├── escript
        │   ├── beam.smp
        │   └── heart
        └── lib/
            └── (minimal runtime libs: kernel, stdlib, compiler)

Escripts are typically 60-70% smaller than releases because:

  • Elixir runtime is embedded in the escript itself

  • We bundle only the minimal ERTS needed to run beam

  • No boot scripts, sys.config, or full OTP libraries

  • Uses system tar command for reliable archive creation

  • Uses zstd for high-compression final output

  • Reproducible builds with fixed ownership and timestamps

Summary

Functions

estimate_size(escript_path)

Returns the approximate size of a minimal ERTS package. Useful for user feedback.

package(escript_path, erts_path, output_path, compression_level \\ 3)

Packages an escript with minimal ERTS into a compressed tarball.

prepare_minimal_erts(erts_source, erts_dest)

Prepares a minimal ERTS for escript execution by copying the necessary files from erts_source (the ERTS cache) to erts_dest (a temp dir).

Functions

estimate_size(escript_path)

@spec estimate_size(Path.t()) :: {:ok, integer()} | {:error, String.t()}

Returns the approximate size of a minimal ERTS package. Useful for user feedback.

package(escript_path, erts_path, output_path, compression_level \\ 3)

@spec package(Path.t(), Path.t(), Path.t(), integer()) ::
  {:ok, Path.t()} | {:error, String.t()}

Packages an escript with minimal ERTS into a compressed tarball.

  • escript_path - Path to the compiled escript

  • erts_path - Path to the fetched ERTS directory (cache — never modified)

  • output_path - Path for the output .tar.zst file

  • compression_level - Zstd compression level (1-19, default: 3)

  • {:ok, output_path} on success

  • {:error, reason} on failure

prepare_minimal_erts(erts_source, erts_dest)

@spec prepare_minimal_erts(Path.t(), Path.t()) :: :ok

Prepares a minimal ERTS for escript execution by copying the necessary files from erts_source (the ERTS cache) to erts_dest (a temp dir).

The cache is never modified.

For escripts we only need:

  • The beam emulator (beam.smp or erl)
  • erlexec and escript (for escript handling)
  • Essential runtime libraries (kernel, stdlib, compiler)

We exclude Elixir libs from the ERTS bundle because the escript file already embeds all Elixir code; having a stale or mismatched Elixir in the bundled ERTS lib/ would cause module-redefinition conflicts.