Core Runtime (.lcore files)

Luma ships with a small core runtime, implemented directly in Go, that provides the low-level building blocks used by the language. These functions are not written in Luma itself, but included into compiled programs on demand based on what features each program actually uses.

What are core functions?

• They are Go functions prefixed with _luma_ (e.g. _luma_toInt, _luma_list_add_all_bool).
• They handle essentials like type conversions, optional handling, list/set/map operations, printing, introspection, etc.
• They form the “standard library kernel” on which higher-level Luma features depend.

File format and extension

• Core functions are stored in .lcore files in the core/ directory.
• .lcore is chosen to clearly distinguish runtime source from user .luma programs and from regular .go files.
• Each .lcore file contains one or more Go functions, usually grouped by topic.

Example:

// Name: _luma_list_add_all_bool
// Description: Appends all elements from a bool slice to the target bool list.
// Author: Luma Core
// Version: 1.0
func _luma_list_add_all_bool(list *[]bool, values []bool) {
    *list = append(*list, values...)
}

Sliced core library

The core runtime is not embedded as a single monolithic blob. Instead, coregen splits .lcore files into 19 feature slices based on filename prefix. Only the slices a program actually uses are included in the generated Go output.

This means a simple print("Hello") program only includes CorePrint (~3 functions), not the entire runtime.

How they are included in compilation

• The generator tool coregen reads all .lcore files from the core/ directory and groups them by filename prefix into feature slices.
• It generates core_gen.go (at the project root) containing one Core* string constant per slice.
• During compilation, the compiler tracks which core slices are needed as it generates code (see Compilation Pipeline for details).
• Only the needed Core* constants are emitted into the generated Go program.
• Developers can set the LUMA_CORE=dev environment variable to pull .lcore files directly from disk during compiler development.

Regenerating core_gen.go

After modifying any .lcore file, regenerate the embedded constants:

cd cmd/coregen && go run main.go

This reads all files from core/ and writes the updated core_gen.go to the project root.

Why not .go?

• .lcore files are not standalone Go packages:
  • they don’t declare package,
  • they don’t import dependencies,
  • they are meant to be pasted into the generated main package.
• Using .go would mislead tools like go build or editors.
• .luma is reserved for user code.
• .lcore makes their purpose explicit: Luma core runtime.

Development guidelines

• Functions must start with _luma_ to avoid colliding with user code.
• Keep them minimal and consistent; they are the trusted runtime.
• Document parameters and return types in comments (helps both maintainers and the generator).
• Naming determines slicing: the filename prefix of a .lcore file determines which Core* slice it belongs to. When adding a new .lcore file, use the correct prefix (e.g. _luma_list_*.lcore for list operations) so coregen routes it to the right slice.
• When core changes are made, regenerate core_gen.go with cd cmd/coregen && go run main.go and commit it.