Package Structure

Package structure in Riot is not a matter of style preference. It is part of how the toolchain understands the workspace.

That means layout affects:

• build planning
• binary discovery
• test discovery
• documentation generation
• how easy a package is to navigate

The basic expectation

A Riot package should have a shape that makes its role obvious.

At a high level that means:

• metadata at the package root
• source files under src/
• tests, examples, and benchmarks where Riot expects them
• generated artifacts outside source directories

The exact files vary by package, but the principle does not: structure should be predictable.

Why predictable structure matters

Predictability buys a lot:

• the toolchain can do more automatically
• new contributors learn one package faster
• docs examples transfer from one package to another
• editors and scripts need fewer exceptions

The more a workspace drifts into custom shapes, the more every command and document has to explain those exceptions.

A useful way to think about it

Good package structure should make it easy to answer:

• where does the public interface live?
• where does executable entrypoint code live?
• where do tests live?
• where would generated docs come from?

If those answers are fuzzy, the package is probably harder to use than it needs to be.