Documentation pages
SultanC Documentation
This is the documentation for SultanC, a self-hosted systems programming language whose keywords exist in Arabic and English as two surfaces of the same syntax. The pages are grouped by purpose: the guide teaches the language, the reference specifies it, the internals describe how the compiler works, and the contributing pages explain how to change it.
The README gives a short overview of the project and its build routes.
Guide
| Page | What it covers |
|---|---|
| Getting started | Building the compiler, the first program, compiling, running and checking |
| Language tour | The language by example: types, functions, control flow, records, enums, pattern matching, ownership, errors and modules |
Reference
| Page | What it covers |
|---|---|
| Type system | Built-in and structural types, type identity, generics, numeric casts and wrapping arithmetic |
| Ownership and destruction | Moves, borrows, copies, drop glue, temporaries, vector capacity and the allocator |
| Errors | Results, propagation with ?, panic, std.error, runtime failures and localized messages |
| Diagnostics | What the compiler prints: terminal layout, JSON schema, public codes, suggestions and fixes |
| Compile-time evaluation | comptime, declaration annotations and compile-time assertions |
| Modules and imports | Import forms, packages and module identity |
| Concurrency | Threads, atomics, Arc, Mutex, RwLock, Condvar, Once, channels and the capture check |
| Formatting | std.fmt: format strings, arguments, custom formatters and the compile-time check |
| Testing | sultanc test: @@test functions, each run in its own process, filters, other targets and exit statuses |
| Source formatter | sultanc fmt and the formatter library: the canonical layout, what it keeps, editor integration |
| Standard library coverage | What std provides, module by module, compared with Rust and Go |
| Targets | Supported operating systems and architectures, and which backend serves each |
| Platform dependencies | Every system function std imports, and what std implements itself |
| Arabic terminology | The canonical Arabic vocabulary of the language, std and diagnostics |
Internals
| Page | What it covers |
|---|---|
| Compiler architecture | The pipeline from source to executable and the layout of compiler/ |
| MSIR and code generation | The verified intermediate representation, the native and LLVM backends, and the linkers |
| Safety flow | How moves, borrows, lifetimes and escapes are checked |
| Interpreter | sultanc run: execution model, memory model and host calls |
| Jisr | The C frontend behind import "x.h" and import "x.c": pipeline, owners, declarations, compiled C, limits |
| Bootstrap | The C Stage0, the WebAssembly seed, the build routes and how CI proves each one |
| TLS and cryptography | The TLS 1.3 implementation in std and its cryptographic primitives |
| iSpeak | The message layer behind every diagnostic, in Arabic and English, and its context contracts |
| Diagnostics compared | SultanC diagnostics against rustc, Clang, GCC and Swift: what exists and what is still needed |
Contributing
| Page | What it covers |
|---|---|
| Contributor guide | Repository layout, development builds, the rules for compiler sources and documentation style |
| Tests | Running the test suite, test directives and adding tests |
| Examples | The example programs and how they are organized |
History
These pages are records of past decisions and migrations. They describe the project as it was when they were written; the guide, reference and internals describe it as it is.
| Page | What it records |
|---|---|
| Byte character literals | A language proposal that has not been adopted |
| iSpeak history | How the message layer was introduced |
| iSpeak reason audit | A review of every contextual-reason key |
| Embedded runtime retirement | Moving the compiler's embedded runtime into std |
| OS migration inventory | Moving the operating-system layer into std |
Keeping the documentation current
The implementation is authoritative. When a change alters a contract described here, update the page in the same change rather than adding a separate status note. Style and conventions are in the contributor guide.