Compiling
oel compile checks a project and turns every component into compiled files: the form a build, a package or another machine can use without your source.
Most of the time you do not need it: oel build and oel run compile as they go. Compile on its own when you want to keep the compiled form, for example to build on another machine without sending it your source.
Usage
oel compile --target <target> -o build/compiled
oel compile <path> --target <target> -o <dir>
| Argument or option | Meaning |
|---|---|
[path] | The project folder. Without a path, the project in the current folder. |
--target <target> | The target to compile for, as for oel check. Compiled files are checked against their target again when they are built. |
-o <dir> | The folder to write compiled files into. |
--json | A machine-readable report, with any diagnostics. |
What it produces
- Every component. Each component file gets its compiled files, including components that
maindoes not reach. Compiling keeps everything; only a build leaves out what the program does not use. - Your folder layout. Compiled files sit at the same relative paths as their source, so the output mirrors your project.
- Extension files inside their component. An extension file's helpers are compiled into the component they belong to; they get no compiled files of their own.
- The root files.
main.oel,pack.oelandmetadata.oelare compiled too, so the output carries the entry point, the package declarations and the project's settings that a build needs.
Compiled files hold no source text and no comments. Each compiled component carries a description of its public interface: its inputs and outputs, what it references and the permissions it needs. That lets a build, or a project that uses your package, check calls to it without the source.
What happens first
oel compile runs the same checks as oel check, and writes nothing if the project fails them. It uses only the packages already installed and pinned by your lock files, and it runs none of your code and no package code.
The output folder is never read back as source.
Building from compiled files
oel build builds a native program straight from compiled files, with no .oel files present:
oel compile --target <target> -o build/compiled
oel build build/compiled --target <target> -o build/support
The build does not take compiled files on trust. It checks each one against its description, rejects files built for another target or changed since they were compiled, and rebuilds the reference map from the compiled files themselves. The program still starts at the project's main: compiled files cannot name a different entry point.
One pair per file
--pairs writes the compiled files as a folder of pairs instead of one file: for every source file of a project, a compiled file and a description of its public interface that sit side by side, at the file's relative path. A build links such a folder without any source:
oel compile <path> --pairs build/pairs --target <target>
oel build --pairs build/pairs -o build/support --target <target>
| Option | Meaning |
|---|---|
--pairs <dir> | The folder to write the pairs into. It takes the place of -o: use one or the other. |
--target <target> | The target to compile for. |
--cache <dir> | Reuse compiled results between runs of the same source. |
--json | A machine-readable report, with any diagnostics. |
- The folder must be new or empty. A path that exists as a file or a link is refused.
- An extension file has no pair of its own. It is folded into the component it extends.
- At most 1,024 pairs. A project with more files is refused before anything is written.
- A receipt comes last.
pairs.jsonlists every pair that was written, with its digest. A build refuses a folder without it, with a pair it does not list, with a listed pair missing, or with bytes that differ from the listed digests, so a run that was killed half way leaves a folder that does not link. - A source edited during compilation is refused. Nothing is published.
--pairs is refused for a single file and for a project in the older project format, which compile to one file.
Libraries of component projects
--owner-libraries <dir> publishes the complete set of libraries of a project that holds components: its agents and nodes with their configuration, and the factory providers that a binding names. A component's library is not executable by itself. The application's pair builds with the libraries beside it, again without source:
oel compile <path> --owner-libraries build/libraries --target <target>
oel build --pairs build/libraries -o build/support --target <target>
The build joins every binding call of the application to the library of the provider it names, and refuses a call whose provider is missing or differs from the source it was compiled from.
Related
- Building a program: from source or from compiled files to a native program.
- Building a package: compiled files packed into a single package file.
- Running a program: the pair folder, launched without the source.
- How it works: the four steps from source to a running program.