Browse the documentation

Early preview

Building a program

oel build turns a project into a native program for one target: a native executable for an operating system, or a firmware image for a microcontroller board.

Usage

oel build --target <target>
oel build --target <target> --release
oel build --target <target> --debug
oel build --target <target> -o build/support
oel build --target <board> -o build/sensors --release --memory-report
oel build build/compiled --target <target> -o build/support
Argument or optionMeaning
[path]The project folder, or a folder of compiled files written by oel compile. Without a path, the project in the current folder.
--target <target>What the program runs on: an operating system and processor, or a board.
-o <file>The file to write, in place of the program named after the application.
--releaseA release build, the kind you deploy.
--debugA build with source-level debugging information. Use one of --release and --debug, not both.
--memory-reportFor a board: report the firmware's RAM, flash and stack use.
--jsonA machine-readable report, with any diagnostics.

Supported targets lists the targets.

The program's name

The program takes your application's name, the name in metadata.oel that main carries. Without -o, a project whose main.oel declares main support() builds into support, beside main.oel. 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 oel check and oel compile do. From compiled files, each 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 signatures in the Open Engineering Language, 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 oel flash. Building never flashes a device.

Debug builds

--debug adds what standard native debuggers need to debug at source level: the lines of your 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 files instead of source. Compile once, then build from the output folder, with no .oel files present:

oel compile --target <target> -o build/compiled
oel 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.

Building from a folder of pairs

--pairs builds a native program from the folder that oel compile --pairs or oel compile --owner-libraries wrote, with no source anywhere:

oel build --pairs build/pairs --target <target> -o build/support
OptionMeaning
--pairs <dir>The folder of pairs, in place of a project.
--target <target>What the program runs on.
-o <file>The file to write. The file may not lie inside the pair folder.
--entry <name>The entry function, written as package::module::main.
--cache <dir>Reuse results between builds.
--jsonA machine-readable report, with any diagnostics.

The build checks the folder before it links anything:

  • every file is a pair file or the receipt, and a link, a device or any other file is refused by name;
  • both halves of every pair are present, each pair is checked against its own description, and a pair that was moved out of its component's folder is refused;
  • the receipt pairs.json must list exactly the pairs found, with their digests: a folder that is incomplete, extended or changed after it was written does not link;
  • pairs from two different compilations of a project do not link together, and at most 1,024 pairs link in one build.

The verified pairs then go through the same linking and native build as any other input. oel run --pairs builds and starts it in one step.