sun::driver

namespace · Source (opens in a new tab)

Coordinates compilation, dependency loading, linking, and program execution.

Resolves project configuration without accessing dependency contents.

Downloads configured inputs and assembles distributable artifacts.

Coordinates compiler inputs, analysis, code generation, and execution.

Classes

sun::driver::Driver (public)
sun::driver::GitDependencyBuildScope (public)
sun::driver::ManifestProcessor (public)
sun::driver::SunJIT (public)

Structs

Functions

addSourceDigests

public · function · Source (opens in a new tab)

void sun::driver::addSourceDigests(BuildInputs &inputs, const std::vector< std::string > &sourceFiles, const std::vector< std::string > &protoFiles, const std::string &baseDir)

Add the digest of each source file, and of the Sun source generated from each proto schema, to inputs.

Adds source and protobuf content digests to the build inputs.

baseDir is the folder proto paths are relative to. Throws SunError when a file cannot be read.

Related: BuildInputs, SunError

appendOwnSourceBytes

public · function · static · Source (opens in a new tab)

static void sun::driver::appendOwnSourceBytes(const ExprAST &node, sun::serialization::ASTSerializer &serializer, std::string &out)

Appends the serialized form of every statement the program wrote itself to out.

Blocks are flattened and imported moon scopes are skipped. Each statement is prefixed with its length so neighbours cannot run together.

buildPackages

public · function · Source (opens in a new tab)

void sun::driver::buildPackages(const SunConfig &config, const std::vector< PackagePlan > &plans)

Stages and compresses complete packages, preserving valid unchanged outputs.

Related: SunConfig, PackagePlan

collectReachableFunctions

public · function · static · Source (opens in a new tab)

static void sun::driver::collectReachableFunctions(llvm::Function *func, std::set< llvm::Function * > &visited)

Helper: recursively collect all functions reachable from a given function.

compileFile

public · function · Source (opens in a new tab)

void sun::driver::compileFile(const std::string &filename, bool includeStdlib=false)

Compiles a source file, optionally loading the standard library.

compileFileWithStdlib

public · function · Source (opens in a new tab)

void sun::driver::compileFileWithStdlib(const std::string &filename)

Compile with stdlib preloaded.

compileFiles

public · function · Source (opens in a new tab)

void sun::driver::compileFiles(const std::vector< std::string > &sourceFiles, const std::vector< MoonImport > &moonImports={})

Compile multiple source files using the merged-AST model.

Related: MoonImport

compileString

public · function · Source (opens in a new tab)

void sun::driver::compileString(const std::string &source, bool includeStdlib=false)

Compiles source text, optionally loading the standard library.

compileStringWithStdlib

public · function · Source (opens in a new tab)

void sun::driver::compileStringWithStdlib(const std::string &source)

Compile with stdlib preloaded.

compileToExecutable

public · function · Source (opens in a new tab)

bool sun::driver::compileToExecutable(llvm::Module &module, const std::string &outputPath, std::string &errorMsg, bool keepObjectFile=false, const LinkOptions &linkOpts={}, bool optimize=true)

Compiles a standalone executable with the requested optimization setting.

Returns true on success, false on failure

Related: LinkOptions

computeFileDigest

public · function · Source (opens in a new tab)

std::string sun::driver::computeFileDigest(const std::string &path, const char *what)

Digest of a file's bytes, as lowercase hex.

Reads an input file and computes its content digest.

what names the file's role in the error ("source", "native archive"). Throws SunError when it cannot be read.

Related: SunError

computeInputHash

public · function · Source (opens in a new tab)

std::string sun::driver::computeInputHash(const BuildInputs &inputs)

The hash of inputs and of the running compiler, as lowercase hex.

Computes a digest covering the inputs and settings of a build.

Throws SunError when an imported bundle cannot be read.

Related: BuildInputs, SunError

computeOwnSourceHash

public · function · static · Source (opens in a new tab)

static std::string sun::driver::computeOwnSourceHash(const BlockExprAST &blockAst)

Returns a hash that identifies a program by its own statements.

Imported moon scopes are left out because they already carry their own identity.

Related: BlockExprAST

computeStaticInitOrder

public · function · static · Source (opens in a new tab)

static uint32_t sun::driver::computeStaticInitOrder(const std::vector< std::string > &importedModuleKeys, const std::vector< sun::moon_bundling::MoonImport > &moonImports)

Works out where the startup function of the code being compiled runs relative to those of the bundles it imports: zero when it imports nothing, otherwise one more than the highest value recorded by an import.

Lower values run first, so every import's globals are initialized before this code's startup function reads them.

Related: sun::moon_bundling::MoonImport

configTargetKey

public · function · Source (opens in a new tab)

std::string sun::driver::configTargetKey(const std::string &targetTriple)

Returns the canonical config target key, retaining architecture and ABI.

declaresStdlibString

public · function · static · Source (opens in a new tab)

static bool sun::driver::declaresStdlibString(const BlockExprAST &block)

Does this block declare class String directly inside module std?

Interpolation desugars to std.String and std.HeapAllocator, so the stdlib's own sources satisfy it without importing stdlib.moon — which they cannot do, being that library.

Related: BlockExprAST

effectiveLinkTriple

public · function · Source (opens in a new tab)

llvm::Triple sun::driver::effectiveLinkTriple(const std::string &targetTriple)

The triple a link is actually for: the explicit target, or the host.

embedBuildRecord

public · function · Source (opens in a new tab)

void sun::driver::embedBuildRecord(llvm::Module &module, const BuildRecord &record)

Add record to module so that it ends up in the object file, and in any executable linked from it.

Stores build provenance in the generated LLVM module.

Call once per module, just before emitting it.

Related: BuildRecord

emitObjectFile

public · function · Source (opens in a new tab)

bool sun::driver::emitObjectFile(llvm::Module &module, const std::string &outputPath, std::string &errorMsg, bool optimize=true)

Emits an object file with the requested backend optimization setting.

Returns true on success, false on failure

executeFiles

public · function · Source (opens in a new tab)

void sun::driver::executeFiles(const std::vector< std::string > &sourceFiles, const std::vector< MoonImport > &moonImports={})

Execute multiple source files using the merged-AST model.

Related: MoonImport

executeString

public · function · Source (opens in a new tab)

sun::driver::SunValue sun::driver::executeString(const std::string &source, int argc=0, char **argv=nullptr, bool includeStdlib=false)

Execute and log SunError to stderr, then rethrow.

executeStringWithReachableIR

public · function · Source (opens in a new tab)

sun::driver::SunValue sun::driver::executeStringWithReachableIR(const std::string &source, int argc=0, char **argv=nullptr, bool includeStdlib=false)

Execute and dump all reachable IR (includes stdlib functions).

Related: sun::driver::SunValue

executeStringWithStdlib

public · function · Source (opens in a new tab)

sun::driver::SunValue sun::driver::executeStringWithStdlib(const std::string &source, int argc=0, char **argv=nullptr)

Execute with stdlib preloaded.

Related: sun::driver::SunValue

executeTestsWithStdlib

public · function · Source (opens in a new tab)

sun::driver::SunValue sun::driver::executeTestsWithStdlib(const std::string &source, int argc=0, char **argv=nullptr)

Execute in test mode: tests kept, the runner main synthesized, stdlib preloaded.

Returns the runner's exit code (0 = every test passed).

Related: sun::driver::SunValue

getCompilerDigest

public · function · Source (opens in a new tab)

const std::string & sun::driver::getCompilerDigest()

Digest of the running executable's bytes, so output from a rebuilt compiler is never mistaken for output from the one before it.

Returns the compiler digest stored by this object.

Read once per process.

getStdlibMoonImports

public · function · Source (opens in a new tab)

std::vector< MoonImport > sun::driver::getStdlibMoonImports()

Get the stdlib.moon path for test preloading.

Related: MoonImport

hasStdlibImport

public · function · static · Source (opens in a new tab)

static bool sun::driver::hasStdlibImport(const std::vector< MoonImport > &moonImports)

Check if stdlib.moon is included in moon imports.

Related: MoonImport

haveTool

public · function · Source (opens in a new tab)

bool sun::driver::haveTool(const std::string &tool)

Whether tool exists on PATH.

initTestEnvironment

public · function · Source (opens in a new tab)

void sun::driver::initTestEnvironment()

Set SUN_PATH to cwd if not already set (for VS Code Test Explorer).

isVoid

public · function · Source (opens in a new tab)

bool sun::driver::isVoid(const SunValue &v)

Helper to check if value is void.

Related: SunValue

linkExecutable

public · function · Source (opens in a new tab)

bool sun::driver::linkExecutable(const std::string &objectPath, const std::string &outputPath, std::string &errorMsg, const LinkOptions &linkOpts={})

Links the object file to create an executable Uses the explicitly selected driver, or the target-appropriate default Returns true on success, false on failure.

Related: LinkOptions

linkerCommandFor

public · function · Source (opens in a new tab)

std::string sun::driver::linkerCommandFor(const std::string &targetTriple, bool staticLink=false)

Pick the link driver for a target.

SUN_CC overrides the choice entirely.

Static Linux links require a musl toolchain for the target architecture (<arch>-linux-musl-gcc). Missing musl never selects glibc or dynamic linkage implicitly; users must request dynamic or set SUN_CC explicitly.

A macOS target links with Apple's own cc on a Mac; from any other host there is no driver to pick — linking Mach-O needs the Apple SDK, which cannot ship with a Linux toolchain — so stop at emit-obj and link the object on a Mac.

Otherwise: host builds use cc; cross builds prefer a triple-prefixed GCC (aarch64-linux-gnu-gcc), falling back to clang --target=<triple>. Returns "" when no capable link driver exists on this machine.

loadNativeLibraries

public · function · Source (opens in a new tab)

NativeLibraries sun::driver::loadNativeLibraries(const LinkOptions &opts)

Make libraries named by -l visible to the JIT.

The JIT resolves externs through DynamicLibrarySearchGenerator over the current process, so a shared library only has to be dlopen'd into this process for its symbols to become reachable. A name that resolves to a static archive instead (lib<name>.a in a -L directory, or an explicit .a path) is returned in archives for the JIT to link itself.

Related: NativeLibraries, LinkOptions

mergeASTs

public · function · static · Source (opens in a new tab)

static std::unique_ptr< BlockExprAST > sun::driver::mergeASTs(std::vector< std::unique_ptr< BlockExprAST > > &parsedFiles)

Merge multiple parsed BlockExprASTs into a single unified AST.

Same-named modules are merged together.

Related: BlockExprAST

operator<<

public · function · Source (opens in a new tab)

std::ostream & sun::driver::operator<<(std::ostream &os, const SunValue &v)

Helper to print a SunValue.

Related: SunValue

operator==

operator==(T expected, const SunValue &v)

public · function · Source (opens in a new tab)

template <typename T>
bool sun::driver::operator==(T expected, const SunValue &v)

Compares the stored values for equality.

Related: SunValue

operator==(const SunValue &v, T expected)

public · function · Source (opens in a new tab)

template <typename T>
bool sun::driver::operator==(const SunValue &v, T expected)

Comparison helpers for testing.

Related: SunValue

packageFileHash

packageFileHash(const fs::path &path)

public · function · Source (opens in a new tab)

std::string sun::driver::packageFileHash(const fs::path &path)

No documentation comment.

packageFileHash(const std::filesystem::path &path)

public · function · Source (opens in a new tab)

std::string sun::driver::packageFileHash(const std::filesystem::path &path)

Returns the SHA-256 digest of a file, reporting unreadable inputs.

planPackages

public · function · Source (opens in a new tab)

std::vector< PackagePlan > sun::driver::planPackages(const SunConfig &config, const std::vector< PackageArtifact > &artifacts)

Checks membership and output locations before compiling production files.

processMoonImports

public · function · static · Source (opens in a new tab)

static void sun::driver::processMoonImports(BlockExprAST &blockAst, Parser &parser, const std::vector< MoonImport > &moonImports)

Process moon imports: collect stubs, deduplicate, check for collisions with source modules and between moons, then prepend to AST.

Related: BlockExprAST, Parser, MoonImport

readBuildRecord

public · function · Source (opens in a new tab)

std::optional< BuildRecord > sun::driver::readBuildRecord(const std::string &path)

The record inside the executable or object file at path.

Reads build provenance from a compiled artifact.

Empty when the file is missing, is not an object file, or carries no record.

Related: BuildRecord

readMoonInputHash

public · function · Source (opens in a new tab)

std::optional< std::string > sun::driver::readMoonInputHash(const std::string &path)

The input hash a .moon bundle was built from.

Reads the recorded input digest from a Moon library.

Empty when the file is missing or is not a readable bundle.

renameOwnExterns

public · function · static · Source (opens in a new tab)

static void sun::driver::renameOwnExterns(BlockExprAST &block, const std::map< std::string, std::string > &renames, std::vector< std::string > &unmapped)

Bind the program's own C externs to the archives the bundle being built carries: an extern whose link name is a key of renames is emitted, and recorded in the bundle's metadata, under the prefixed value.

Imported bundles' scopes are left alone; their externs were bound when they were built. Link names no rename applies to are collected in unmapped.

Related: BlockExprAST

resolveConfigDependency

public · function · Source (opens in a new tab)

fs::path sun::driver::resolveConfigDependency(const SunConfig &config, const std::string &name)

Resolves a configured dependency to a verified local directory on demand.

Related: SunConfig

resolveGitDependency

public · function · Source (opens in a new tab)

std::filesystem::path sun::driver::resolveGitDependency(const SunConfig &consumer, const std::string &name)

Builds a direct source file or configured library in an isolated directory.

Direct source builds use the consumer config; named builds use the library config. The directory exposes the library's output filename and excludes its tests. Reports missing or ambiguous entrypoints and dependency cycles.

Related: SunConfig

resolveGitEntrypoint

public · function · Source (opens in a new tab)

std::string sun::driver::resolveGitEntrypoint(const ConfigEntrypoint &entry, bool refresh=false)

Fetches a versioned checkout once and returns its entrypoint's absolute path.

Uses SUN_GIT_CACHE or ~/.sun/cache/git and Git's normal authentication. Refresh fetches a new snapshot while preserving previous checkouts. Reports fetch failures and paths escaping the checkout as compiler errors.

Related: ConfigEntrypoint

shellQuote

public · function · Source (opens in a new tab)

std::string sun::driver::shellQuote(const std::string &s)

Quote a string for safe use as a single argument in a /bin/sh command.

The link command runs through std::system, and -l/-L values come from the user, so they must not be able to inject shell syntax.

stripUnreachableForJIT

public · function · static · Source (opens in a new tab)

static void sun::driver::stripUnreachableForJIT(llvm::Module &module)

Strip library code the program never uses before handing a module to the JIT.

ORC eagerly compiles every defined function in an added module, so linked-but-unused stdlib code would dominate JIT time. Internalize everything except the entry points, then GlobalDCE drops whatever main can't reach (references through vtables/globals are preserved).

toDouble

public · function · Source (opens in a new tab)

double sun::driver::toDouble(const SunValue &v)

Helper to get numeric value as double (for backward compatibility).

Related: SunValue

validateGitSource

public · function · Source (opens in a new tab)

void sun::driver::validateGitSource(const ConfigEntrypoint &entry)

Rejects invalid Git URLs, invalid revisions, and escaping source paths.

Related: ConfigEntrypoint

warnAboutArchiveSet

public · function · static · Source (opens in a new tab)

static void sun::driver::warnAboutArchiveSet(const std::vector< std::string > &archives, const std::vector< std::string > &bareExterns)

What the linker will not say.

Two archives with one file name under different hashes mean two versions of a library go into the program, each bound to the code that came with it. A plain extern naming a symbol that a bundle carries only in prefixed form binds to whatever the final link provides under the bare name, which is rarely what was meant.

wrapOwnBundle

public · function · static · Source (opens in a new tab)

static void sun::driver::wrapOwnBundle(BlockExprAST &blockAst, const std::string &scopeName)

Move everything the program declares itself (every top-level node that is not an imported bundle's scope) into one MoonScopeAST for the bundle being built, named by its $hash$ prefix.

Imported scopes stay where they are.

Related: BlockExprAST, MoonScopeAST

wrapStaticCtorsForJIT

public · function · static · Source (opens in a new tab)

static bool sun::driver::wrapStaticCtorsForJIT(llvm::Module &module)

Make a module's global initializers callable under the JIT.

They are internal functions registered in llvm.global_ctors — one per linked module, uniquified by the IR linker — and the JIT resolves symbols by name, which cannot reach an internal function. So wrap every ctor entry in a single external runner for the driver to look up and call before main, in the same order the AOT init_array would use. Returns false when the module has no constructors and there is nothing to run.

Variables

ExitOnErr

ExitOnErr

public · variable · static · Source (opens in a new tab)

llvm::ExitOnError sun::driver::ExitOnErr

No documentation comment.

Type Aliases

SunValue

SunValue

public · typedef · Source (opens in a new tab)

using sun::driver::SunValue =  std::variant<VoidValue,   
                              bool,        
                              int8_t,      
                              int16_t,     
                              int32_t,     
                              int64_t,     
                              float,       
                              double,      
                              std::string  
                              >

SunValue can hold any primitive type that main() might return.

Related: VoidValue, SunValue, main()

Compiler API Reference