Verona, from source form to native boundary.

1 — Foundation

Two layers of compilation

Verona has two cooperating compilation layers. The first is a metaprogramming layer: macros run at compile time, receive and return S-expressions, and can inspect, construct, combine, or generate the syntax that the next layer will compile. The second is the top-level-form compiler: it expands those forms, collects declarations, resolves signatures, and type-checks executable bodies.

This separation is deliberate. In the metaprogramming layer, a program is data: lists, identifiers, strings, and quoted templates. A macro can build a function, a protocol implementation, or a sequence of definitions without turning those declarations into runtime values.

source
  → reader syntax
  → compile-time macro evaluation
  → expanded top-level forms
  → declaration collection and type checking
  → native artifact

2 — Language

Verona core language

Verona programs are written as S-expressions. Names are case-sensitive, and ; begins a line comment. String and character literals are ASCII-only; strings are immutable NUL-terminated byte pointers. Named control characters include #\tab, #\newline, #\vertical_tab, #\form_feed, and #\return. A char automatically widens where an integer is expected.

Values and types

(type point (product (x i32) (y i32)))
(type option (sum (none) (some i32)))

(function unwrap ((value option)) i32
  (match value
    ((none) 0)
    ((some number) number)))

Polymorphism

Declarations and reader features

#+darwin
(external-function mach-task-self
  "mach_task_self" () u32)

3 — Bundled package

Base library

The explicit base module provides surface declaration macros and the public protocol layer. Add base/src to a target’s module path, import it, and use its qualified forms.

Application programs should use operations exported by a module such as base, rather than compiler-internal %… primitives. Numeric type conversion is always explicit: use base:convert where a conversion is intended.

(import base)

(base:function total
  (for (a)
    ((base:numeric a)))
  ((left a) (right a))
  a
  (+ left right))

(base:function same
  (for (a)
    ((base:equality a)))
  ((left a) (right a))
  bool
  (= left right))

4 — Compile-time layer

Metaprogramming reference

Macros are compile-time programs that construct Verona syntax. A macro returns one expression form when used in executable code, or a sequence of top-level definitions when used at the top level. Source locations are retained by the compiler and restored after expansion.

The declarations in the explicit base module are imported macros, not built-in evaluator functions. compiler:definition and compiler:fold-left form the narrow compiler-facing bridge: the first constructs a compiler definition, and the second constructs a nested binary call tree.

Evaluator bindings

Quotes and templates

'FORM quotes an S-expression, `FORM quasiquotes a template, and ,FORM evaluates and inserts an S-expression inside that template.

(import base)

(base:macro generated-function (type)
  `(base:function ,(keyword-concat (keyword "generated-") ,type)
     () ,type 42))

5 — Native boundary

Native interoperability and LLVM

Verona lowers typed programs through LLVM to native artifacts. The LLVM layer implements Verona’s native-code pipeline; the language itself exposes a defined C ABI boundary for interoperating with existing native software.

Use external-function to import a C symbol and native-export to publish a compatible Verona function. Static and shared libraries receive a generated .h file beside the artifact.

(external-function strlen "strlen" ((pointer u8)) usize)

(function add ((left i32) (right i32)) i32
  (+ left right))

(native-export add "verona_add")

Variadic APIs and APIs that need exact C-layout callback storage require dedicated bindings before they can be called safely.

6 — Package setup

Configuring environment

Verona packages use two independent environment variables. VERONA_SOURCE_DIR identifies the absolute root directory containing Verona package sources. VERONA_LIBRARY_DIR identifies the absolute root directory containing installed Verona package artifacts.

export VERONA_SOURCE_DIR="$HOME/.local/src/verona"
export VERONA_LIBRARY_DIR="$HOME/.local/lib/verona"

These variables describe Verona package locations only. They do not configure C-library discovery; native libraries remain target-specific build inputs.

The bundled bootstrap tutorial checks both variables, explains any missing setup, and prints links to the Verona site and source repository. Run it from the repository root with make bootstrap.

7 — Build tools

Build and package tooling

verona --version
verona compile SOURCE [options]
verona build TARGET OUTPUT-DIRECTORY [--feature NAME]...

(executable app
  (root app.main)
  (module-path "src")
  (optimize 2)
  (library "sqlite3"))

Compile options

Executable arguments

An executable can receive the platform command line with a C-compatible entry declaration. argc includes the executable name; argv points to its NUL-terminated byte strings.

(function main ((argc i32) (argv (pointer (pointer u8)))) exit-code
  (let ((first-argument (pointer u8)
                        (deref (pointer-offset argv 1))))
    ; parse first-argument when argc is at least 2
    0))

verona.build clauses

A build file contains one or more executable, static-library, or shared-library declarations. Every target requires exactly one (root module.name) clause.