Peeper

Peeper is an experimental systems programming language and native compiler. This repository contains the compiler, bundled library, package tooling, language server, and executable source fixtures.

Peeper is pre-release software. Language, package, and compiler interfaces may change without compatibility guarantees. No stable binary release is currently published.

Current capabilities

• Static semantic analysis with explicit compiler phases.
• Ownership, move, borrow, pointer, and reference checks.
• Scalars, aggregates, arrays, slices, optionals, interfaces, and modules.
• HIR and MIR lowering to LLVM IR and native executables through Clang.
• Project manifests, dependency commands, source checking, and an LSP server.

See the open roadmap for unfinished language and runtime work.

Binary installation

Signed release candidates target Linux, macOS, and Windows on amd64 and arm64. Download matching peeper-installer-<os>-<arch> asset from a published release, verify it against SHA256SUMS, then run it. Windows assets use .exe.

Installer verifies signed release manifest, downloads compiler, native target, and managed LLVM packs, validates every size and SHA-256 digest, then activates complete installation atomically. It prints directory to add to PATH; it does not modify shell or registry configuration.

Installed distributions include Clang, linker, target runtime, and standard libraries. macOS cannot redistribute Apple SDK, so Command Line Tools and working xcrun --sdk macosx --show-sdk-path remain required. Run peeper doctor after installation.

See docs/distribution.md for support policy, release security, and maintainer setup.

Source build requirements

• Go version declared in go.mod.
• LLVM Clang available as clang for native build and run commands.
• Git for cloning the compiler and fetching packages.

Build from source

git clone https://github.com/PeeperLanguage/compiler.git
cd compiler
bash scripts/build.sh
build/bin/peeper -help

Bundling produces:

• compiler binary: build/bin/peeper
• bundled libraries: build/libs

Create a project

peeper init initializes the current directory:

mkdir hello-peeper
cd hello-peeper
/path/to/compiler/build/bin/peeper init hello-peeper
/path/to/compiler/build/bin/peeper run

Generated source starts with:

fn main() {
    println("Hello from Peeper!");
}

Commands

Command	Purpose
peeper build [path]	Compile a program to a native executable.
peeper run [path] [args]	Compile and run a program on the host target.
peeper check [path ...]	Check .peep files or directories without linking.
peeper init [name]	Initialize peeper.toml and src/main.peep.
peeper get [pkg ...]	Install manifest or named dependencies.
peeper update [pkg ...]	Update locked dependencies.
peeper sniff [pkg ...]	Preview available dependency updates.
peeper list	List direct and transitive dependencies.
peeper remove <alias>	Remove one dependency.
peeper cleanup	Remove orphaned cached dependencies.
peeper doctor	Validate installation, managed toolchain, and runtime.
peeper lsp	Start the language server over standard input/output.

Run peeper -help for the complete command list and current aliases.

Compiler pipeline

source
  -> tokens
  -> AST
  -> name and base-type semantics
  -> CFG
  -> flow typing and optional narrowing
  -> definite initialization
  -> ownership
  -> project-wide usage analysis
  -> HIR
  -> MIR
  -> LLVM IR
  -> native linker

Mandatory semantic checks finish before HIR optimization may remove source control flow. COMPILER_GUIDELINES.md explains these phase and representation boundaries.

仓库 layout

Path	Contents
cmd/	Compiler CLI entrypoint and commands.
internal/	Frontend, semantics, IR, LSP, pipeline, and backend packages.
pkg/	Reusable manifest, registry, and utility packages.
_builtin_library/	Compiler-bundled Peeper library sources.
x_test/	Positive, negative, and runtime source fixtures.
scripts/	Bundling and repository automation.

Development

go vet ./...
go test ./...
go test -race ./...
bash scripts/build.sh
PEEPER_BIN="$PWD/build/bin/peeper" go test -count=1 ./x_test

Read CONTRIBUTING.md before proposing a change. Compiler work must also follow RULES.md, go-style.md, and COMPILER_GUIDELINES.md.

安全 reports belong through the private process in SECURITY.md, not a public issue. Community participation follows CODE_OF_CONDUCT.md.

License

Peeper is licensed under the GNU General Public License v3.0.