Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Jazz is a functional programming language inspired by Elixir and Haskell, designed to provide a strong, static type system without the complexity of category theory-oriented abstractions like monads or semigroupoids. The project currently focuses on core expression subsets, type inference, and immutable bindings, with an active development path targeting a modern compiler implementation.
Sources: README.md:1-15, README.md:18-24
Project Architecture and Workspace
The Jazz repository is organized into distinct implementation tiers. Developers must distinguish between the active compiler target and historical reference implementations to ensure contributions align with the project's roadmap.
Workspace Policy
The project strictly enforces a workspace policy where new functionality is localized to specific directories:
| Path | Status | Purpose |
|---|---|---|
jazz-next/ | Active | The only target for new compiler implementation work, including parser, analyzer, and codegen changes. |
jazz2/ | Legacy | Reference-only design source and experimental code; non-normative for current behavior. |
jazz-hs/ | Legacy | Historical reference code; read-only. |
Sources: AGENTS.md:3-13, jazz-next/README.md:3-10, README.md:33-36
Active Compiler Components (jazz-next)
The active development in jazz-next is divided into logical compiler stages:
This diagram represents the data flow from surface syntax parsing to the driver within the jazz-next implementation.
Sources: jazz-next/README.md:12-25
Environment Setup and Dependencies
Jazz is implemented in Haskell and utilizes several specialized libraries for parsing, diagnostics, and testing.
Core Dependencies
The project relies on the following key Haskell packages:
- Parsing:
megaparsec,parser-combinators - Diagnostics:
diagnose - CLI/UI:
haskeline,prettyprinter,prettyprinter-ansi-terminal - Testing:
tasty,tasty-hunit,tasty-hspec,hspec - Compiler Helpers:
llvm-hs-pure(historical),qbe(active/planned),lens,bifunctors
Sources: jazz2/package.yaml:22-50, jazz-hs/package.yaml:22-47
Tooling Requirements
- GHC/Stack: The project uses Stack for builds. The current resolver is
lts-22.19(GHC 9.6.x). - Node.js: Used by the legacy
jazz-hsexecution script to run generated JavaScript code. - Scripts: Various Bash scripts are provided for linting, documentation checks, and test execution.
Sources: jazz2/stack.yaml:21-23, jazz-hs/run.sh:1-9, jazz-next/scripts/test-warning-config.sh:1-5
Language Basics
Syntax and Purity
Jazz functions are pure by default. Impure functions (side-effecting) must be explicitly denoted with a ! suffix. Pure functions are prohibited from calling impure ones directly.
// Pure function
isEven = \(i) -> mod(i, 2) == 0.
// Impure function (denoted by !)
greet! = \(name) -> {
println! "Hello, ${name}".
}.
Sources: README.md:92-120
Function Application and Currying
Functions support partial application and are curried by default. The $ operator is used as a right-associative, zero-precedence application operator to reduce parenthesis nesting.
add10 = (+10).
nums = [1, 2, 3, 4, 5].
print! $ map add10 nums.
Sources: README.md:57-75
Testing and Verification
Development in jazz-next includes a comprehensive test suite covering configuration, diagnostics, and language semantics.
Running Tests
Tests are executed via the provided test runner script located in the repository root or the implementation directory.
# Execute all warning and configuration tests
bash jazz-next/scripts/test-warning-config.sh
Sources: jazz-next/README.md:38-43
Test Categories
| Category | Source Directory | Focus |
|---|---|---|
| Parser | test/JazzNext/Compiler/Parser/ | Lambda parsing, if-expressions, and operator fixity. |
| Semantics | test/JazzNext/Compiler/Semantics/ | Rebinding warnings, type inference, and purity enforcement. |
| Modules | test/JazzNext/Compiler/Modules/ | Prelude loading and module resolution. |
| Tooling | test/JazzNext/Compiler/Config/ | Warning flag parsing and CLI behavior. |
Sources: jazz-next/README.md:27-36, jazz-next/scripts/test-warning-config.sh:12-38
Summary
To get started with Jazz development, clone the repository and focus implementation efforts on the jazz-next/ directory. Ensure that all language changes are accompanied by updates to the documentation in docs/spec/* and corresponding tests in jazz-next/test/. Use the provided Shell scripts to verify that code meets the project's diagnostic and authority policies.
Sources: README.md:31-42, AGENTS.md:5-13