Installation

This page covers the three things you need before building a component: a per-language toolchain, the edgecommons scaffolding CLI, and the library dependency wired into your project. The CLI normally wires the dependency for you when it scaffolds a component — the manual declarations below are for adding EdgeCommons to a project by hand.

Toolchain prerequisites

EdgeCommons is one SDK in four languages. You only need the toolchain for the language you build in.

Java

Java 25 (LTS) and Maven. The published SDK artifact is built for Java 25, so a JDK 25 is required even though a generated component compiles its own bytecode to level 11.

java -version    # expect 25.x
mvn -version     # any recent Maven 3.x

Note

Run a component that uses the streaming subsystem with --enable-native-access=ALL-UNNAMED (the Java FFM / Panama binding to the native edgestreamlog core).

Python

Python 3.9 or newer for components.

python3 --version    # expect 3.9 or newer

Note

The edgecommons CLI itself runs on Python 3.8+, but scaffolded Python components target 3.9+.

Rust

A Rust toolchain installed via rustup, plus cargo.

rustc --version    # 1.85 or newer recommended
cargo --version

Note

The library crate is edition 2024 / MSRV 1.85; a scaffolded component crate is edition 2021 / MSRV 1.85. A current stable toolchain satisfies both. Building the on-device greengrass feature additionally needs a C toolchain and libclang and is Linux/WSL only.

TypeScript

Node.js 18 or newer and npm.

node --version    # expect v18 or newer
npm --version

Beyond the language toolchain, you will want git, a local MQTT broker for HOST-platform testing, and — for packaging/deploying to Greengrass — the GDK (Greengrass Development Kit).

Install the scaffolding CLI

edgecommons is a single static binary. Build and install it from the cli/ workspace of the monorepo:

Linux

cargo install --path cli/crates/ec-cli    # installs `edgecommons` onto your PATH

Windows

cargo install --path cli/crates/ec-cli    # installs `edgecommons` onto your PATH

Building the CLI needs a rustup toolchain; running it needs nothing else. The component templates and the canonical config schema live inside the binary, so the CLI scaffolds and validates offline. Scaffolding a Java or TypeScript component needs nothing but the binary — the language toolchain is what builds the result, not what generates it.

Verify your environment

edgecommons doctor checks the external tools the platforms you target need, reports the version of each, and exits non-zero when a required tool is missing. Narrow it with --platforms and -l/--language so it only checks what your workflow actually uses.

Linux

edgecommons doctor                          # everything, for all three platforms
edgecommons doctor --platforms HOST -l RUST # just what a Rust component on HOST needs

Windows

edgecommons doctor                          # everything, for all three platforms
edgecommons doctor --platforms HOST -l RUST # just what a Rust component on HOST needs

Add the library to a project

When you scaffold with edgecommons component new, the dependency is written for you. The --dep-source flag chooses between three forms:

• local (the default) — a path/file dependency on a monorepo checkout of the library. Best for developing against the SDK in this repo, and it needs no registry access.
• registry — the published artifact, resolved from GitHub Packages or a git tag.
• pinned-rev (Rust and Python only) — a git dependency pinned to the exact library commit the CLI was built from (--library-rev overrides it), plus a gitignored .cargo/config.toml local-dev override for Rust. This is the recommended choice once a component leaves the monorepo as its own repository: the pin cannot lag the facades the embedded templates call the way a registry tag can. Maven and npm cannot express a git dependency on a subdirectory of the monorepo, so Java and TypeScript reject it.

Note

--dep-source and --library-path shape the Python, Rust, and TypeScript dependency — the three whose declaration is a path or a git reference. With local, the path defaults to the monorepo the CLI was built from, so the common case needs no flag.

Java always declares the Maven coordinate com.mbreissi.edgecommons:edgecommons at the library version, so you pick local-vs-registry by where that artifact resolves from (your ~/.m2 cache vs GitHub Packages), not by a flag. pinned-rev is not available for Java (or TypeScript).

The declarations below show what each form looks like if you are adding EdgeCommons to an existing project by hand. edgecommons component new substitutes the library version the CLI was built against.

Java

Coordinate com.mbreissi.edgecommons:edgecommons. Add the dependency to your pom.xml:

<dependency>
  <groupId>com.mbreissi.edgecommons</groupId>
  <artifactId>edgecommons</artifactId>
  <version>0.2.0</version>
</dependency>

Registry — resolve from GitHub Packages by adding the repository and authenticating in ~/.m2/settings.xml with a <server> whose <id> is github and a GitHub token that has the read:packages scope:

<repositories>
  <repository>
    <id>github</id>
    <url>https://maven.pkg.github.com/edgecommons/edgecommons</url>
  </repository>
</repositories>

Local — build the library from the monorepo and install it to your local Maven cache, then the same coordinate resolves from ~/.m2 with no repository configured:

cd libs/java && mvn clean install

Python

Package edgecommons. The dependency form is chosen by --dep-source; in requirements.txt:

# local: an editable install of the monorepo checkout
-e ../libs/python

# registry: the published artifact via a git tag
edgecommons @ git+https://github.com/edgecommons/edgecommons@python-lib/v0.2.0#subdirectory=libs/python

# pinned-rev: the exact commit the CLI was built from (or --library-rev)
edgecommons @ git+https://github.com/edgecommons/edgecommons@<rev>#subdirectory=libs/python

Install with:

pip install -r requirements.txt

Rust

Crate edgecommons. The dependency form is chosen by --dep-source; in Cargo.toml:

[dependencies]
# local (dev default): a path dependency on the monorepo checkout
edgecommons = { path = "/abs/path/to/libs/rust", default-features = false }

# registry: the published artifact via a git tag
# edgecommons = { git = "https://github.com/edgecommons/edgecommons", tag = "rust-lib/v0.2.0", default-features = false }

# pinned-rev: the exact commit the CLI was built from (or --library-rev)
# edgecommons = { git = "https://github.com/edgecommons/edgecommons", rev = "<rev>", default-features = false }

For the local form, the CLI fills the path from --library-path (defaulting to the in-repo libs/rust). Off-by-default cargo features (greengrass, cloudwatch, streaming, credentials, parameters, …) are composed on top as your component needs them.

The pinned-rev form also gets a gitignored .cargo/config.toml next to Cargo.toml, patching the pinned dependency to a local sibling checkout so cargo build still resolves locally on your machine while Cargo.toml keeps the committed pin for CI:

# .cargo/config.toml — LOCAL DEV ONLY, gitignored
[patch."https://github.com/edgecommons/edgecommons"]
edgecommons = { path = "/abs/path/to/libs/rust" }

[net]
git-fetch-with-cli = true

TypeScript

Package @edgecommons/edgecommons (note the scope — it is not a bare edgecommons). The dependency form is chosen by --dep-source; in package.json:

{
  "dependencies": {
    "@edgecommons/edgecommons": "file:/abs/path/to/libs/ts"
  }
}

For the local form above, the value is file:<path> (the CLI fills it from --library-path, defaulting to the in-repo libs/ts). Install local path deps with npm install --install-links so the package is copied rather than symlinked.

Registry — use a semver range and resolve the @edgecommons scope from GitHub Packages. The CLI emits an .npmrc (only for --dep-source registry) and authenticates from the NODE_AUTH_TOKEN environment variable (a GitHub token with read:packages):

{
  "dependencies": {
    "@edgecommons/edgecommons": "^0.2.0"
  }
}

.npmrc

@edgecommons:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Next steps

QuickstartScaffold, build, and run your first component against a local MQTT broker.