Checking source
oel check checks your code without building or running it, and reports every problem as a diagnostic that points at your source.
Usage
oel check
oel check src/nodes
oel check src/nodes/summarize.node.oel
oel check --target <target>
oel check --json
| Argument or option | Meaning |
|---|---|
[path] | The project, one folder of it or one source file. Without a path, the project in the current folder. |
--target <target> | The target to check for. |
--json | Diagnostics in machine-readable form. See Diagnostics. |
What it checks
It checks that:
- Files and roles. The three root files are present, every other source file is named
<name>.<role>.oelor, for a language file,<name>.<lang>.oel, and each declares exactly one component whose name matches its file name. Extension files hold only private helper functions of their component. - The entry point.
main.oeldeclaresmainfollowed by the name inmetadata.oel, such asmain support(); an entry namedmainis refused. - Size. Every source file is within the size limit, the bodies of functions in other languages included.
- Headers. Imports of reusable functions come before the first declaration and name files that exist; every export you select with
refer … select …is used in code that can run. - Visibility. Each call reaches a function the calling file is allowed to see: its own helpers, global functions of its folder and the folders above, and what it imports or selects.
- Types and ownership. Every value, input and output has the type its use requires, and ownership rules hold.
- Effects and capabilities. Each piece of code does only what it has been allowed to do.
- Hooks. Every hook exists, has the right type for where it is attached, and runs in a valid group.
- Configuration. Settings are known fields with values of the right type.
- Subagents. A subagent, a short-lived agent that an agent spawns at run time, is imported where it is named and spawned only where spawning is allowed, with limits that fit those of the agent that spawns it. See Subagents.
- Isolation. You mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process, outside the shared communication layer, reachable only through the edges you declare and holding only the resources it declares itself. The check refuses an isolated component that reaches anything else. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on macOS, on Windows, on microcontroller boards, on other Linux targets and on any host without those facilities, an isolated component is refused, never run without isolation. See Isolated components.
- Bindings. An agent, subagent or node declares the memory, skills, knowledge, storage and database it uses, each bound to a package you select, and the check refuses any use it did not declare. See Bindings and storage.
- Functions in other languages. Your application can hold private functions written in other languages, with typed signatures in the Open Engineering Language. Their file names, their privacy, their options and their signatures are checked, and every type in a signature must be one that can cross to the other language. See Functions in other languages.
- Packages. Every package a file uses is declared by the nearest
pack.oel, locked in itspack.lockand installed. - The target. The target can offer what the program needs. A feature it cannot support fails here, not on the device.
Every component is checked, including those that main does not reach.
A folder or one file
A folder or a file is checked in the context of its project. It keeps the global functions, imports and packages it inherits from the folders above it, so its result agrees with a check of the whole project. oel check and the build run the same checks, so the two agree.
What it never does
- It changes no file, and never creates a missing one.
- It installs no package and contacts no registry: a package that is declared but not installed is reported, with the command that installs it.
- It runs none of your code and no package code.
If a file changes while oel check is reading the project, it reports that rather than check a mix of old and new files. Run it again once your edits are saved.
Diagnostics
Each problem is reported with its file, line and column, a message and, where it helps, the other places involved, such as the earlier declaration of a duplicate name. With --json, each diagnostic follows the published diagnostic schema. Diagnostics describes both forms.
When any problem is found, oel check ends with a failure status, so an automated build stops there.
Related
- Formatting source: formatting is separate from checking, and a formatted file may still fail a check.
- Reference maps: what references what, and what is unused.
- Files and roles and Functions and visibility: the rules the check applies.