Shipping a program

A FutureBlitz program builds into one native executable, with the runtime and the C libraries the standard library uses linked in. Shipping it is copying that file, and the few others this guide names when a program has them.

1. Build it for release

fb build --release

A release build is optimized and lets integer overflow wrap, where a debug build panics on it. The executable goes in the package’s build/ folder, named after the package, or where -o says:

fb build --release -o dist/shop

On Windows it’s shop.exe.

2. Build it on each OS

fb builds for the OS and architecture it runs on, so a program for Windows, macOS, and Linux is built on each, as a CI matrix does (Testing in CI has one). The targets are windows-x64, macos-arm64, macos-x64, linux-x64, and linux-arm64.

What each one runs on:

• Windows: Windows 10 or later. Nothing else is needed: the C and C++ runtimes link in.
• macOS: the macOS fb runs on, macOS 15 or later. macOS stops an unsigned executable that was downloaded in a browser, so sign it with an Apple Developer ID, or have the people who run it clear the mark, with xattr -d com.apple.quarantine shop.
• Linux: glibc 2.28 or later: RHEL 8, Ubuntu 20.04, Debian 10, and later. fb links Linux programs against that glibc, so one built on a new distribution runs on old ones, with no other library needed.

3. Ship what goes beside it

Most programs are the executable alone. Two things add files beside it, and fb build lists each one:

• A dependency that’s link = "beside" in project.toml builds as a library of its own: charts.dll on Windows, libcharts.so on Linux, and libcharts.dylib on macOS.
• A [native] library that’s dynamic is copied beside the executable.

On Windows, a debug build also writes a .pdb beside the executable, with its debug info for a debugger. The program doesn’t need it to run.

The executable finds its libraries beside it, so keep them in one folder.

4. Ship the notices

When a program uses one of the C libraries the standard library is built on, like SQLite for std.db or libcurl for std.net.http, fb names it after the build, with its license and the file of its notices:

     Bundled <library> <version>, under <its licenses>; ship its notices with the program: <FutureBlitz>/notices/<library>.txt

Those licenses ask that the notices go with the program: put the files beside it, or in its documentation.

5. Read its crashes

Every executable, release builds too, has a table of where each call is, so a panic on someone else’s machine prints a stack trace in FutureBlitz’s names, files, and lines, with no debug files shipped:

panic: index 5 is out of range for 3 elements at stock.fb:12:17
    at Pick (stock.fb:12)
    at Restock (stock.fb:20)
    at top-level code (main.fb:8)

A program that panics exits with 101. Ask whoever saw it for those lines, and Debugging takes it from there.