Building a program
In AEL, the Agent Engineering Language, ael build (command names may change before launch) will turn a project into a native program for one target: a native executable for an operating system, or a firmware image for a microcontroller board.
Status
Planned for AEL Beta 0.0.1. AEL is not available yet.
Usage
ael build --target <target> -o build/support
ael build --target <target> -o build/support --release
ael build --target <target> -o build/support --debug
ael build --target <board> -o build/sensors --release --memory-report
ael build build/compiled --target <target> -o build/support
| Argument or option | Meaning |
|---|---|
[path] | The project folder, or a folder of compiled AEL written by ael compile. Without a path, the project in the current folder. |
--target <target> | What the program will run on: an operating system and processor, or a board. |
-o <file> | The file to write. |
--release | A release build, the kind you deploy. |
--debug | A build with source-level debugging information. Use one of --release and --debug, not both. |
--memory-report | For a board: report the firmware's RAM, flash and stack use. |
--json | A machine-readable report, with any diagnostics. |
Planned targets lists the targets planned for Beta 0.0.1.
The steps of a build
Every build will go through the same steps, and none can be skipped:
- Check and compile. From source, the project will be checked and compiled, as
ael checkandael compiledo. From compiled AEL, each compiled file will be verified instead. - The reference map. The complete reference map will be computed and verified, starting at
main. - The native program. Only what the program reaches will go into it, and the result will be written in one step.
The build will use only the packages already installed and pinned by your lock files. It will never download anything, and it will run none of your code and no package code.
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 will stay out. An HTTP-only app will carry no gRPC or WebSocket code, and a GET-only API no POST handlers.
A feature that the target cannot support will fail the build, not on the device. Each build will record 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.
- For a board: a firmware image, written to a device only when you ask, with
ael flash. Building will never flash a device.
Debug builds
--debug will add what standard native debuggers need to debug at source level: the lines of your AEL source for each part of the program. It will add information only: the program's code will be the same as in a build without it. Which targets offer source-level debugging will be listed with the final list of targets; Desktop and server describes debugging a build.
Memory reports
For a board, --memory-report will report 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 will be able to 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 will check every compiled file before using it, reject files that were changed or built for another target, and compute the reference map again. The program will still start at the project's main.
Not settled yet
What a build without --release or --debug produces, and the default name of the output file, will be described when the build options are final.
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.