System API

Properties of the host machine and the running process: OS and device identity, hardware info, well-known directories, blocking sleeps, and live environment manipulation.

Overview

The System API is a namespace exposing properties of the host machine and the running process. It is registered at VM startup as the global identifier System; all methods are invoked as System.method(...).

For per-process subprocess control (spawning, piping stdin/stdout, killing), see Process. System.setEnv / System.unsetEnv mutate the current process's environment, and any process subsequently launched through Process.spawn / Process.exec inherits the updated environment automatically. No plumbing is required to pass values from the script down into a child.

Conventions

All string-returning methods produce UTF-8. On hosts that cannot answer a query (osVersion() on a stripped-down container, for instance) the call returns an empty string rather than null. cpuCount() returns a Zym number (integer-valued), and hasFeature / hasEnv return booleans.

Bad argument types raise a Zym runtime error of the form System.method(args): argument must be a <type>. systemDir(name) raises a runtime error if name is not one of the supported desktop-only kinds. See Conventions for the CLI-wide rules.

Identity

System.osName()

Returns the OS family name, e.g. "Linux", "macOS", "Windows".

System.distribution()

Returns the distribution or OS friendly name, e.g. "Ubuntu 25.10", "macOS 14.6", "Windows 11". Returns an empty string if the platform does not expose one.

System.osVersion()

Returns the version string for the OS. The format is platform-defined.

System.modelName()

Returns the device or model identifier as reported by the host. Desktops typically return "GenericDevice".

print("%s %s", System.osName(), System.distribution())
// Linux Ubuntu 25.10

Hardware

System.cpuName()

Returns the human-readable CPU brand string, e.g. "AMD Ryzen 9 5980HX with Radeon Graphics".

System.cpuCount()

Returns the number of logical CPU cores available to the process.

System.uniqueId()

Returns a stable per-machine identifier. Suitable for non-secret machine fingerprinting; not suitable as a secret.

Locale & Features

System.locale()

Returns the full BCP-47-ish locale tag, e.g. "en_US".

System.localeLanguage()

Returns the language portion of the locale only, e.g. "en".

System.hasFeature(name)

Tests for a runtime feature tag and returns a boolean.

if (System.hasFeature("64")) {
    print("64-bit build")
}

Process Info

System.executablePath()

Returns the absolute path of the currently running zym binary.

Directories

All directory methods return absolute paths as strings. Paths are not guaranteed to exist on disk. Create them before writing.

System.dataDir()

Returns the per-user, non-project-specific data directory. Linux: $XDG_DATA_HOME or ~/.local/share. macOS: ~/Library/Application Support. Windows: %APPDATA%.

Per-app data: System exposes only this broader, non-project-specific location; there is intentionally no equivalent for a per-application "user data" directory, since zym is a general-purpose runtime rather than a single project. For per-app isolation, append your own application-name segment to the value of dataDir().
System.configDir()

Returns the per-user config directory. Linux: $XDG_CONFIG_HOME or ~/.config.

System.cacheDir()

Returns the per-user cache directory. Linux: $XDG_CACHE_HOME or ~/.cache.

System.tempDir()

Returns the system temp directory: /tmp on Linux/macOS, %TEMP% on Windows.

System.systemDir(name)

Returns a well-known user folder. Only desktop-meaningful folders are accepted; any other value raises a runtime error.

per-user well-known folders
print("downloads: %s", System.systemDir("downloads"))
print("documents: %s", System.systemDir("documents"))

Sleep

Both sleep methods block the calling thread and return null.

System.sleep(ms)

Blocks the calling thread for ms milliseconds. Negative values are clamped to 0.

System.sleepUsec(usec)

Blocks the calling thread for usec microseconds. Negative values are clamped to 0.

var t0 = Time.ticksMsec()
System.sleep(250)
print("waited %n ms", Time.ticksMsec() - t0)

Environment

The environment methods read and write the current process's environment. Changes take effect immediately and propagate to any subsequent child process spawned via Process.spawn / Process.exec, because those inherit the parent's live environment by default.

System.getEnv(name)

Returns the value of name, or null if the variable is not set.

System.hasEnv(name)

Returns true if name is currently set, false otherwise.

System.setEnv(name, value)

Sets name to value, replacing any prior value. Returns null.

System.unsetEnv(name)

Removes name from the environment. No-op if it was not set. Returns null.

Process equivalents: Process also exposes Process.getEnv / Process.setEnv / Process.unsetEnv. They operate on the same underlying process environment as the System versions. Calling either is equivalent; use whichever module reads more naturally at the call site.
Thread safety: setenv / unsetenv are not thread-safe with respect to concurrent reads. Zym is single-threaded, so this is not a concern from script. It matters only when embedding zym alongside multi-threaded native code.

Examples

Identifying the Host

print("%s %s on %s", System.osName(), System.osVersion(), System.cpuName())
print("%n cores, locale %s", System.cpuCount(), System.locale())

Writing to the User's Data Directory

var dir = System.dataDir() + "/my-tool"
Dir.makeRecursive(dir)
File.writeAllText(dir + "/config.json", "{}")

Passing Environment Values to a Child Process

System.setEnv("MY_TOOL_LOG", "debug")
var r = Process.exec("/usr/local/bin/my-tool", ["--check"])
print("exit=%n", r.exitCode)
System.unsetEnv("MY_TOOL_LOG")