Building a program

Usage

ael build --target <target>
ael build --target <target> --release
ael build --target <target> --debug
ael build --target <target> -o build/support
ael build --target <board> -o build/sensors --release --memory-report
ael build build/compiled --target <target> -o build/support

Supported targets lists the targets.

The program's name

The program takes your application's name, the name in metadata.ael that main carries. Without -o, a project whose main.ael declares main support() builds into support, beside main.ael. With -o, the program is written to the file you name instead.

The steps of a build

Every build goes through the same steps, and none can be skipped:

1. Check and compile. From source, the project is checked and compiled, as ael check and ael compile do. From compiled AEL, each compiled file is verified instead.
2. The reference map. The complete reference map is computed and verified, starting at main.
3. The native program. Only what the program reaches goes into it, and the result is written in one step.

The build uses only the packages already installed and pinned by your lock files. It never downloads anything, and it runs none of your code and no package code.

Functions in other languages

Your application can hold private functions written in other languages, with typed AEL signatures, built and run with your own toolchains, pinned by version.

• When a project declares them, the build compiles each one with your toolchain for its language, at the version it pins. The toolchains compile the code you declared; none of your functions runs while you build.
• The compiled code of those functions is written beside the program.
• A project that declares no function in another language starts no toolchain at all.

Functions in other languages says what the build checks first and what it refuses.

What goes into the program

Only what your program can reach from main: its components, the package exports it uses and the support they need. A component nothing reaches, a route file that is never mounted and a package that is installed but never selected stay out. Only what you use ships: an HTTP-only app carries no WebSocket code, and no gRPC code unless an edge is placed on the network, and a GET-only API no POST handlers.

A feature that the target cannot support fails when you build, not on the device. Each build records exactly what went into it, so you can check what a program contains.

What you get

• For an operating system: a self-contained native executable, with no interpreter or virtual machine to run and no second language to install unless you write functions in one.
• For a board: a firmware image, written to a device only when you ask, with ael flash. Building never flashes a device.

Debug builds

--debug adds what standard native debuggers need to debug at source level: the lines of your AEL source for each part of the program. It adds information only: the program's code is the same as in a build without it. Desktop and server describes debugging a build.

Memory reports

For a board, --memory-report reports how much RAM, flash and stack the firmware image needs, so you can see before flashing whether it fits the board.

Building without the source

A build can start from compiled AEL instead of source. Compile once, then build from the output folder, with no .ael files present:

ael compile --target <target> -o build/compiled
ael build build/compiled --target <target> -o build/support

The build checks every compiled file before using it, rejects files that were changed or built for another target, and computes the reference map again. The program still starts at the project's main.

Related

• Running a program: check, build and run in one step.
• Reference maps: the map every build checks.
• Flashing a board: writing a firmware image to a device.