Bakeware

CircleCI Hex version Hex Docs Total Download License Last updated

Compile Elixir applications into single, easily distributed executable binaries

The Bakeware oven

Bakeware was made over a weekend at SpawnFest 2020 and thanks to the response from the community, we're working on finishing it off. While it's not ready for production, it's definitely ready for experimentation - just expect APIs to change in the near-term. If you'd like to help, please let us know and stay tuned!

Bakeware extends Mix releases with the ability to turn Elixir projects into single binaries that can be copied and directly run. No need to install Erlang or untar files. The binaries look and feel like the build-products from other languages.

Here's a quick list of features:

  • Simple - add the bakeware dependency and the Bakeware assembler to your Mix release settings
  • Supports OSX and Linux (We wrote the code with Windows and the BSDs in mind, so support for those platforms may not be far off)
  • Zstd compression for small binaries
  • Optional support for automatic software updates (work in progress)
  • Command-line argument passing conveniences
  • Lots of examples

This README contains the basics of making your applications work with Bakeware and reference material for when you need to dig into how it works.

Since everything was written quickly and the integration is fairly straightforward, we recommend that you take a look at the examples. The examples are bare bones Elixir scripts, OTP applications, Phoenix applications and more with small changes to their mix.exs files and instructions for running that you can try out for yourself.

Using

Mix release

Bakeware supports tieing in executable binary assembly into a Mix release as a step by using the Bakeware.assemble/1 function.

This will assemble the necessary components to create a Bakeware executable that can be distributed across machines to run the script/application without extra environment setup (such as installing Elixir/Erlang, etc)

To use, add this to your release as a step after assembly:

def release do
  [
    demo: [
      steps: [:assemble, &Bakeware.assemble/1]
    ]
  ]
end

Mix task

Bakeware also supports manually assembling the executable via mix bakeware.assemble

Generally, it is expected that you integrate assembly as a Mix release step (see Bakeware.assemble/1)

However, this task provides the ability to manually assemble the Bakeware executable binary either for the current project, or for other specified release directories.

Supported options:

  • --name - Name to use for the binary. Defaults to the app name
  • --path - path to release directory. Defaults to release directory of current Mix project <!-- ASSEMBLE_TASK !-->

Scripting

Bakeware supports an API similar to Escript for implementing a main function.

The main function will take 2 arguments:

  • arg0 - The absolute path to the executable
  • args - Analogous to argv in other languages. A list or arguments passed to the executable

The main function must return a superset of functions that :erlang.halt/1 supports:

  • integer -> returning an integer will set the exit status. IE success: 0, error: >= 1
  • iodata -> An Erlang crash dump is produced with iodata as slogan. Then the runtime system exits with status code 1. The string will be truncated if longer than 200 characters.
  • :abort -> The runtime system aborts producing a core dump, if that is enabled in the OS.

Example:

defmodule MyApp.Main do
  use Bakeware.Script

  @impl Bakeware.Script
  def main(_arg0, _args) do
    IO.puts "Hello, World!"
    0
  end
end

Tips

Minimizing executable size

Bakeware binaries appear to have a lower bound of about 12 MB in size. We expect that they can be made smaller out-of-the-box, but here are a few things you can do:

  1. Make sure zstd is installed to enable compression during assembly:
  • MacOS: brew install zstd
  • Ubuntu: apt-get install zstd
  1. Build using MIX_ENV=prod. The default is MIX_ENV=dev, so be sure that the environment variable is set.
  2. Run rm -fr _build and then mix release. During development cruft builds up in the release directory. Bakeware can't tell the difference between the important files and the cruft, so executables will slowly grow in size if you don't do a clean build.
  3. Inspect your _build/prod/rel/<name> directory and especially under lib for files or dependencies that you might be including on accident.
  4. Make sure that compile-time dependencies are marked as runtime: false in your mix.exs so that they're not included

Creating cross-platform binaries

Bakeware binaries include the Erlang runtime but there are still dependencies on the host system. These include the C runtime and other libraries referenced by the Erlang runtime and any NIFs and ports in your application. Luckily, the binary ABIs of many libraries are very stable, but if distributing to a wide audience, it's useful to build on a system with older library versions. Python has a useful pointers in their packaging guides.

Reference material

Command-line arguments

In general, command-line arguments passed to Bakeware applications are passed through to Elixir. A few special command-line arguments can be passed to adjust the launchers behavior. Bakeware stops parsing command-line arguments when it encounters a --. Processed command-line arguments are not passed along to Elixir.

The following arguments may be passed:

  • --bw-info - Print out information about the application
  • --bw-gc - This cleans up all unused entries in the cache (NOT IMPLEMENTED)
  • --bw-install - Do not run the application. Stop after installing to the cache directory. (NOT IMPLEMENTED)
  • --bw-system-install - Install to a system-wide location (NOT IMPLEMENTED)

Environment variables

The Bakeware launcher sets the following environment variables for use in Elixir:

Variable nameDescription
BAKEWARE_EXECUTABLEThe absolute path to the executable
BAKEWARE_ARG1The first command-line argument
BAKEWARE_ARGnThe nth command-line argument
BAKEWARE_ARGCThe number of arguments

See the Scripting section of this document for a more user friendly API.

Binary format

Bakeware application binaries look like this:

  • Bakeware application launcher
  • A CPIO archive of an Erlang/OTP release
  • Trailer

The CPIO archive can be compressed. This depends on the contents of the trailer.

Trailer format (multi-byte fields are big endian):

Offset from endFieldTypeDescription
-4Magic4 byte stringSet to "BAKE"
-5Trailer version8-bit integerSet to 1
-6Compression8-bit integer0 = No compression, 1 = Zstd
-8Flags16-bit integerSet to 0 (no flags yet)
-12Contents offset32-bit integerOffset of CPIO archive
-16Contents length32-bit integerLength of CPIO archive
-48SHA25632 bytesSHA-256 of the CPIO archive

Cache directory

Bakeware maintains a cache of extracted binaries. This is needed to run the OTP releases and it enables start-time optimizations.

The cache directory location is system-specific:

  • Windows - "C:/Users/<USER>/AppData/Local/Bakeware/cache"
  • MacOS - "~/Library/Caches/Bakeware"
  • Linux and other Unixes - "~/.cache/bakeware"

Here's the layout of each cache entry:

PathCreated byDescription
$CACHE_DIR/$SHA256/source_pathsLauncherA list of source paths (used for GC)
$CACHE_DIR/$SHA256/binCPIOOTP release's bin directory
$CACHE_DIR/$SHA256/erts-x.y.zCPIOOTP release's ERTS
$CACHE_DIR/$SHA256/libCPIOOTP release's lib directory
$CACHE_DIR/$SHA256/releasesCPIOOTP release's releases directory
$CACHE_DIR/$SHA256/startCPIOStart script. E.g., bin/my_otp_release start

TODO: Add lock file to protect an executable being extracted on top of itself. This might actually work, though...

LICENSE

All code is licensed under Apache-2.0 with the exception of zstd which is dual licensed BSD/GPL. See it's LICENSE and COPYING files for more details.