Getting Started #

This guide walks you through installing SafeC, compiling your first program, and understanding the basic compilation workflow.

Installation #

Run the install script. It downloads a prebuilt safec/safeguard/sc-lsp release from GitHub Releases and configures your shell environment — there is nothing to build. It does need clang 21 or newer on the machine (SafeC hands its LLVM IR to clang to compile and link, and clang imports C headers); Install says how to get one per platform.

curl -fsSL https://raw.githubusercontent.com/safec-org/SafeC/main/install.sh | bash

irm https://raw.githubusercontent.com/safec-org/SafeC/main/install.ps1 | iex

Install Script Options #

install.ps1 takes the same as -Prefix, -Version, -Std and -SkipEnv.

Published binaries: macOS arm64, Linux x86_64, Windows x86_64. See Releases for the full asset list. They need:

• macOS 11 (Big Sur) or newer: the binaries and the prebuilt std are built for 11.0.
• Linux with glibc 2.25 or newer (Debian 10, Ubuntu 18.04, RHEL 8 and later): the binaries are built against an older glibc and checked for it, and the prebuilt std calls nothing newer than 2.25 (getrandom). Musl-based distributions (Alpine) aren't supported by the release binaries.

Verify the install:

safec --version       # safec 1.0.0-beta-7
safeguard --version   # safeguard 1.0.0-beta-7

Your First Program #

Create a new project with safeguard:

safeguard new hello
cd hello

This generates the following structure:

hello/
  .gitignore
  Package.toml
  src/
    main.sc

Replace src/main.sc with:

extern int printf(const char* fmt, ...);

int main() {
    printf("Hello from SafeC!\n");
    return 0;
}

Build and run:

safeguard build
safeguard run

Output:

Hello from SafeC!

A More Complete Example #

This example demonstrates regions, references, arrays, and slices:

extern int printf(const char* fmt, ...);

int main() {
    // Stack variable with explicit region reference
    int x = 42;
    &stack int ref = &x;
    printf("x = %d\n", *ref);

    // Array with bounds checking
    int arr[5];
    arr[0] = 10;
    arr[1] = 20;
    arr[2] = 30;

    // Slice — a bounds-checked view into the array
    []int s = arr[0..3];
    printf("slice length = %ld\n", s.len);

    return 0;
}

Compilation Pipeline #

The SafeC compiler processes source files through a multi-stage pipeline:

Source (.sc)
    |
    v
Preprocessor     #define, #include, #ifdef, -D/-I flags
    |
    v
Lexer            Tokenization
    |
    v
Parser           Recursive-descent parsing -> AST
    |
    v
Sema             Type checking, region analysis, borrow checking
    |
    v
ConstEval        Compile-time function evaluation, static_assert
    |
    v
CodeGen          LLVM IR generation
    |
    v
LLVM IR (.ll)    Text IR or bitcode output
    |
    v
clang/lld        Link to native binary

Compiler Flags #

safec <input.sc> [input2.sc ...] [options]

Every flag safec accepts is below (safec --help also lists LLVM's own options, which SafeC doesn't need).

Output #

Optimization and Linking #

Targets #

Debug and Diagnostics #

Compilation Control #

Preprocessor #

Incremental Compilation #

Incremental compilation (per-file .bc caching) is on by default — no flag needed to enable it.

Documentation #

What safeguard doc runs to read a package's declarations:

Information #

These need no input file:

C Header Import #

SafeC can natively include C standard headers. The compiler parses C header declarations and makes them available without manual extern stubs:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main() {
    ?&char msg = malloc(64);               // raw void* -> ?&char: implicit
    match (msg) {
        case some(m): {
            strcpy(m, "Hello from C headers!");
            printf("%s\n", m);
        }
        case null: { }
    }
    free(msg);
    return 0;
}

The automatic import works by invoking clang -ast-dump=json on the included header and extracting function and typedef declarations. Disable it with --no-import-c-headers if you prefer manual extern declarations.

Using the Package Manager #

For projects with dependencies or multiple source files, use safeguard. The install script installs it alongside safec and sc-lsp, so it's already available.

# Create a new project
safeguard new myproject
cd myproject

# Build and run
safeguard build
safeguard run

The project structure created by safeguard new:

myproject/
  .gitignore
  Package.toml       # Project manifest
  src/
    main.sc          # Entry point

The install script already sets SAFEC_HOME (to the install prefix, ~/safec by default) and adds it to PATH so safeguard can locate the compiler and standard library automatically — restart your shell, or source your shell rc file, after installing. If you skipped that step (--skip-env) or moved the install elsewhere, set it manually:

export SAFEC_HOME=/path/to/safec
export PATH="$SAFEC_HOME/bin:$PATH"

Linking #

SafeC compiles to LLVM IR. safec --emit-bin -o hello links it in one step through clang (Linking), and safeguard links a project for you; by hand, the final linking step uses your system's C toolchain:

# Basic linking
clang hello.ll -o hello

# With pthreads (for spawn/join)
clang concurrency.ll -lpthread -o concurrency

# With math library
clang math_demo.ll -lm -o math_demo

Editor Support #

An LSP server is available for .sc files, providing:

• Diagnostics (error highlighting)
• Hover information
• Code completion
• Go-to-definition
• Document symbols

The server is sc-lsp, which the install script puts on your PATH; Tools has the VS Code, Neovim and Emacs setups (the VS Code extension is in the editors/vscode/ directory of the sc-language-server repository).

Next Steps #

• Design Philosophy — Understand why SafeC makes the choices it does
• Types — Learn about SafeC's type system
• Memory and Regions — Understand region-based memory safety