69 lines
3.7 KiB
Markdown
69 lines
3.7 KiB
Markdown
# Elixir — Comprehensive Development Guide
|
|
|
|
## Quick Reference
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Current Version | **Elixir 1.19.5** (target for all new code) |
|
|
| Required OTP | **OTP 27+** (OTP 28 supported) |
|
|
| Phoenix Version | **1.8.5** (latest — requires `:formats` on controllers) |
|
|
| Cortex Status | Elixir **not yet installed** on cortex.hydrascale.net |
|
|
| AI Agent Tooling | `usage_rules` hex package (~> 1.2) — **always include** |
|
|
| Production Framework | **Ash Framework** for substantial projects |
|
|
| Agent Framework | **Jido** (~> 2.1) for multi-agent systems |
|
|
| Paradigm | Functional, concurrent, fault-tolerant on BEAM VM |
|
|
|
|
---
|
|
|
|
## CRITICAL RULES — Read First
|
|
|
|
1. **Target Elixir 1.19.5** — not 1.15, not 1.17. Use current idioms and features.
|
|
2. **Always add `usage_rules`** to every project: `{:usage_rules, "~> 1.1", only: [:dev]}`.
|
|
3. **Use Ash Framework** for production/substantial projects (not necessarily POCs).
|
|
4. **Cortex is Elixir-first** — Elixir is the primary orchestrator, with interop to Python/Rust/Zig.
|
|
5. **Never use deprecated patterns** from pre-1.16 code (see Part 1).
|
|
6. **Phoenix 1.8** — always specify `:formats` on controllers, use `~p` verified routes, use scopes.
|
|
7. **For agentic workflows** — consider `GenStateMachine` over GenServer (built-in timeouts, state enter, postpone). For multi-agent orchestration, use **Jido**.
|
|
|
|
---
|
|
|
|
## Guide Structure — Load What You Need
|
|
|
|
This guide is split into focused parts. Load the part relevant to your current task:
|
|
|
|
### Part 1: Core Language & OTP (`elixir-part1-core.md`)
|
|
Elixir 1.19 features, type system, breaking changes since 1.15, pattern matching, pipelines, with expressions, structs, protocols, behaviours, Mix project structure, testing.
|
|
|
|
### Part 2: Concurrency & OTP (`elixir-part2-concurrency.md`)
|
|
BEAM processes, message passing, GenServer, Supervisors, DynamicSupervisor, Task, GenStateMachine (state machines for agentic workflows), Registry, ETS.
|
|
|
|
### Part 3: Phoenix Framework (`elixir-part3-phoenix.md`)
|
|
Phoenix 1.8.5 — router/pipelines, verified routes, controllers, HEEx components, LiveView, Channels, contexts, Ecto, authentication, scopes, telemetry, security, testing, generators, deployment.
|
|
|
|
### Part 4: Ecosystem & Production (`elixir-part4-ecosystem.md`)
|
|
Ash Framework, Jido (multi-agent systems), usage_rules, OTP releases, Docker deployment, distributed Erlang, monitoring (PromEx/Prometheus/Grafana), CI/CD, interop (Python/Rust/Zig), common libraries, cortex deployment plan, anti-patterns.
|
|
|
|
---
|
|
|
|
## Common Libraries Quick Reference
|
|
|
|
| Library | Purpose | Hex |
|
|
|---------|---------|-----|
|
|
| Phoenix | Web framework + LiveView | `{:phoenix, "~> 1.8"}` |
|
|
| Ecto | Database wrapper + query DSL | `{:ecto_sql, "~> 3.12"}` |
|
|
| Ash | Declarative resource framework | `{:ash, "~> 3.0"}` |
|
|
| Jido | Multi-agent orchestration | `{:jido, "~> 2.1"}` |
|
|
| GenStateMachine | State machines (wraps gen_statem) | `{:gen_state_machine, "~> 3.0"}` |
|
|
| Oban | Background job processing | `{:oban, "~> 2.18"}` |
|
|
| Req | HTTP client (modern) | `{:req, "~> 0.5"}` |
|
|
| Jason | JSON encoding/decoding | `{:jason, "~> 1.4"}` |
|
|
| Swoosh | Email sending | `{:swoosh, "~> 1.16"}` |
|
|
| Mox | Mock behaviours for testing | `{:mox, "~> 1.1", only: :test}` |
|
|
| Credo | Static analysis / linting | `{:credo, "~> 1.7", only: [:dev, :test]}` |
|
|
| libcluster | Automatic BEAM node clustering | `{:libcluster, "~> 3.4"}` |
|
|
| Horde | Distributed supervisor/registry | `{:horde, "~> 0.9"}` |
|
|
| Nx | Numerical computing / tensors | `{:nx, "~> 0.9"}` |
|
|
| Broadway | Data ingestion pipelines | `{:broadway, "~> 1.1"}` |
|
|
| PromEx | Prometheus metrics for Elixir | `{:prom_ex, "~> 1.9"}` |
|
|
| usage_rules | AI agent docs from deps | `{:usage_rules, "~> 1.1", only: :dev}` |
|