Projects

CandleC's build, check, and clean commands operate on a directory containing candlec.toml. Source and resource files are discovered recursively.

Project layout

hello/
├── candlec.toml
├── src/
│   ├── main.casm
│   └── util/math.casm
├── res/
│   └── greeting.txt
└── build/

Every .casm file under the source directory becomes a module. Its path relative to that directory, without the extension, forms the module name with path separators replaced by dots: src/util/math.casm becomes util.math. Dots in source path components are reserved for the module namespace.

Every non-directory file under the resource directory is a resource candidate. Its ID is its relative path with / separators, such as texts/greeting.txt. Resource IDs are used by load_res.

Configuration

candlec.toml uses TOML. The sections are optional; the defaults below apply when a setting is omitted.

[project]
name = "hello"
version = "1.0.0"
main_module = "main"

[paths]
source = "src"
resources = "res"
output = "build"

[optimization]
dead_code_elimination = true
dead_resource_elimination = true

[plugins]
"candlesys" = "1.0.0"

Setting	Default	Purpose
project.name	Project directory name, or project	Project name used in the output filename. It cannot be . or .. or contain / or \.
project.version	0.1.0	Project version used in the output filename. It cannot be . or .. or contain / or \.
project.main_module	main	Module that must contain the program's main function.
paths.source	src	Directory searched for .casm source files.
paths.resources	res	Directory searched for resources; if it does not exist, the project has none.
paths.output	build	Directory where the executable is written and which clean empties.
optimization.dead_code_elimination	true	Omits modules and functions not reached by CandleC's analysis.
optimization.dead_resource_elimination	true	Omits resource files not found by the analysis.
[plugins] entries	None	Records plugin names and non-empty versions as executable dependencies. It does not build or bundle plugin libraries.

Relative paths are resolved from the project directory; absolute paths are accepted. The executable is written as <name>-<version>.candle inside the output directory.

Main function and linking

The configured main module must exist and contain a main function with no parameters or captures. CandleC links plugin dependency metadata, module and function metadata, resources, startup instructions, and function bytecode into one executable. The startup instructions load the configured module and main function, call it, discard its return value, and exit with code zero.

CandleC encodes each function's instructions and appends ret void if its final instruction is not ret. Its relative jump syntax is expressed in instruction indexes, then converted to byte offsets; current CandleC accepts byte offsets from -128 through 127. See Control Flow and Calls and the CandleVM bytecode format.

Analysis and checks

During builds, CandleC analyzes reachable functions and resources from the configured main function. It recognizes statically visible module and function references, follows branches, and collects named resource references. When it cannot determine a call target, its reachability analysis conservatively treats all functions as potentially used. Dead-code and dead-resource elimination can each be disabled in [optimization].

check validates source parsing, instruction operands, duplicate modules and functions, main entry requirements, resource paths, and reachability warnings. It does not write an executable, run the program, load plugins, or perform all final linker checks; a project that passes check can still fail during build.

Clean output

candlec clean empties the configured output directory without removing the directory itself. If it does not exist, the command succeeds without creating it. CandleC refuses to clean the project root or an output path that is itself a symbolic link.