Salam Programming Language¶

Salam is a general-purpose and systems programming language designed for efficient software development, featuring a built-in domain-specific language (DSL)

---

• ✨ Introducing Salam

  • Supported Languages

  • Why Choose Salam?

  • Key Features

• 🧩 Editor Support

  • Visual Studio Code

• 🛠️ The Compiler (salam)

  • Build

  • Usage

  • Cross-compilation

• 🐳 Docker & Docker Compose

  • Development (live reload)

  • Production (copy & build)

  • Plain Docker (without Compose)

  • Books (XeLaTeX)

• 🚀 Bun Workspaces: Multi-App Development & Static Site Guide

  • 🚀 1. Quickstart Execution Guide

  • 📁 2. Monorepo Architecture & Core Setup

    • Root Configuration Files

      • package.json (Workspace Root)

      • bunfig.toml (Workspace Root)

  • 🛠️ 3. Static Site Package Implementation

    • Static Site Configuration

  • ⚡ 4. The Serve Methods Evaluated

    • Method A: Bun Native Dev Engine (bun run --watch index.html)

    • Method B: The Local Isolation Method (bunx vite)

  • 🔄 5. Global Monorepo Package Updates

    • Explaining the Flags Behind the Script (bun update -i -r)

  • 🔒 6. Security Breakdown & Best Practices

    • The Port Selection Architecture

    • Network Address Binding (0.0.0.0 vs 127.0.0.1)

    • Safe Command Formula

  • 📚 7. MyST Documentation

    • Configuration Files

    • Running the Documentation Locally

• 🤝 Contributing

• 🔍 Joining Code Reviews

  • How a GitHub PR Review Works

    • Leaving an inline comment

    • Suggesting a code change

    • Submitting the review

    • Tips for great reviews

  • Growing with the Community

  • 💬 Real-Time Community

• 📖 Glossary

Salam Language, inspired by the word salam (سلام), meaning peace, is engineered for exceptional efficiency, reliability, and modern software development. Designed from the ground up to balance low-level control with developer productivity, Salam eliminates the unnecessary syntactic friction often found in systems engineering. By prioritizing a clean, scannable, and intuitive architecture, it lowers the cognitive barrier to entry, fostering an accessible and inclusive environment for building high-performance software.

Supported Languages¶

• English: Fully supported and ready for use.

• Persian (فارسی): Fully supported and ready for use.

• Arabic (العربية): Currently under development. We need contributions from native Arabic speakers to complete support.

Why Choose Salam?¶

• 🌍 Localized for Persian and Arabic Speakers: Write and read code in your native language.

• 🧑‍🎓 Beginner-Friendly: Salam makes programming approachable for everyone, including students and new developers.

• 💻 Powerful Tools: Easy to use, but with robust capabilities for all your coding needs.

Key Features¶

• ✏️ Intuitive scripting and code compilation.

• 🚀 Docker support for seamless development.

• 🔧 Linting and code checks for best practices.

• 🔄 Built-in commands for versioning and updates.

🧩 Editor Support¶

Visual Studio Code¶

Install the official Salam Language extension from the Visual Studio Code Marketplace for syntax highlighting and language support.

🛠️ The Compiler (salam)¶

Salam is statically typed and compiled. The general language transpiles to C and is built to a native executable; embedded layout: blocks compile to HTML/CSS/JS.

Build¶

Requires a C compiler. tcc is the default backend (bundled math, fast); gcc/clang also work.

The compiler lives in compiler/ (a self-contained subproject: src/, std/, tests/, tools/, Makefile, CMakeLists.txt). Build it from there:

cd compiler
sh tools/bash/build-compiler.sh   # quick build with tcc  ->  ./salam
# or, with CMake (out-of-tree build, then run the test suite via ctest):
cmake -B build && cmake --build build && ctest --test-dir build
# or just: make            # (release build via the Makefile -> ../salam at the repo root)

There is no separate runtime library: salam build emits the small C runtime (print/strcat/pow/alloc and optional bounds checks) inline into the generated C, so compiled programs are self-contained and link only -lm (-lmsvcrt with tcc).

Usage¶

# general language -> native executable
salam build app.salam --output=app.exe         # then ./app.exe
salam cli build app.salam --keep-c             # optional 'cli' prefix; keep generated C
salam obj app.salam                            # compile to .o only

# layout DSL -> website
salam layout build page.salam                  # page.html + page.css + page.js
salam layout build page.salam --inline         # one self-contained page.html
salam layout build a.salam b.salam             # per-page html + merged style.css/script.js

# inspect any stage (general or layout)
salam app.salam --emit-tokens-xml | --emit-ast-xml | --emit-symbol-xml
salam app.salam --log-level=trace
salam build app.salam -DDEBUG                  # preprocessor define

# format source in place (auto-detects nothing - pass --lang=fa for Persian files)
salam fmt app.salam                            # reformat one file
salam fmt                                      # reformat every .salam under the cwd, recursively
salam fmt compiler/src/ examples/              # reformat given files and/or directories
salam fmt --check                              # report files that need formatting (exit 1 if any)
salam fmt app.salam --tabs                     # indent with tabs (convert spaces to tabs)
salam fmt compiler/src/ --indent=2             # indent with 2 spaces per level
salam fmt page.salam --lang=fa                 # Persian source

# REPLs
salam cli       # general
salam layout    # layout

Hello, World:

func main {
    println("Hello, World!")
}

Cross-compilation¶

Salam can produce executables and object files for other operating systems and architectures using the LLVM backend. Pass a full LLVM target triple with --target=<triple> to build or obj; when it is present the compiler routes through LLVM (clang/llc) instead of the default C backend, so --cc and --keep-c no longer apply. The output name follows the target’s conventions (.exe for Windows, .obj for MSVC objects, none for ELF), and --output overrides it as usual.

# Windows executable from Linux (MinGW target)
salam build main.salam --target=x86_64-w64-windows-gnu --output=app.exe

# WebAssembly (WASI)
salam build main.salam --target=wasm32-wasi --output=app.wasm

# a target-specific object file
salam obj main.salam --target=x86_64-pc-windows-msvc      # -> main.obj

The target is fully wired through the pipeline: the OS/arch predefined macros (SALAM_OS_WINDOWS, SALAM_ARCH_X64, …) describe the target, so @if SALAM_OS_WINDOWS selects the right branch, and link "..." directives are passed to the cross-linker (e.g. link "user32" → -luser32).

Prerequisites. Cross-compilation drives the LLVM toolchain, so you need a recent clang/llc (v22 is what the toolchain invokes) plus, for Windows targets, the LLVM linker lld and a sysroot (the target’s CRT, system import libraries, and headers):

sudo apt install clang lld llvm        # toolchain (or an official LLVM release)

Bundled sysroot (zero-setup for your users). Build the compiler with -DSALAM_BUNDLE_MINGW=ON and a MinGW-w64 sysroot is staged into <prefix>/share/salam/sysroots/<arch>-w64-mingw32/; salam build --target=…-windows-gnu then discovers and passes it automatically, so end users need nothing extra:

# copy an existing sysroot (e.g. from the mingw-w64 package)
cmake -B build -DSALAM_BUNDLE_MINGW=ON \
      -DSALAM_MINGW_SYSROOT=/usr/x86_64-w64-mingw32
# or download one (pin the hash for reproducibility)
cmake -B build -DSALAM_BUNDLE_MINGW=ON \
      -DSALAM_MINGW_URL=<llvm-mingw archive> -DSALAM_MINGW_SHA256=<hash>
cmake --build build && cmake --install build

Point $SALAM_SYSROOTS at a directory holding per-target sysroot subdirectories to override or add targets without rebuilding. Automatic discovery names them by toolchain, not by the raw triple: <arch>-w64-mingw32/ for *-windows-gnu (e.g. x86_64-w64-mingw32/) and <arch>-linux-musl/ for *-linux-musl (e.g. x86_64-linux-musl/).

MSVC / macOS targets. Automatic sysroot discovery currently handles only MinGW (*-windows-gnu) and musl (*-linux-musl). Microsoft’s and Apple’s SDKs are not redistributable and aren’t auto-discovered, so for *-windows-msvc and *-apple-darwin you must supply a toolchain/sysroot yourself (e.g. xwin for MSVC) and drive clang manually via salam llvm until first-class selection for those targets lands. On Linux, prefer the -windows-gnu (MinGW) triple.

The LLVM backend supports a growing subset of the language; cross-compilation works for self-contained programs and their imports within that subset. Host-native builds without --target continue to use the fast C backend (tcc/gcc/clang) and the full standard library.

🐳 Docker & Docker Compose¶

The compiler ships a multi-stage Dockerfile and a docker-compose.yml built on Alpine Linux (musl, the lightest practical base). The build context is the compiler root (compiler/). The image includes everything the compiler needs: a C compiler (gcc + tcc), the LLVM 22 backend (clang-22, llc-22, opt-22, lli-22), and make, no CMake required.

The compose file lives in compiler/docker/; pass it with -f so you can run from the repository root. There are two modes:

Development (live reload)¶

The compiler tree is bind-mounted and ./salam is recompiled automatically on every change to src/ (powered by entr, see tools/bash/docker-dev.sh):

docker compose -f compiler/docker/docker-compose.yml up dev   # build, then watch & rebuild

Edit any file under compiler/src/ on your host and the container rebuilds ./salam incrementally. To get a shell inside the same environment:

docker compose -f compiler/docker/docker-compose.yml run --rm dev sh

Production (copy & build)¶

The production stage runs COPY . then make && make install, baking a fully built, self-contained compiler into the image. salam is the entrypoint, and the repository root is mounted at /work so shared examples/ are reachable:

docker compose -f compiler/docker/docker-compose.yml build prod
docker compose -f compiler/docker/docker-compose.yml run --rm prod build examples/en/basics/hello.salam --output=hello
docker compose -f compiler/docker/docker-compose.yml run --rm prod layout build page.salam --inline
docker compose -f compiler/docker/docker-compose.yml run --rm prod --help

Plain Docker (without Compose)¶

Build with compiler/ as the context (so the Dockerfile’s COPY . picks up the compiler tree):

docker build --target prod -f compiler/docker/Dockerfile -t salam:prod compiler   # production image
docker run --rm -v "$PWD":/work salam:prod build app.salam --output=app

docker build --target dev  -f compiler/docker/Dockerfile -t salam:dev  compiler   # dev image
docker run --rm -it -v "$PWD/compiler":/app salam:dev                             # live-rebuild loop

The LLVM and Alpine versions are configurable build args (--build-arg LLVM_VERSION=22, --build-arg ALPINE_VERSION=edge). LLVM 22 currently lives in Alpine’s edge repositories, which is why edge is the default base.

Books (XeLaTeX)¶

The tutorial books have their own image under books/docker/ so you can typeset them without installing a local TeX distribution. One common XeLaTeX image builds both languages: it is based on the full TeX Live scheme, which already bundles xepersian (for the heavier right-to-left Persian book), polyglossia + tcolorbox (for the lighter English book) and Latin Modern. The books/ tree is bind-mounted, so the generated PDFs are written back to the host at books/<lang>/intro-programming/book.pdf:

docker compose -f books/docker/docker-compose.yml run --rm books        # both
docker compose -f books/docker/docker-compose.yml run --rm books en     # English only
docker compose -f books/docker/docker-compose.yml run --rm books fa     # Persian only

Or with plain Docker (build once, then run against the mounted books/ tree):

docker build -t salam-books books/docker
docker run --rm -v "$PWD/books":/books salam-books all

🚀 Bun Workspaces: Multi-App Development & Static Site Guide¶

🚀 1. Quickstart Execution Guide¶

To kick off your entire localized monorepo environment simultaneously, run the following steps from your root directory.

• Install workspace links and cached instances:

bun install

• Boot up all servers concurrently on high ports:

bun run dev:all

Your terminal window will display interleaved logs, cleanly prefixed by their respective package origins:

Salam % bun run dev:all
$ bun run --filter='*' --parallel dev
@workspace/pages:dev         |
@workspace/pages:dev         |   VITE v8.1.3  ready in 61 ms
@workspace/pages:dev         |
@workspace/pages:dev         |   ➜  Local:   http://127.0.0.1:55002/
@workspace/editor:dev        |
@workspace/editor:dev        |   VITE v8.1.3  ready in 65 ms
@workspace/editor:dev        |
@workspace/editor:dev        |   ➜  Local:   http://127.0.0.1:55001/
@workspace/vercel-editor:dev |
@workspace/vercel-editor:dev |   VITE v8.1.3  ready in 91 ms
@workspace/vercel-editor:dev |
@workspace/vercel-editor:dev |   ➜  Local:   http://localhost:5173/
@workspace/vercel-editor:dev |   ➜  Network: use --host to expose
@workspace/runner:dev        |
@workspace/runner:dev        |  ⛅️ wrangler 4.107.0
@workspace/runner:dev        | ────────────────────
@workspace/runner:dev        | ⎔ Starting local server...
@workspace/runner:dev        | [wrangler:info] Ready on http://localhost:8787
@workspace/runner:dev        | [wrangler:info] GET / 200 OK (7ms)

📁 2. Monorepo Architecture & Core Setup¶

To configure the workspace, structure your repository directory tree alphabetically as follows:

salam-monorepo/
├── bunfig.toml
├── package.json
├── editor/
├── extensions/
│   └── vscode/
├── pages/
├── runner/
└── vercel-editor/

Root Configuration Files¶

package.json (Workspace Root)¶

This file defines the workspaces in strict alphabetical order and leverages Bun’s parallel filtering mechanics. It also centralizes shared dependency versions via Bun’s workspace catalog and exposes root scripts for local development, builds, Wrangler type generation, and dependency updates.

{
  "name": "salam-monorepo",
  "private": true,
  "workspaces": {
    "packages": [
      "editor",
      "extensions/vscode",
      "pages",
      "runner",
      "vercel-editor"
    ],
    "catalog": {
      "react": "^19.2.7",
      "react-dom": "^19.2.7",
      "tailwindcss": "^4.3.2",
      "@tailwindcss/vite": "^4.3.2",
      "@vitejs/plugin-react": "^6.0.3",
      "vite": "^8.1.3",
      "typescript": "^6.0.3",
      "wrangler": "^4.107.0",
      "@types/bun": "latest",
      "@types/node": "^26.1.0",
      "@types/react": "^19.2.17",
      "@types/react-dom": "^19.2.3"
    }
  },
  "scripts": {
    "dev:all": "bun run --filter='*' --parallel --if-present dev",
    "dev:editor": "bun run --filter='@workspace/editor' dev",
    "docs:myst": "bun run myst start",
    "dev:pages": "bun run --filter='@workspace/pages' dev",
    "dev:runner": "bun run --filter='@workspace/runner' dev",
    "dev:vercel": "bun run --filter='@workspace/vercel-editor' dev",
    "build:all": "bun run --filter='*' --if-present build",
    "build:myst": "bun run myst build --html",
    "build:vercel": "bun run --filter='@workspace/vercel-editor' build",
    "update:deps": "bun update -i -r",
    "clean": "rm -rf node_modules **/node_modules .bun-cache",
    "generate": "bun run --filter='@workspace/runner' generate",
    "typecheck": "bun run --filter='@workspace/runner' typecheck"
  },
  "devDependencies": {
    "@tailwindcss/vite": "catalog:",
    "@vitejs/plugin-react": "catalog:",
    "mystmd": "^1.10.1",
    "vite": "catalog:"
  }
}

Useful root commands:

• bun run dev:all: start every workspace that exposes a dev script

• bun run dev:editor, bun run dev:pages, bun run dev:runner, and bun run dev:vercel: start one workspace at a time

• bun run build:all: run every workspace build script that exists

• bun run build:vercel: build the React/Vite app in vercel-editor/

• bun run docs:myst: start the MyST documentation dev server

• bun run build:myst: build the MyST documentation to static HTML (_build/html/)

• bun run generate: refresh Cloudflare Wrangler types for runner/

• bun run typecheck: regenerate Wrangler types and run the runner/ TypeScript check

• bun run update:deps: interactively update dependencies across the workspace

bunfig.toml (Workspace Root)¶

Forces Bun to persistently treat execution environments with development-first behaviors.

[development]
development = true

🛠️ 3. Static Site Package Implementation¶

The independent workspace utilizes your specific package scope (@workspace/pages). It is set to "private": true to protect against accidental package publishing to the public npm registry.

Static Site Configuration¶

pages/package.json

{
  "name": "@workspace/pages",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "bunx vite --port 55002 --host 127.0.0.1"
  }
}

⚡ 4. The Serve Methods Evaluated¶

Depending on your asset compilation pipelines, you can run and serve your static file assets via two distinct command-line approaches.

Method A: Bun Native Dev Engine (bun run --watch index.html)¶

Bun acts as a full-stack compiler. It looks for runtime entry points, hooks a watcher loop, and injects code straight into the runtime.

PORT=55002 bun run --watch index.html

• 🟥 The Critical Crash Bug: If an HTML file links a <script src="./app.js"> tag and app.js is missing, deleted, or generated out-of-order by another builder script, Bun’s dependency engine throws a fatal compilation or segmentation panic and crashes your entire root dev terminal.

Method B: The Local Isolation Method (bunx vite)¶

Bypasses complex multi-environment integrations entirely by mounting a dedicated Vite development context over the directory.

bunx vite --port 55002 --host 127.0.0.1

• 🟩 The Fix: Missing scripts or components safely emit standard frontend browser 404 Not Found messages instead of breaking your backend engine processes.

🔄 5. Global Monorepo Package Updates¶

To manage and upgrade your external dependencies across all application subdirectories together without navigating into individual package folders, trigger your custom root shortcut:

bun run update:deps

Explaining the Flags Behind the Script (bun update -i -r)¶

• -i (--interactive): Spawns an interactive Terminal User Interface (TUI) mapping out all out-of-date assets. Use your Arrow keys and spacebar to selectively pick packages to upgrade, or toggle l to force a package beyond its defined SemVer range to its absolute --latest release.

• -r (--recursive): Forces Bun’s resolution engine to sweep across all items listed under your workspaces field (editor, pages, runner, etc.) instead of executing purely inside the main directory.

When initialized, Bun appends a Workspace column to your terminal output grid so you can verify exactly where every target module upgrade is bound before writing the changes to disk.

🔒 6. Security Breakdown & Best Practices¶

When operating servers on your host machine, observe these boundaries:

The Port Selection Architecture¶

Network ports scale from 1 to 65535.

• 1 – 1023: System-privileged root ports. Avoid using these.

• 1024 – 49151: Registered user application ports (e.g., 8080, 3000). High risk of overlapping with other applications.

• 49152 – 65535: Dynamic, Private, and High Ports. Ideal for setting up workspace dev contexts cleanly.

Network Address Binding (0.0.0.0 vs 127.0.0.1)¶

• 0.0.0.0 (All Interfaces): Default configuration for most servers. If you are on an open public Wi-Fi network (like a cafe), anyone on that network can read your unreleased static code by querying your local IP address.

• 127.0.0.1 (Loopback Localhost): Hardware-restricted isolation. Only your exact physical computer can access the ports. Highly recommended for untrusted networks.

Safe Command Formula¶

To enforce instant browser updates, skip disk caches, isolate network eavesdroppers, and bypass compiler engine crashes, use this script formula:

bunx vite --port 55002 --host 127.0.0.1

📚 7. MyST Documentation¶

The repository ships a MyST (Markedly Structured Text) docs site powered by mystmd. Source content comes from books/ (TeX book files) and .md files across the repository.

Configuration Files¶

• myst.yml - MyST project config (site template, repository link, and custom style file).

• .readthedocs.yaml - Read the Docs build config used to host the generated documentation.

• _build/ - generated static output directory from myst build --html (including _build/html/), ignored by git in .gitignore.

Running the Documentation Locally¶

# Install workspace dependencies (includes mystmd)
bun install

# Start the live-reload docs server
bun run docs:myst

# Build the static HTML output to _build/html/
bun run build:myst

The dev server (myst start) watches books/ and .md files across the repository and rebuilds on changes. Read the Docs uses .readthedocs.yaml to autobuild and deploy the site.

🤝 Contributing¶

We welcome contributions from the community!

• 📖 Read our Contributing Guide.

• 🌟 Follow our Code of Conduct.

Together, let’s make coding accessible to all.

🔍 Joining Code Reviews¶

Everyone is welcome, and encouraged, to participate in code reviews. You do not need to be a core maintainer to review a pull request. In fact, reviewing PRs is one of the most impactful ways to contribute to Salam, and we want to make it as approachable as possible.

💡 Code review is harder than writing code. Reading someone else’s work, understanding their intent, spotting edge cases, and communicating feedback kindly and clearly takes real skill. If you are doing it, thank you; it matters enormously.

How a GitHub PR Review Works¶

Open any pull request, then click the Files changed tab to see a diff of every file that was modified.

Leaving an inline comment¶

1. Hover over any line number in the diff; a blue + button appears.

2. Click it to open a comment box for that specific line or block.

3. Write your thought, then click Start a review (not “Add single comment”) so all your notes are batched together.

Suggesting a code change¶

Inside an inline comment you can propose an exact replacement using a fenced suggestion block:

```suggestion
your replacement code here
```

The author can accept your suggestion with a single click, no manual editing required.

Submitting the review¶

When you have finished reading all the files:

1. Click the green Review changes button (top right of the diff).

2. Write an overall summary comment.

3. Choose one of three outcomes:

   • 💬 Comment - share thoughts without formally approving or blocking. Great for questions, first-timer feedback, or discussion starters.

   • ✅ Approve - you are satisfied with the changes. This is the green tick that moves a PR toward merging. Only approve if you have read the changes carefully.

   • 🚫 Request changes - something needs to be fixed before the PR can merge. Be specific and constructive.

4. Click Submit review.

Tips for great reviews¶

• A simple comment is perfectly fine. If you are new to reviewing, just leaving a thoughtful question or noting something you learned is genuinely valuable. You don’t have to approve or block.

• Be kind and specific. Point to the exact line, explain why something may be a concern, and suggest an alternative when you can.

• Assume good intent. The author put effort into this. Phrase feedback as questions (“Could this be…?”) rather than commands (“Change this to…”).

• First-timer PRs deserve extra warmth. If a contributor’s bio or commit history shows they are new, a short encouraging note goes a long way.

• Approve when you mean it. The green checkmark signals trust. Reserve it for changes you have genuinely read and feel confident about.

Growing with the Community¶

Consistent reviewers and contributors are noticed. Active participation in reviews, issues, and discussions is how community members become trusted collaborators. Over time, standout contributors may be invited to join the Salam core team and take on additional responsibilities:

• 🏷️ Triage role - help label, categorise, and prioritise incoming issues and pull requests.

• 🛡️ Discord / Telegram moderator - help keep real-time channels welcoming and on-topic.

• 🔑 Maintainer access - merge PRs, manage releases, and help shape the roadmap.

💬 Real-Time Community¶

The Salam core team lives in our real-time channels. Join us to ask questions, share ideas, discuss reviews in progress, or just say hello:

These spaces are open to everyone, from curious newcomers to experienced systems programmers. The more voices the better.

📖 Glossary¶

Terms used across this readme, the Contributing Guide, and the editor readme.

© 2024-2026 Salam Language Team