145 lines
5.6 KiB
Markdown
145 lines
5.6 KiB
Markdown
# El Language — Agent Guide
|
||
|
||
El is a self-hosting, statically-typed language that compiles to C. This file orients agents that work on El itself or on programs written in El.
|
||
|
||
---
|
||
|
||
## What El Is
|
||
|
||
El compiles `.el` source → C → native binary. Every El value is `el_val_t` (int64_t). Strings are heap pointers cast through int64_t. The compiler is written in El (self-hosting).
|
||
|
||
**The compiler pipeline:**
|
||
```
|
||
elc-cli.el
|
||
└─ imports: compiler.el
|
||
└─ imports: lexer.el, parser.el, codegen.el, codegen-js.el
|
||
```
|
||
|
||
The canonical compiler binary is `dist/platform/elc`. It was produced by running an earlier version of itself on `elc-cli.el`.
|
||
|
||
---
|
||
|
||
## The Two Layers — Know Which One You're In
|
||
|
||
### Layer 1: El programs (`.el` files)
|
||
|
||
This is where almost all work belongs. El programs are source files that get compiled by `elc`. New library functions, application logic, and language-level utilities all go here as `.el` files.
|
||
|
||
**Do not add C code when El can express it.** If functionality can be built from existing El primitives (string ops, `exec`, `fs_read/write`, `http_post`, etc.), write it in El.
|
||
|
||
### Layer 2: The C seed (`el-compiler/runtime/el_seed.c`)
|
||
|
||
This is the self-contained C OS-boundary layer. It provides the `__`-prefixed primitives that compiled El programs call: libcurl HTTP, pthreads, filesystem I/O, arena allocation, etc. It is **not generated** — it is maintained by hand.
|
||
|
||
The old `el_runtime.c` has been archived to `el-compiler/runtime/legacy/`. The runtime is now native El (`runtime/*.el`). `el_seed.c` replaces `el_runtime.c` as the sole C compilation dependency.
|
||
|
||
**Only edit `el_seed.c` when you genuinely need OS-level access** (raw sockets, GPU calls, new libcurl features). For everything else, write El.
|
||
|
||
When you do add a C builtin:
|
||
1. Add the C function to `el_seed.c`
|
||
2. Declare it in `el_seed.h`
|
||
3. Add it to the `builtin_arity` table in `el-compiler/src/codegen.el` (so the compiler knows the arg count)
|
||
4. Rebuild the elc binary (see below)
|
||
|
||
---
|
||
|
||
## Rebuilding the Compiler
|
||
|
||
After changing any `.el` source in `el-compiler/src/`:
|
||
|
||
```bash
|
||
cd /Users/will/Development/neuron-technologies/foundation/el
|
||
./dist/platform/elc elc-cli.el > elc-new.c
|
||
cc -std=c11 -I el-compiler/runtime -lcurl -lpthread \
|
||
-o dist/platform/elc-new \
|
||
elc-new.c el-compiler/runtime/el_seed.c
|
||
# Verify self-hosting:
|
||
./dist/platform/elc-new elc-cli.el > elc-verify.c
|
||
diff elc-new.c elc-verify.c # should be identical
|
||
mv dist/platform/elc-new dist/platform/elc
|
||
```
|
||
|
||
After changing `el_seed.c` only (no El source changes), rebuild downstream programs but do NOT need to rebuild the compiler binary itself — the seed is linked at the application level, not the compiler level.
|
||
|
||
---
|
||
|
||
## How El Programs Are Built
|
||
|
||
Each El application has a `build.sh` that:
|
||
1. Concatenates all `.el` source files (stripping `import` lines)
|
||
2. Runs `elc` to produce a `.c` file
|
||
3. Runs `cc` linking against `el_seed.c`
|
||
|
||
Example (cgi-studio daemon):
|
||
```bash
|
||
cd products/cgi-studio/el-daemon
|
||
./build.sh
|
||
```
|
||
|
||
When you add a new `.el` file to an application, add it to that application's `build.sh` concat list.
|
||
|
||
---
|
||
|
||
## Parallelism in El
|
||
|
||
El is single-threaded at the application level. Parallelism is achieved through subprocess fan-out:
|
||
|
||
```el
|
||
// Pattern: write payloads to temp files, exec bash script with & and wait,
|
||
// read results back from temp files.
|
||
fn http_post_parallel(urls: [String], bodies: [String]) -> [String] {
|
||
// ... bash fan-out via exec() ...
|
||
}
|
||
```
|
||
|
||
Use `exec()` (blocking) or `exec_bg()` (fire-and-forget) with shell scripts to run concurrent work. There is no goroutine or async/await — parallelism goes through the OS process layer.
|
||
|
||
---
|
||
|
||
## Key Files
|
||
|
||
| Path | What it is |
|
||
|------|-----------|
|
||
| `dist/platform/elc` | Canonical compiler binary (arm64 Mac) |
|
||
| `el-compiler/src/codegen.el` | Code generator — builtin arity table lives here |
|
||
| `el-compiler/src/lexer.el` | Lexer |
|
||
| `el-compiler/src/parser.el` | Parser |
|
||
| `el-compiler/runtime/el_seed.c` | Self-contained C OS-boundary layer (replaces el_runtime.c) |
|
||
| `el-compiler/runtime/el_seed.h` | Seed header (C function declarations) |
|
||
| `spec/language.md` | Language specification |
|
||
| `BOOTSTRAP.md` | How to recover the compiler from scratch |
|
||
| `elc-cli.el` | Compiler entry point |
|
||
| `elc-combined.el` | Pre-merged single-file compiler (used during early bootstrap) |
|
||
|
||
---
|
||
|
||
## HTTP Timeout
|
||
|
||
The El HTTP client (libcurl) defaults to **60 seconds**. Override per-process via `EL_HTTP_TIMEOUT_MS` env var. Set it before spawning any subprocess that makes long API calls:
|
||
|
||
```el
|
||
exec("EL_HTTP_TIMEOUT_MS=300000 " + SOME_BIN + " " + args + " 2>&1")
|
||
```
|
||
|
||
---
|
||
|
||
## Operator naming convention (for cognitive `.el` modules)
|
||
|
||
When you write `.el` that names a **cognitive faculty / operator** (the language
|
||
faculty, appreciation, interoception, the summon loop under `elp/`), name it for
|
||
its **functional human equivalent** — the faculty a mind would name — **not** its
|
||
linear-algebra operation. Put the math characterization in the `@impl`
|
||
doc-comment, never in the operator's public name (e.g. public `discern`/`contrast`
|
||
⟵ `@impl subtract (a−b)`; public `summon`/`recall` ⟵ `@impl LOCAL nearest-region
|
||
+ bounded spreading activation`). Full table + rationale in
|
||
`foundation/el/AGENTS.md` § *Operator naming convention*. This does **not** apply
|
||
to plain library/compiler code (a `sort` is a `sort`).
|
||
|
||
## Rules
|
||
|
||
- New library functions → write in El
|
||
- New OS/hardware primitives → write in C and register in `codegen.el` arity table
|
||
- Never edit `dist/platform/elc` directly — always rebuild from source
|
||
- Never modify `el_seed.c` to add functionality that El can express
|
||
- Cognitive-faculty `.el` → name for the mind, algebra in `@impl` (see above)
|