Modules, Manifests, and Project Configuration
| Concept | What it describes |
|---|---|
| Modules | Names, visibility, and shared state in Sun code. |
| Manifests | Source files and libraries used by one entrypoint. |
| Moon libraries | Compiled code and metadata shared between programs. |
| sun-config.json | Products, dependencies, targets, and build steps for a project. |
Modules
Module declarations
/** Small arithmetic helpers. */
public module math {
/** Returns the square of a number. */
public function square(x: i32) i32 {
return x * x;
}
}
/** Uses a function from another module. */
function main() i32 {
return math.square(3); // 9
}Inside math, call square(3) directly. Outside it, use math.square(3).
Dotted names create nested modules:
/** Helpers for reading files. */
public module app.files.readers {}This makes app, files, and readers public. The comment documents readers.
Use separate nested declarations to document each module.
Using statements
using math;
/** Calls square without the module prefix. */
function main() i32 {
return square(3);
}using math lets this file use names from math without the prefix. It does
not load another file or library; the manifest does that.
A using inside a function or module applies only there and in its children.
Each source file needs its own using statements, even when several files
contribute to the same module.
Visibility
/** Number operations available to callers. */
public module numbers {
/** Private helper used within this module. */
function twice(x: i32) i32 { return x * 2; }
/** Returns four times the input. */
public function four_times(x: i32) i32 { return twice(twice(x)); }
}Callers can use numbers.four_times(3). They cannot use numbers.twice(3).
Declarations are private unless marked public; there is no private keyword.
Private names are accessible within their module and its children, including
parts of that module in other files. using does not bypass privacy.
Class members follow the same module boundary. All declarations of the same module must agree on its visibility. Names outside any module are available throughout the program.
Module-level variables
/** Counts calls for the lifetime of the program. */
public module counter {
public var count: i64 = 0;
/** Records one call. */
public function add() void { count += 1; }
}counter.add() changes the shared counter.count. Use const for a value that
cannot change. Protect shared mutable values with a mutex when using
multiple threads.
Manifests
using std.io;
/** Prints a greeting. */
function main() void {
println("Hello!");
}
manifest {
source_files: ["helpers.sun"]
libraries: ["sun/stdlib"]
}Run it with sun main.sun. Sun compiles helpers.sun with main.sun and loads
the compiler-supplied standard library. Source paths start at the directory
containing main.sun.
All manifest fields are optional. A manifest declares dependencies, not the
artifact's identity. Source-level id fields are rejected.
Configured builds use the entrypoint's name as its local ID. When the project
has "package_id": "sun", an entrypoint named stdlib has the
canonical identity sun/stdlib. Without a package ID, the name is
used unchanged. Library and executable entrypoints follow the same rule.
Direct compilation defaults to the source filename without .sun. Use --id
to override that local name for one direct compilation:
sun --emit-moon --id geometry -o output.moon shapes.sunThe source project's package_id, when present, still prefixes the override.
The output path never changes identity. Configured builds reject --id, including
inside custom build scripts; change the entrypoint name in the config instead.
Renaming a published entrypoint changes its identity and can break consumers.
Test files and other inputs
manifest {
test_files: ["helpers_tests.sun"]
protos: ["messages.proto"]
archives: ["native/libhelper.a"]
}| Field | Use |
|---|---|
source_files | Compile more Sun files with the entrypoint. |
test_files | Include these files only when compiling tests. |
libraries | Load compiled .moon libraries. |
protos | Generate message types from Protobuf schemas. |
archives | Carry native static libraries inside a .moon bundle. |
See Testing, Protobuf, and C FFI for examples.
Platform-specific files
manifest {
source_files: ["files.sun"]
target: {
linux: { source_files: ["files_linux.sun"] }
macos: { source_files: ["files_macos.sun"] }
}
}A Linux build includes files_linux.sun before files.sun. A macOS build uses
files_macos.sun instead. windows is also supported.
--target selects the build target; without it, Sun uses the host platform.
The manifest only selects inputs for that target.
Package library references
Use package-id/entrypoint-name in libraries:
manifest {
libraries: [
"sun/stdlib",
"sun/tls",
"namo-robotics/aether/aether",
"namo-robotics/relay/relay"
]
}The last slash separates the package ID from the library entrypoint name.
sun/stdlib and sun/tls use the compiler's bundle search paths; they do not
fetch or build a compiler checkout. The compiler project's package ID is sun.
Other packages must be declared in sun-config.json dependencies. Their versions,
local workspace providers, selected entrypoints, and target restrictions remain
controlled by that configuration. Dependency libraries resolve from the package's
installed lib directory. Custom build scripts use their inherited dependency
locations without fetching again.
A reference to the current package selects its configured library output and
needs no self-dependency. Keep that library in the consuming entrypoint's
requires list so it is built first. References do not change build ordering.
Loose .moon paths remain supported for standalone files and prebuilt fixtures.
Library aliases work with both package references and file paths.
Path Resolution
manifest {
libraries: ["libs/shapes.moon", "stdlib.moon"]
}Sun searches in this order:
- The entrypoint's directory.
sun_pathdirectories from itssun-config.jsonfiles.- Directories passed with
--lib-path. - Directories in
SUN_PATH. - The compiler's library installation directories.
An installed compiler finds stdlib.moon without extra settings. To use a
library elsewhere:
sun --lib-path /path/to/libraries main.sunPath variables
Manifest entries can reference variables with $NAME — in source_files, libraries
(paths and urls) and protos entries alike. Here the manifest asks for
$LIBS/mathlib.moon:
manifest {
libraries: ["stdlib.moon", "$LIBS/mathlib.moon"]
}This folder's sun-config.json supplies both the library search path (where
stdlib.moon is found) and the variable:
{
"sun_path": ["../../build"],
"path_variables": { "LIBS": "libs" },
"root": true
}The compiler merges every sun-config.json from the entrypoint's folder up
to the filesystem root: the nearest definition of a variable wins, search
dirs are searched nearest-first, and relative entries resolve against their
own config file's folder. So a workspace root can define sun_path and shared
variables once, while each subfolder adds or overrides only what is local to
it. A config with "root": true stops the upward search — this example uses
it to stay self-contained. Explicit --path-var arguments override config
values; config values override the sun.pathVariables editor defaults and
the environment:
sun --path-var LIBS=libs --compile -o main main.sun # overrides config values
LIBS=libs sun --compile -o main main.sun # environment works tooUsing a variable that is defined nowhere is a compile error. Variables are expanded before path resolution, so a variable can hold a relative directory — which keeps a manifest portable when libraries live in a different place on each machine.
The config can also declare build products in an entrypoints array. See
Sun Config for the entry fields and how to build or test a
whole project.
Source
using std.io;
using std;
using mathlib;
/** Runs the example that calls a library imported using a path variable. */
function main() void {
println(triple(14));
}
manifest {
libraries: [
"sun/stdlib",
"$LIBS/mathlib.moon"
]
}/** Groups the declarations used by this example program. */
public module mathlib {
/** Returns three times the input to demonstrate a path-variable import. */
public function triple(x: i32) i32 {
return x * 3;
}
}
manifest {
source_files: []
libraries: []
}Build and run
./build.sh
./mainPrecompiled libraries (.moon)
A .moon file contains compiled code and the type information needed to use it.
Creating Moon files
/** Helpers for measuring shapes. */
public module shapes {
/** Returns the area of a square. */
public function square_area(side: i32) i32 { return side * side; }
}
manifest {
}sun --emit-moon -o shapes.moon shapes.sunTop-level modules in a library must be public. Put library globals inside a module too.
Using Moon files
/** Uses the compiled shapes library. */
function main() i32 {
return shapes.square_area(4); // 16
}
manifest {
libraries: ["shapes.moon"]
}sun main.sunPrivate library helpers remain hidden from callers.
Library identity
manifest {
}Keep this ID when publishing new versions of the same library. The ID identifies the library; it does not set the output filename or guarantee compatibility.
Libraries that use other libraries
app → ui.moon → graphics.moonIf the app only calls UI functions, its manifest needs only ui.moon. The UI
bundle carries the code and metadata it needs from graphics.moon.
To name graphics types directly in app source, also list graphics.moon.
Using another version does not replace the copy inside ui.moon. Sun checks
identity and ABI compatibility when values cross library boundaries; matching
type names alone are not enough. See ABI compatibility.
Module aliases
sun main.sun --moon shapes-v1.moon:shapes=old_shapes \
--moon shapes-v2.moon:shapes=new_shapesUse old_shapes and new_shapes in source to distinguish the versions. Aliases
change lookup names, not type identity or compatibility.
Library globals and constants
/** Shared dimensions. */
public module limits {
public const ROWS: i64 = 3;
}An importer can use limits.ROWS as an array size because its value is known at
compile time. A constant computed at startup cannot be used that way.
Library globals initialize once, before globals in code that imports them.
Bundle version names
sun --emit-moon shapes.sun -o shapes.moon --version-name v1.0.0This adds a readable label. It changes the bundle hash, but does not select versions or change compatibility rules.
Installed libraries
manifest {
libraries: ["sun/stdlib", "sun/tls"]
}stdlib.moon provides the standard library. Add tls.moon for
TLS and HTTPS; it carries its OpenSSL dependency.
The compiler searches its installation directories automatically. For your own
bundles, keep them beside the project or use --lib-path.
Project configuration: sun-config.json
Build a project
{
"root": true,
"package_id": "example/shapes",
"entrypoints": [
{ "name": "shapes", "path": "src/shapes.sun", "type": "library", "export": true },
{ "name": "viewer", "path": "src/main.sun", "type": "binary", "export": true,
"requires": ["shapes"] }
]
}sun build # Build exported products and their tests
sun build --all # Also build internal tests, examples, and tools
sun build --entrypoint viewer # Build viewer and its prerequisites
sun build --no-test # Omit test binaries
sun test sun-config.jsonentrypoints names the products to build; each source file's manifest names its
inputs. requires orders local products. It does not import them: the viewer's
manifest still lists the libraries it uses. package_id identifies the project
when another project depends on it. With a package ID, sun build selects
exported products by default; unnamed projects default to all products.
--all selects every enabled entrypoint without changing package exports. Use
--package to limit it to one package. It cannot be combined with --entrypoint.
Paths are relative to the declaring config. Sun discovers configs beside source
files and in parent directories; root: true stops that upward search.
sun -c sun-config.json also builds the config.
Composed config builds
{
"root": true,
"projects": ["src/*/sun-config.json"]
}sun build
sun build --package example/shapes
sun build --all # Build all enabled entrypoints across projects
sun build --package example/shapes --all
sun build --package example/shapes --entrypoint viewerprojects includes matching configs; Sun does not scan other directories
implicitly. Each project keeps its own paths and settings. Package IDs must be
unique in the workspace. A matching local project takes precedence over a
configured download or Git provider; a failed local build remains an error.
Output paths
sun describe --field build_root
sun describe --field install_root
sun describe --field package_idAdd --config <file> and --package <id> to select a project. Without --field,
sun describe prints JSON.
| Product | Output name |
|---|---|
Library named shapes | shapes.moon |
Binary named viewer | viewer |
Tests for shapes | shapes_test |
Without name, Sun uses the source filename without its extension. Manifest IDs
do not set output filenames. Build products go under .sun/build/; staged
products go under .sun/install/. Both paths include the target, build
configuration, and project name. Scripts use SUN_BUILD and SUN_INSTALL
instead of constructing those paths themselves.
After a successful configured build, source the generated environment script from the configuration's workspace root to run installed binaries by name:
source .sun/install/env.sh
viewerThe script uses plain export PATH=... lines to add installed binaries while
preserving your existing PATH. It includes all composed projects already
installed for the selected target and build configuration, even with --package.
Paths are absolute and quoted, so you can source the script from any directory.
Each build rewrites it; source it again to pick up newly installed directories.
For POSIX shells, use . .sun/install/env.sh.
Dependencies
Every dependency belongs in the config's dependencies array:
{
"dependencies": [
{ "type": "moon", "package": "example/math", "path": "vendor/math.moon" }
]
}manifest {
libraries: ["example/math/math"]
}type | Provider | Main fields |
|---|---|---|
git | Sun products built from source | url, version, packages |
moon | A compiled Sun library | package, url or path |
package | A whole Sun distribution | package, url or path |
binary | A prebuilt executable | package, binary, url or path |
system | System packages or build tools | apt or brew, optional check |
deb | A particular Debian package file | url or path, sha256 |
Remote Moon, binary, and Sun package downloads require sha256. Debian files
require it even for a local path. Replace checksum placeholders in the examples
with the file's lowercase SHA-256 digest.
Git repositories
{
"dependencies": [
{
"type": "git",
"url": "git@github.com:example/toolkit.git",
"version": "main",
"packages": {
"example/core": { "entrypoints": ["core"] },
"example/ui": { "entrypoints": ["widgets", "viewc"] }
}
}
]
}Import "example/core/core" in the consumer's manifest. packages
selects project IDs and entrypoint names, not manifest IDs. Sun builds those
products and their prerequisites, runs their preparation steps, and skips their
tests. An optional config selects a repository-relative root config instead
of sun-config.json.
version is a branch, tag, or commit. HTTPS, ssh://, and git@host:path URLs
use Git's normal authentication. Sources stay cached until a build uses
--refresh-sources. Generated products stay outside the checkout, under
.sun/cache/git/builds or SUN_GIT_CACHE.
For a single source file instead of a repository config, replace packages with
"package": "example/core" and "path": "src/core.sun". This form builds with
the consumer's settings and cannot also specify config.
Moon files, binaries, and Sun packages
Each object below is one item in dependencies:
{
"type": "moon",
"package": "example/shapes",
"url": "https://example.com/shapes.moon",
"sha256": "<sha256>"
}The library appears at ${example/shapes}/lib/shapes.moon. Its expected library
identity defaults to package; add library when the identities differ.
Sun verifies the artifact's checksum, library identity, and target.
{
"type": "binary",
"package": "example/tools",
"binary": "example/viewc",
"url": "https://example.com/viewc",
"sha256": "<sha256>"
}The executable appears at ${example/tools}/bin/viewc.
{
"type": "package",
"package": "example/tools",
"url": "https://example.com/tools.tar.gz",
"sha256": "<sha256>"
}This selects a whole Sun distribution with its package.json inventory.
All three types accept a local path instead of url; a whole package may also
be an extracted directory. Local paths are config-relative.
System libraries
{
"dependencies": [
{
"type": "system",
"check": { "type": "pkg-config", "name": "sdl3", "version": ">=3.2" },
"target": {
"linux": { "apt": ["libsdl3-dev"] },
"macos": { "brew": ["sdl3"] }
}
}
]
}check is optional. A pkg-config check runs pkg-config --exists with the
module name and optional version constraint. Comparisons support >=, <=, =,
>, and <; a bare version means equality. This checks library metadata, not
whether a program can compile or run with the library.
For a build tool, use an executable check:
{
"type": "system",
"check": { "type": "executable", "name": "cmake" },
"apt": ["cmake"],
"brew": ["cmake"]
}An executable check looks for the named program on the host's PATH; it does
not run the program or check its version. Check names must be simple module or
executable names, not paths or shell commands.
For package-manager installation without an availability check, omit check:
{ "type": "system", "apt": ["build-essential"] }sun build skips availability checking for this declaration. sun dep install
passes its packages to the host package manager, which handles already-installed
packages. With a check, installation is skipped when it passes and the check is
repeated afterward. A check without an installation mapping is also allowed,
but a missing dependency must then be installed manually.
These declarations do not add linker flags. To pass library flags to a product,
also add "pkg_config": ["sdl3"] to that entrypoint. Private downloaded
archives, such as musl OpenSSL, can remain preparation steps.
Debian artifacts
{
"dependencies": [
{
"type": "deb",
"target": {
"x86_64-linux-gnu": {
"url": "https://example.com/library-dev_amd64.deb",
"sha256": "<amd64-sha256>"
},
"aarch64-linux-gnu": {
"url": "https://example.com/library-dev_arm64.deb",
"sha256": "<arm64-sha256>"
}
}
}
]
}Use deb for a specific package file; use system for packages from configured
APT repositories. Installation verifies the checksum and architecture, then
invokes APT if the exact version is not installed. APT handles dependencies and
runs package installation scripts. The file must also support the host's
distribution and repositories; an architecture match alone is not sufficient.
An optional check supplies the build-time availability check. Otherwise,
builds query the installed package version using the verified artifact cached
by sun dep install. The original local .deb can be removed afterward. A local path still requires sha256.
Target-specific dependencies
{
"dependencies": [
{
"type": "moon",
"package": "example/shapes",
"target": {
"x86_64-linux-gnu": {
"url": "https://example.com/shapes-linux.moon",
"sha256": "<linux-sha256>"
},
"arm64-apple-darwin": {
"url": "https://example.com/shapes-macos.moon",
"sha256": "<macos-sha256>"
}
}
}
]
}To restrict where a dependency applies without changing its fields, use
supported_targets:
{
"dependencies": [
{
"type": "git",
"url": "git@github.com:example/toolkit.git",
"version": "main",
"supported_targets": ["x86_64-linux-gnu", "arm64-apple-darwin"],
"packages": {"example/ui": {"entrypoints": ["widgets"]}}
}
]
}The list accepts exact target triples, normalizes aliases, and keeps architectures
and ABIs distinct. An empty list disables the dependency everywhere. Omit it to
apply no additional restriction. Use target when fields differ by platform;
when both are present, the target must be allowed by supported_targets and
have a matching target branch. Existing empty target branches remain supported.
The same selection rules apply to every explicit dependency type:
- Fields outside
targetare shared; the matching branch overrides them. - Exact triples take precedence over
linux,macos, andwindowsbranches. Branches do not inherit from one another. - Without
target, shared fields apply on every allowed target. With no matching branch, the dependency is skipped. - All branches are validated, including inactive ones.
--target selects the compilation target; otherwise Sun uses the host.
For a host tool, start a preparation command with a reference such as
"${example/ui}/bin/viewc"; Sun resolves that tool for the host.
Installing dependencies
sun dep install --dry-run
sun dep install
sun dep install --config path/to/sun-config.json --package example/app
sun dep install --yesThe command follows project and target selection. It installs missing system
requirements, installs prebuilt artifacts, and fetches Git sources. It follows
local and Git dependency configs to install their declared requirements without
running preparation steps, generators, or compilation. sun build builds the
selected source products afterward.
--dry-run prints the plan without downloading, building, or installing, so it
cannot discover requirements in unresolved sources. APT retains its confirmation
prompt unless --yes is supplied and uses sudo when needed. Sun does not
refresh APT repository metadata automatically.
sun build runs declared availability checks before compilation but never
installs them. Host package installation rejects cross-compilation targets;
see Cross-compiling for target library setup.
Inspect a dependency
sun resolve --config sun-config.json --package example/app --dependency example/shapesThis prints the dependency root and target as JSON. Resolution may download or build the dependency. Editor discovery uses already staged products instead.
Dependency cache
SUN_DEPENDENCY_CACHE=/path/to/shared-cache sun buildBy default, artifact dependencies use .sun/cache/dependencies/ under the
selected workspace, or beside the standalone config. Matching downloads are
reused; incorrect bytes are rejected. No writable home directory is needed.
Git uses .sun/cache/git/ or SUN_GIT_CACHE; Debian artifacts use
.sun/cache/debs/ under the workspace.
Existing configs
Untyped dependency declarations remain supported. When migrating, add type,
rename Git's git field to url, and rename artifact hash to sha256.
Legacy unpinned URLs refresh on resolution; new remote artifact declarations
require a checksum. Existing whole-value default/target dependency wrappers
also remain supported.
A local-only selection can still use
{ "package": "example/core", "entrypoints": ["core"] }
to select products from an included project without an external provider.
Target-specific settings
{
"supported_targets": ["x86_64-linux-gnu", "aarch64-linux-gnu"],
"sun_path": {
"default": ["vendor/x86_64"],
"target": { "aarch64-linux-gnu": ["vendor/aarch64"] }
},
"entrypoints": [
{
"name": "app",
"path": "src/main.sun",
"enabled": {
"default": false,
"target": { "aarch64-linux-gnu": true }
}
}
]
}supported_targets restricts the entire project. Incompatible projects are
warned about and skipped before their dependencies or child configs are loaded.
Omit it to allow every target; [] disables the project. An explicit package or
entrypoint selection must still match a build product.
For individual settings, a matching target replaces default, including whole
arrays. Without a match, the default applies; a required setting with neither
is an error. Names stay fixed. Disabled entrypoints skip their other settings.
Do not wrap the structural entrypoints, packages, or dependencies arrays.
Targets normalize aliases but retain architecture and ABI distinctions. Setting
a target-specific value does not itself restrict project support. Legacy
top-level target blocks remain supported but cannot overlap per-setting
wrappers for the same setting.
Preparation steps
{
"steps": [
{
"name": "generate",
"command": ["python3", "generate.py", "${SUN_BUILD}/generated.sun"],
"inputs": ["generate.py"],
"outputs": ["${SUN_BUILD}/generated.sun"]
}
],
"entrypoints": [
{ "name": "app", "path": "main.sun", "steps": ["generate"] }
]
}Steps run before normal compilation. Sun hashes declared inputs, tools, and
outputs to skip unchanged steps; missing or changed outputs cause a rerun.
Outputs must be under SUN_BUILD. Commands are argument lists, not shell
expressions. A step's requires lists earlier steps; an entrypoint's requires
lists earlier products.
Use entrypoint compile_args, pkg_config, and link_args for native compiler
and linker options. For generated C bindings, see
C header binding generation.
Custom build scripts
{
"entrypoints": [
{ "name": "app", "path": "main.sun", "build": ["scripts/compile.sh"] }
]
}#!/bin/sh
# Compile this product using the settings supplied by Sun.
set -eu
"$SUN_EXECUTABLE" build-compile --dynamic -lmbuild replaces normal compilation. Its executable scripts run in order from
the config directory on every requested build. Each needs a shebang and must
manage its own incremental work. A failure preserves the previous installation.
Do not combine build with steps, compile_args, pkg_config, link_args,
or a Git entrypoint.
Scripts receive SUN_SOURCE, SUN_OUTPUT, SUN_TEST_OUTPUT, SUN_TARGET,
SUN_BUILD, SUN_INSTALL, SUN_JOBS, and SUN_EXECUTABLE.
SUN_BUILD_CONTEXT names their read-only build settings. build-compile
inherits those settings and accepts extra compiler flags.
"$SUN_EXECUTABLE" dependency-path example/shapes
"$SUN_EXECUTABLE" dependency-path example/tools --hostThese commands read already resolved dependencies from the build context;
they do not download or build. --host selects a tool for the build machine.
Distributions and resources
{
"entrypoints": [
{ "name": "app", "path": "main.sun", "type": "binary" }
],
"packages": [
{
"name": "app-tools",
"entrypoints": ["app"],
"resources": [{ "path": "assets", "destination": "share/app/assets" }]
}
]
}sun build creates packages/app-tools/ and packages/app-tools.tar.gz under
SUN_BUILD. The distribution contains bin/app, assets, and a package.json
inventory. Libraries go in lib/; tests and compiler temporary files stay out.
This top-level packages array defines distributions; a Git dependency's
packages dictionary selects products to consume.
Resource paths are config-relative. Destinations stay inside the distribution; Sun rejects missing files, links, and conflicting destinations. Changing only resources repackages without recompiling unchanged code.
To copy resources beside one product, add resources to its entrypoint:
{
"entrypoints": [
{
"name": "app",
"path": "main.sun",
"resources": [{ "path": "assets/icons", "destination": "app.icons" }]
}
]
}Entrypoint destinations are relative to that product's directory. Package
resources and config-wide exports use package-relative destinations.
Building only what changed
sun build
sun build # Reuse unchanged artifacts
sun build --force-rebuildSun compares inputs, dependencies, target, flags, and compiler. Unchanged outputs
keep their timestamps. Test-only edits rebuild tests without rebuilding the
application. --force-rebuild bypasses the incremental check.
Advanced compilation
Cross-compiling
sun build --target aarch64-linux-gnu
sun --emit-obj --target aarch64-linux-gnu --lib-path vendor/aarch64 main.sunUse bundles built for the requested target and a compatible compiler. Sun rejects wrong-target bundles. Installation directories are searched for target subdirectories automatically; custom library paths must name the right directory.
pkg-config dependency checks for cross-builds require PKG_CONFIG_LIBDIR pointing
at target metadata. Set PKG_CONFIG_SYSROOT_DIR as appropriate. sun dep install
does not install foreign system packages into the host or a target sysroot.
Exporting complete LLVM IR
sun --emit-llvm -O0 -o main.ll main.sunThis emits LLVM IR, including imported code, without linking or running tests.
Omit -O0 for optimized output. Use matching LLVM tools to process the result.
This option accepts a source entrypoint, not a config build.