Core Concepts

A few ideas explain everything cargo-athena does.

1. Templates are types

Each #[workflow] / #[container] lowers to a Rust type. Referencing that type from another module or crate pulls its definition into the build; emitting your entrypoint includes every template it reaches, and nothing it doesn’t.

There is no registry to keep in sync. Workflows compose across modules and crates through normal Rust name resolution.

2. #[workflow] is a statically analyzed DAG

A workflow body is read, not executed. Each let x = t(args); or t(args); becomes a step; data flow becomes the DAG edges.

Because the body is read, it is also type-checked as ordinary Rust. Wrong types, wrong arity, missing fields, or calling a non-template are compile errors. Only the lowered shapes (let / call statements, if / else) are accepted; anything else is a spanned compile_error!. Full details on the #[workflow] page.

3. #[container] runs real Rust in a pod

A container body really does execute inside its pod. Arguments come in as inputs; the return value goes out as the step’s output. I/O is serde-bound at compile time, so take and return owned types (String, not &str).

Arguments can also be spliced into the pod spec: writing image = "repo:" + tag injects an argument into the image (and likewise into service_account, node_selector, env, and the mutex name / namespace). See #[container] Parameter injection.

4. #[fragment] carries pod resources

A fragment is a normal helper that runs as real Rust code in the calling container’s pod. It can take arguments and return values like any function. Its only superpower: every host! mount, S3 artifact port, or secret! env it declares is also added to each container that transitively calls it.

Share setup logic, mounts, and secrets across containers without a registry.

5. Your workflow binary runs in two worlds

The binary your workflow crate compiles to plays two roles:

• On your machine, cargo athena emit / publish / submit walks the template closure from your entrypoint and prints one WorkflowTemplate per template.
• In Argo, that same binary deserializes the step’s inputs, calls the matching #[container] body, and serializes the return.

cargo athena publish cross-compiles it static-musl and uploads it; emit adds it to every container template; a tiny sh bootstrap picks the matching architecture and runs the right function. The image needs only sh and uname.

With these in mind, the reference pages are the details: #[workflow], #[container], the CLI, and athena.toml.