Skip to main content
Markdown

Your First Native Application

Build a native application that writes and reads a Parquet file. This tutorial covers project creation, SDK selection, and executable builds using a small, self-contained dataset. You will need the Exaloop CLI, its matching Codon compiler, and the Data SDK; no external services are required.

Before you begin: install the all-SDK distribution. It includes the CLI and automatically registers the Data SDK used here.

Use an existing Codon installation

Set up individual SDKs and the CLI, then register the Data SDK once using its installed path:

Terminal
exaloop plugin add data --path /path/to/sdk/data

1. Check the Toolchain​

Terminal
exaloop doctor
exaloop plugin list

Confirm that the selected compiler is the one you intend to use and that data is available. If a check fails, resolve it with troubleshooting before continuing.

2. Create and Run a Project​

Choose a new directory; init does not overwrite existing project files:

Terminal
exaloop init analytics-demo
exaloop --project analytics-demo --target app run

The starter prints Hello from Codon. It contains app.codon and an exaloop.toml manifest with a named native target. --project selects the directory; --target app selects what to build and run.

3. Add a Data SDK Example​

Replace analytics-demo/app.codon with:

app.codon
import exaloop.data as data

with data.table({"value": data.array([2.5, 4.0, 6.5])}) as table:
    table.write("values.parquet")

with data.read_parquet("values.parquet") as table:
    values = table["value"].to_numpy(float)

assert values.sum() == 13.0
print("Parquet round trip passed")

Update analytics-demo/exaloop.toml to select the Data SDK:

exaloop.toml
[targets.app]
kind = "native"
source = "app.codon"
plugins = ["data"]
codon_args = ["-release"]

Run the target again:

Terminal
exaloop --project analytics-demo --target app run

Expected output:

Output
Parquet round trip passed

It also writes analytics-demo/values.parquet. Target commands run from the project directory, so relative file paths are resolved there. The NumPy array returned by to_numpy owns its data and remains usable after the table closes.

4. Build an Executable​

Terminal
exaloop --project analytics-demo --target app build

The executable is analytics-demo/dist/app/app. It does not need the CLI or a Python interpreter to run, but it still needs its Codon, Data SDK, and transitive native libraries. Before moving it to another machine, read about runtime packages and host requirements.

Next Steps​

  • Tables and files: schemas, NULLs, conversions, and ownership.
  • CLI and projects: multiple targets, tests, and packaging.
  • Profiling: inspect a representative application's runtime costs.
  • PGO: improve a build using separate training and evaluation inputs.

For profiling and PGO, use a longer-running program with representative inputs so that startup time does not dominate the measurements.