How do I declare package capabilities in EK9?

← Package Capability Security · Ref: Q1271

The 'capabilities' declaration sits inside the 'defines package' block alongside 'version', 'license', and the other package properties. Each entry is a fully-qualified gated type name using the 'org.ek9.lang::' module path.

COMPACT SINGLE-LINE FORM

  capabilities <- ["org.ek9.lang::Stdout"]

MULTI-LINE FORM (for multiple entries)

  capabilities <- [
    "org.ek9.lang::Stdout",
    "org.ek9.lang::File",
    "org.ek9.lang::EnvVars"
    ]

BOTH FORMS COMPILE IDENTICALLY. Use the compact form for a single capability, the multi-line form for readability when you have several.

THE FULL EXAMPLE

  defines module my.publishable.library

    defines package
      publicAccess <- true
      version <- 1.0.0-0
      description <- "My library"
      license <- "MIT"
      capabilities <- ["org.ek9.lang::Stdout"]

    defines function
      sayHello()
        stdout <- Stdout()
        stdout.println("hello")

IMPORTANT RULES

1. Capabilities list entries MUST be non-empty. EK9 list literals do not accept '[]'. If you want a pure-computation library, omit the 'capabilities' block entirely — see Q1276.
2. Each gated type used in your non-dev source must be covered. The full gated type list appears in Q1273.
3. Grouped types count as one capability. Declaring 'org.ek9.lang::TCP' covers TCPConnection, TCPHandler, and NetworkProperties automatically.
4. Dev code (files under dev/) is exempt — see Q1278.

See Q1270 for the four-condition publishable rule. See Q1273 for the full gated types list. See Q1277 for what error E12010 means.

Example

defines module qa.packagecapabilities.declaresyntax

  defines package
    version <- 1.0.0-0
    description <- "Shows a publishable package declaring Stdout capability"
    license <- "MIT"
    publicAccess <- true
    capabilities <- ["org.ek9.lang::Stdout"]

  defines function

    sayHello()
      stdout <- Stdout()
      stdout.println("Hello from a publishable library")

Common mistakes

E12010 — The module uses Stdout but the capabilities list declares TCP. TCP does not cover Stdout — they are independent gated types in different groups. Declare 'org.ek9.lang::Stdout' to match the actual gated type the code references. See ek9 -h E12010.

Incorrect:

    capabilities <- ["org.ek9.lang::TCP"]

Correct:

    capabilities <- ["org.ek9.lang::Stdout"]

Other ways to ask this

Show me the syntax for declaring capabilities in a defines package block.
Where do I put the capabilities list for a publishable package?
How do I tell the compiler my package uses Stdout or File?
What does a working capabilities declaration look like?

Coming from another language?

Maven pom.xml: no capability concept. npm package.json: 'scripts' can run arbitrary code with no declared surface. Cargo.toml: no capability model. pyproject.toml: no enforcement. EK9: declarative 'capabilities <- [...]' list in 'defines package' is the single source of truth, enforced by the compiler at the module boundary.

Keywords: package, org.ek9.lang, syntax, declare, gated type, capabilities