Browse the documentation

Early preview

A first program

This walk-through creates a project in the Open Engineering Language, writes a program that prints a number, adds a helper function, and then checks, runs and builds the program.

The project

One command creates a ready-to-build project:

oel init hello

oel init creates a folder named hello with three files at its root. It never overwrites files that already exist.

hello/
  main.oel        # the program's entry point
  pack.oel        # the packages the project uses; none at first
  metadata.oel    # the project's name and settings

metadata.oel records the name you gave and the source profile of the project:

# metadata.oel
metadata {
    schema = 1;
    name = "hello";
    source_profile = "oel-source/1";
}

pack.oel starts with no packages. It stays in the project even when it is empty:

# pack.oel
pack {
    schema = 1;
    dependencies = [];
}

A project name is an identifier: letters, digits and _, not starting with a digit, not a keyword, not main, and at most 64 characters.

The entry point

Every program starts in main.oel, which declares exactly one main, followed by the name in metadata.oel:

# main.oel
main hello() {
    print(42);
}

The name after main is the application's: it must equal name in metadata.oel, and an entry named main is refused. A main without a result type returns nothing, and the program exits successfully when main finishes. A comment starts with # and runs to the end of the line.

A helper function

A function declared with fn is a helper function. It is private to the file that declares it and that file's extension files: no other file can call it. Here is main.oel again with a helper added:

# main.oel, with a helper function
main hello() {
    let price: i64 = 1200;
    let total: i64 = with_tax(price);
    print(total);
}

fn with_tax(amount: i64) -> i64 {
    return amount + amount / 5;
}
  • let binds a name to a value; here each binding writes its type after the name. A binding does not change unless it is declared with let mut.
  • i64 is a 64-bit signed integer. Integers have fixed widths, and the language never converts between them silently.
  • Arithmetic is checked: if amount + amount / 5 overflows, the program reports the overflow, never silently ignores it.

To share a function between files, you write it as a global or a reusable function in a file of its own. Project layout describes both.

Checking and running

From inside the hello folder, you check and run the program:

oel check
oel run

oel check checks the whole project without running anything. Its diagnostics point at the exact place in your source, and oel check --json reports them in a machine-readable form.

oel run checks, builds and runs the program in one step.

Building

To build the program without running it, choose a target:

oel build --target <target>

<target> names what the program runs on: an operating system and processor, or a microcontroller board. Supported targets lists the exact targets. The program takes the application's name: this build writes hello beside main.oel, and -o writes it elsewhere, as in oel build --target <target> -o build/hello.

For a desktop or server target, the result is 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. Desktop and server programs written in the language alone need nothing else installed. Building a program describes every build option.

Formatting

oel fmt formats every source file the same way, and oel fmt --check lists the files it would change without changing them:

oel fmt

Next