Skip to main content
Markdown

Install and Update

The Exaloop distribution packages the Codon compiler, CLI, native tools, and SDKs as a compatible set. Install it from the platform-specific archive supplied by Exaloop, then verify the installation before creating your first project. The archive includes the installation tools, so setup requires neither network access nor a separate Python installation.

Prerequisites: the tarball and SHA-256 checksum supplied by Exaloop for your platform. Database servers and Kafka brokers are installed separately.

Choose the archive for your development machine:

TargetMinimum host
darwin-arm64Apple Silicon, macOS 14, Apple Command Line Tools
linux-x86_64x86-64 Linux with glibc 2.39, such as Ubuntu 24.04
linux-aarch64AArch64 Linux with glibc 2.39, such as Ubuntu 24.04

Each archive includes all eight SDKs: Data, DuckDB, PostgreSQL, MySQL, Redis, Kafka, optimizer, and profiling. The CLI and code generators are ready to use; you do not need to install Python or register SDKs separately. On macOS, install Apple's command-line tools first with xcode-select --install.

Database servers and Kafka brokers are separate. When building a server extension, check the database compatibility requirements against the server where you will deploy it.

First Installation​

Set ARCHIVE to the absolute path of your tarball and SHA256 to the checksum supplied with it. The values below are placeholders:

Terminal
ARCHIVE="$HOME/Downloads/exaloop-RELEASE-PLATFORM.tar.gz"
SHA256="CHECKSUM_SUPPLIED_BY_EXALOOP"

Verify the archive before extracting or running its contents. On macOS:

macOS
printf '%s  %s\n' "$SHA256" "$ARCHIVE" | shasum -a 256 --check -

On Linux:

Linux
printf '%s  %s\n' "$SHA256" "$ARCHIVE" | sha256sum --check -

A successful check prints the archive name followed by OK. A mismatch means the archive or checksum is incorrect; installation should stop at this point.

After verification, extract the tarball to a temporary directory and run its bundled installer:

Terminal
UNPACK=$(mktemp -d)
tar -xzf "$ARCHIVE" -C "$UNPACK"
"$UNPACK"/exaloop-*/bin/exaloop --no-project distribution install \
	--archive "$ARCHIVE" --sha256 "$SHA256"
export PATH="$HOME/.exaloop/bin:$PATH"
exaloop distribution verify
exaloop doctor --json

The installer verifies the archive again, installs a managed copy, and activates it. The temporary extraction directory is no longer needed afterward. Adding the PATH setting to your shell configuration makes exaloop available in new terminals. macOS binaries are ad-hoc signed, not notarized.

Use and Updates​

Check the installed SDKs:

Terminal
exaloop plugin list

Then follow the quickstart to create and build a project. The CLI guide covers builds, code generation, and SDK management.

Installations live under ~/.exaloop/releases/; EXALOOP_HOME selects another location. Each release contains a compatible compiler and SDK set. Replacing individual components can introduce binary incompatibilities even when version numbers appear to match.

Choose an installation path without spaces: PGO and profiling builds do not support spaces in this path.

To update, use the new tarball and checksum supplied by Exaloop. Set ARCHIVE and SHA256 to those values, then install through the existing CLI:

Terminal
exaloop --no-project distribution install --archive "$ARCHIVE" --sha256 "$SHA256"

To return to the previously active release:

Terminal
exaloop distribution rollback

Or activate a specific installed release using its tag and platform:

Terminal
exaloop distribution activate RELEASE_TAG-PLATFORM

If verification fails, your active release stays unchanged. Previous releases remain installed, allowing rollback without downloading another archive. A stale .install-lock after an interrupted installation can be removed once no installer is running.

Project Lock​

Pin a project to the active distribution so that subsequent builds use the same compiler and SDKs:

Terminal
exaloop distribution lock

lock records the active release, platform, and manifest digest in exaloop.lock. Builds fail if a different distribution is active. To activate the release recorded in an existing project lock:

Terminal
exaloop distribution sync

Install that release first if it is missing; sync only activates an installed, verified release. Each lock describes one platform, so use separate locks for different target platforms. Use --no-project for commands that should ignore the project configuration.

Runtime-Only Packages​

From a project with a configured app target, collect the executable and its native libraries:

Terminal
exaloop --target app package --bundle-runtime
exaloop --target app package --bundle-runtime --runtime-library /absolute/path/libextra.so

The package contains your application, its non-system native libraries, integrity hashes, and license inventory. Move the complete directory, including lib/, to the destination. The development compiler and Python interpreter are not included.

Use --runtime-library for additional libraries your code loads dynamically. Supply application data, credentials, external services, and any Python interoperability environment separately. Configure TLS certificates for the destination: the package does not include a CA bundle or make the build machine's certificate paths portable.

Without --bundle-runtime, package includes only the build artifacts. The destination must meet the package's OS, libc, and database compatibility requirements. For server extensions, review the registration SQL and deployment instructions for your database installation; an extension still needs its host database to run.

Next Steps​