Module guide

The Swarm codebase has gotten large enough to be quite intimidating at first glance (currently, as of May 2024, 28K SLOC across 224 modules). This page contains a (work-in-progress) guide to help orient developers to the codebase.

To help with organization and enforce modularity, the codebase is first broken into a number of sublibraries, listed below. Click on a sublibrary to jump to the section outlining its contents.

• swarm-util: miscellaneous utilities
• swarm-lang: parsing, typechecking, etc. for the Swarm language
• swarm-scenario: scenario descriptions, parsing, & processing
• swarm-engine: game simulation
• swarm-doc: generating documentation
• swarm-tui: textual user interface
• swarm-web: web interface

swarm-util

The swarm-util sublibrary contains various miscellaneous utilities which are used throughout the Swarm codebase.

• Control.Carrier.Accum.FixedStrict: this is a vendored version of Control.Carrier.Accum.Strict from the fused-effects library that works around a bug.
• Data.BoolExpr.Simplify: some additional functionality on top of the boolexpr library.
• Swarm.Util: a collection of useful generic functions which are not specific to Swarm but not found elsewhere.
• Swarm.Util.*: various more specialized utilities.

swarm-lang

The swarm-lang library contains definitions and tools for working with the Swarm programming language.

• Syntax
  • Types
  • Direction
  • Swarm.Language.Syntax
• Parsing
  • Parser
  • Parser.*
  • Key
• Checking
  • Context
  • Module
  • Capability
  • Requirement
  • Typed
  • Typecheck
  • Swarm.Effect.Unify
    • Swarm.Effect.Unify: definition of a unification effect and some operations it supports.
    • Swarm.Effect.Unify.Common: common definitions (mostly re: substitution) used in implementations of unification.
    • Swarm.Effect.Unify.Naive: a slow-but-obviously-correct implementation of unification.
    • Swarm.Effect.Unify.Fast: a faster implementation of unification.
• Elaborate
• Pipeline
• Pretty
• Value
• Swarm.Language.LSP

swarm-scenario

swarm-engine

swarm-doc

swarm-tui

swarm-web