std/comptime: add IncludeBytes (#128)

Author: mertcandav

std/comptime/embed.jule

@@ -0,0 +1,9 @@
+// Copyright 2026 The Jule Project Contributors. All rights reserved.
+// Use of this source code is governed by a BSD 3-Clause
+// license that can be found in the LICENSE file.
+
+// Returns the contents of the file at path as a byte slice.
+// The file path is resolved relative to the file path of the package in which
+// the function is called. In other words, the file is searched for in the
+// directory of the package that contains the source file calling the function.
+// fn IncludeBytes(path: str): []byte

std/jule/README.md

@@ -15,6 +15,7 @@ It is also used by the official reference compiler julec and is developed in par
 - [`log`](./log): Elementary package for logs.
 - [`mod`](./mod): Module file parsing and module handling.
 - [`parser`](./parser): Parser. Makes syntax analysis, builds AST.
+- [`resources`](./resources): API for compile-time resources.
 - [`sema`](./sema): Semantic analyzer and HIR (High-Level Intermediate Representation) components.
 - [`token`](./token): Lexical analyzer. Segments Jule source code into tokens.
 - [`types`](./types): Elementary package for types.

std/jule/importer/importer.jule

@@ -10,11 +10,13 @@ use "std/jule/directive"
 use "std/jule/log"
 use "std/jule/mod"
 use "std/jule/parser"
+use "std/jule/resource"
 use "std/jule/sema"
 use "std/jule/token"
 use "std/os"
 use "std/os/filepath"
 use "std/strings"
+use "std/unsafe"
 
 // Read buffer by file path.
 fn readBuff(path: str): []byte {
@@ -35,12 +37,26 @@ fn flatCompilerErr(text: str): log::Log {
 	}
 }
 
+struct file {
+	path:     str
+	mut data: []byte
+}
+
+impl resource::File for file {
+	fn Path(*self): str { ret self.path }
+
+	fn Bytes(*self): []byte { ret self.data }
+
+	fn Text(*self): str { ret unsafe::StrFromBytes(self.data) }
+}
+
 // Default importer for the reference Jule compiler.
 struct importer {
-	mods: []&mod::Mod
-	mod:  &mod::Mod
-	pkgs: []&sema::ImportInfo
-	vars: []str
+	mod:   &mod::Mod
+	mods:  []&mod::Mod
+	pkgs:  []&sema::ImportInfo
+	vars:  []str
+	files: map[str]resource::File
 }
 
 impl sema::Importer for importer {
@@ -159,6 +175,20 @@ impl sema::Importer for importer {
 	fn AllPackages(mut *self): []&sema::ImportInfo {
 		ret self.pkgs
 	}
+
+	fn GetFile(mut *self, path: str): resource::File {
+		mut file, _ := self.files[path]
+		ret file
+	}
+
+	fn IncludeFile(mut *self, path: str): resource::File {
+		mut data := os::ReadFileSync(path) else { ret nil }
+		ret &file{path: path, data: data}
+	}
+
+	fn IncludedFile(mut *self, mut file: resource::File) {
+		self.files[file.Path()] = file
+	}
 }
 
 impl importer {
@@ -187,6 +217,7 @@ impl importer {
 // Returns new default Jule package importer by the compile information.
 fn New(info: CompileInfo): sema::Importer {
 	mut imp := new(importer)
+	imp.files = make(map[str]resource::File)
 	imp.mods = [build::ModStdlib()]
 	initVars(&imp.vars, info)
 	ret imp

std/jule/resource/file.jule

@@ -0,0 +1,17 @@
+// Copyright 2026 The Jule Project Contributors. All rights reserved.
+// Use of this source code is governed by a BSD 3-Clause
+// license that can be found in the LICENSE file.
+
+// A general file instance for compile-time embed files.
+trait File {
+	// Returns path of the file.
+	fn Path(*self): str
+
+	// Returns file content in bytes.
+	// The return value may be mutable reference to the internal buffer,
+	// and mutation is not allowed.
+	fn Bytes(*self): []byte
+
+	// Returns file content in text.
+	fn Text(*self): str
+}

std/jule/sema/api.jule

@@ -72,6 +72,7 @@ fn analyzePackage(mut files: []&ast::AST, mut importer: Importer, flags: int): (
 		files: tables,
 		flags: flags,
 		meta: new(commonSemaMeta),
+		importer: importer,
 	}
 
 	// Use first table (so first file) for this.

std/jule/sema/builtin.jule

@@ -2,12 +2,14 @@
 // Use of this source code is governed by a BSD 3-Clause
 // license that can be found in the LICENSE file.
 
+use "std/conv"
 use "std/fmt"
 use "std/internal/jule/mod"
 use "std/jule/ast"
 use "std/jule/constant"
 use "std/jule/log"
 use "std/jule/types"
+use "std/os/filepath"
 
 // Type alias for built-in function callers.
 //
@@ -1290,6 +1292,71 @@ fn builtinCallerStdComptimeTypeAlias(mut e: &eval, mut fc: &ast::CallExpr, _: &V
 	ret buildVoidValue()
 }
 
+fn builtinCallerStdComptimeIncludeBytes(mut e: &eval, mut fc: &ast::CallExpr, _: &Value): &Value {
+	if len(fc.Args) > 1 {
+		e.pushErr(fc.Token, "passed more argument than expected to IncludeBytes")
+		e.pushSuggestion("call like; IncludeBytes(Path)")
+		ret nil
+	}
+	if len(fc.Args) == 0 {
+		e.pushErr(fc.Token, "identifier and type is missing for IncludeBytes")
+		e.pushSuggestion("call like; IncludeBytes(Path)")
+		ret nil
+	}
+	mut v := e.eval(fc.Args[0], evalDefault)
+	if v == nil {
+		ret nil
+	}
+	if !v.IsConst() || !v.Constant.IsStr() {
+		e.pushErr(fc.Args[0].Token, "expression must be constant and string")
+		ret nil
+	}
+	mut path := v.Constant.ReadStr()
+	if len(path) == 0 {
+		e.pushErr(fc.Args[0].Token, "empty path for IncludeBytes")
+		ret nil
+	}
+	if !filepath::IsAbs(path) {
+		packagefile := e.s.getCurrentFile()
+		packagedir := filepath::Dir(packagefile.File.Path)
+		path = filepath::Join(packagedir, path)
+		path = filepath::Abs(path) else {
+			e.pushErr(fc.Args[0].Token, "path handling failed: "+fmt::Sprint(error))
+			ret nil
+		}
+	}
+	mut file := e.s.importer.GetFile(path)
+	if file == nil {
+		file = e.s.importer.IncludeFile(path)
+		if file == nil {
+			e.pushErr(fc.Args[0].Token, "IncludeBytes cannot read file: "+conv::Quote(path))
+			ret nil
+		}
+		e.s.importer.IncludedFile(file)
+	}
+	data := file.Bytes()
+	mut bytes := &SliceExpr{
+		ElemType: primU8,
+		Elems: make([]&Value, 0, len(data)),
+	}
+	for _, b in data {
+		mut bc := constant::NewU64(u64(b))
+		bytes.Elems = append(bytes.Elems, &Value{
+			Type: &Type{Kind: primU8},
+			Constant: bc,
+			Model: bc,
+		})
+	}
+	ret &Value{
+		Type: &Type{
+			Kind: &Slice{
+				Value: primU8,
+			},
+		},
+		Model: bytes,
+	}
+}
+
 fn builtinCallerStdMemSizeOf(mut e: &eval, mut fc: &ast::CallExpr, _: &Value): &Value {
 	mut result := &Value{
 		Type: primUint,
@@ -1367,7 +1434,7 @@ fn builtinCallerStdIntegEmit(mut e: &eval, mut fc: &ast::CallExpr, mut v: &Value
 	}
 
 	if !argVal.IsConst() || !argVal.Constant.IsStr() {
-		e.pushErr(fc.Args[0].Token, "expression must be constant")
+		e.pushErr(fc.Args[0].Token, "expression must be constant and string")
 		ret nil
 	}
 
@@ -1496,6 +1563,7 @@ fn init() {
 	builtinFuncsStdComptime["File"] = &FuncIns{caller: builtinCallerStdComptimeFile}
 	builtinFuncsStdComptime["Files"] = &FuncIns{caller: builtinCallerStdComptimeFiles}
 	builtinFuncsStdComptime["TypeAlias"] = &FuncIns{caller: builtinCallerStdComptimeTypeAlias}
+	builtinFuncsStdComptime["IncludeBytes"] = &FuncIns{caller: builtinCallerStdComptimeIncludeBytes}
 
 	// Initialize built-in functions of the "std/integ" package.
 	builtinFuncsStdInteg["Emit"] = &FuncIns{

std/jule/sema/package.jule

@@ -6,6 +6,7 @@ use "std/jule/ast"
 use "std/jule/build"
 use "std/jule/log"
 use "std/jule/mod"
+use "std/jule/resource"
 use "std/jule/token"
 use "std/os/filepath"
 use "std/strings"
@@ -35,18 +36,31 @@ trait Importer {
 	// Path is the directory path of package to import.
 	// Should return abstract syntax tree of package files.
 	// Logs accepts as error.
-	// Updated module to package's module if exist when updateMod is true.
+	// Updates module to package's module if exist when updateMod is true.
 	fn ImportPackage(mut *self, path: str, updateMod: bool): ([]&ast::AST, []log::Log)
 
 	// Invoked after the package is imported.
-	// Sets module identitity of imported package to current module.
+	// Sets module identitity of the imported package to current module.
+	// If the current module is not registered, for example,
+	// updated by the ImportPackage it will be registered.
 	fn Imported(mut *self, mut &ImportInfo)
 
 	// Returns all imported packages.
 	// The return value may be mutable reference to the internal buffer.
 	// Packages should be ordered by FIFO; starting with the first deepest
 	// imported package, and ending with the last imported package.
 	fn AllPackages(mut *self): []&ImportInfo
+
+	// Returns File by path.
+	// This function accepted as returns already included file.
+	// If returns not-nil value, will be used instead of IncludeFile if possible.
+	fn GetFile(mut *self, path: str): resource::File
+
+	// Includes the file by path, returns nil if failed.
+	fn IncludeFile(mut *self, path: str): resource::File
+
+	// Invoked after the file is included.
+	fn IncludedFile(mut *self, mut file: resource::File)
 }
 
 fn findVarFileInPackage(mut files: []&SymTab, v: &Var): &SymTab {

std/jule/sema/sema.jule

@@ -306,12 +306,13 @@ const (
 // Semantic analyzer for tables.
 // Accepts tables as files of package.
 struct sema {
-	errors: []log::Log
-	files:  []&SymTab // Package files.
-	file:   &SymTab   // Current package file.
-	flags:  int
-	meta:   &commonSemaMeta
-	step:   int
+	errors:   []log::Log
+	files:    []&SymTab // Package files.
+	file:     &SymTab   // Current package file.
+	flags:    int
+	meta:     &commonSemaMeta
+	step:     int
+	importer: Importer
 }
 
 impl Lookup for sema {
@@ -620,6 +621,7 @@ impl sema {
 					files: imp.Package.Files,
 					flags: self.flags,
 					meta: self.meta,
+					importer: self.importer,
 				}
 				s.setSemaFields()
 				semas[i] = s