# Settings

Gizlang has no configuration file of its own. A program, a library or the `giz` command reads the settings below from
the environment. A project's own settings are in its `package.json` ([the manifest](../guides/command-line.md#the-project-manifest)).

The docs suite (`tests/docs`) fails when the code reads a variable that this page does not list.

## Install and toolchain

| Variable | Effect | More |
| --- | --- | --- |
| `GIZ_INSTALL`, `GIZDB_INSTALL` | The folder that the install script installs into. The defaults are `~/.giz` and `~/.gizdb`. | [Start](../start.md#install-options) |
| `GIZ_VERSION` | The toolchain version that runs this command. It takes precedence over `gizlang.version` of `package.json`. | [Start](../start.md#keep-the-toolchain-current) |
| `GIZ_ACCESS_TOKEN` | The access token of the gizstack.com preview, for the installer, `giz upgrade` and package reads. The default is the file `~/.config/gizstack/access-token`. It is sent to gizstack.com only. | |
| `GIZ_INSTALLER` | Set by the install script: the path of the signed installer, which `giz update` runs. | |
| `GIZ_SELF`, `GIZ_SKILLS`, `GIZ_STANDALONE` | Set by the npm launcher: its own command, the folder of its agent skill, and that no toolchain is installed yet. | |

## Build, cache and packages

| Variable | Effect | More |
| --- | --- | --- |
| `GIZLANG_CACHE` | The store of compiled units, test passes, executables and fetched models. The default is `$XDG_CACHE_HOME/gizlang`, else `~/.cache/gizlang`. | [Command line](../guides/command-line.md#environment-variables) |
| `GIZLANG_CACHE_GB` | The size past which the hourly pass removes the least recently used cache files. The default is 150, at most half of the disk. | [Command line](../guides/command-line.md#environment-variables) |
| `GIZLANG_SHARED_CACHE`, `GIZLANG_TRUSTED_KEYS` | A store of units, executables and test passes that other machines built, and the Ed25519 keys whose signatures you accept. | [Command line](../guides/command-line.md#environment-variables) |
| `GIZLANG_SIGNING_KEY` | A file with a 32-byte Ed25519 seed. The machine signs what it builds with it. | [Command line](../guides/command-line.md#environment-variables) |
| `GIZLANG_STORE`, `GIZLANG_STORE_GB` | A build store that machines share (`ssh://HOST/PATH` or a folder; `off` for none), and its size in GiB (default 150). | [Compiler](../internals/compiler.md) |
| `GIZLANG_REGISTRY` | The package registry: a folder, or an HTTP or HTTPS URL. The default is `https://gizstack.com/packages`. | [Command line](../guides/command-line.md#registries) |
| `GIZLANG_REGISTRY_TOKEN`, `GIZLANG_REGISTRY_ORG`, `GIZLANG_REGISTRY_VISIBILITY` | The bearer token, the organization and the visibility (`public` or `private`) of a remote publication. | [Command line](../guides/command-line.md#publish-a-package) |
| `GIZLANG_TAILWIND` | The Tailwind compiler to run, instead of the pinned one that the cache fetches. | [Markup](ghtml.md) |
| `GIZLANG_NODE_LIB` | The folder of Node's `lib/` for the VM, instead of the copy in the cache. | [VM](../internals/vm.md) |
| `GIZLANG_CLANG` | The `clang` that compiles LLVM IR. The default is the one of the toolchain. | [Tools](../internals/tools.md) |
| `GIZLANG_HOST_LLVM` | For a macOS release built on Linux: the folder of the host LLVM tools. | [Tools](../internals/tools.md) |
| `GIZLANG_WINDOWS_TOOLS` | For a Windows build (`giz build --target x86_64-pc-windows-gnu`): the work folder of `tools/windows/runtime.giz`, with `llvm-mingw/` and `openssl/`. | [Tools](../internals/tools.md) |
| `GIZLANG_WINDOWS_RUNTIME` | For a Windows build: the output folder of `tools/windows/runtime.giz` (the runtime archive). | [Tools](../internals/tools.md) |

## Programs at run time

| Variable | Effect | More |
| --- | --- | --- |
| `GIZLANG_MEMORY_LIMIT` | The bytes that one World may own. The default is 80% of the memory of the machine or of its cgroup. Past it, the program faults with R011. | [Runtime](../internals/runtime.md) |
| `GIZLANG_THREADS` | The number of threads of parallel loops and tasks. The default is one for each CPU of the affinity and quota. | [System](../internals/system.md) |
| `GIZLANG_WORKERS`, `GIZLANG_WORKER` | `N` or `auto`: run `main` in N processes that share the listening sockets. Each worker has `GIZLANG_WORKER` set. | [System](../internals/system.md#worker-processes) |
| `GIZLANG_TASK_STACK` | The bytes of the stack of each task. Smaller values than the minimum are ignored. | [Runtime](../internals/runtime.md) |
| `GIZLANG_CPU` | `x86-64`, `v3` or `v4`: the x86-64 level that vector code runs at. The default is the highest that the CPU has. | [Language](language.md) |
| `GIZLANG_DEVICE` | `cpu`, `cuda`, `hip` or `metal`: the device of tensors and kernels. | [Compute](../internals/compute.md) |
| `GIZLANG_GPU_SOURCES` | The folder that receives the source of each GPU kernel as it compiles (PTX, or LLVM IR on AMD). | [Language](language.md) |
| `GIZLANG_PROFILE`, `GIZLANG_PROFILE_HZ` | A file (`%p` is the process ID) that receives stack samples of the run, and the samples per second (default 997). | [Runtime](../internals/runtime.md) |
| `GIZLANG_RECORD`, `GIZLANG_REPLAY` | Set by `--record LOG` and `--replay LOG`: the log of the inputs of the run. | [Command line](../guides/command-line.md#record-and-replay) |
| `GIZLANG_GC_STRESS` | Any value but `0` collects at each allocation of a Ref, to find a missing root. | [Memory](../internals/memory.md) |
| `GIZLANG_ISOLATE`, `GIZLANG_ISOLATE_CODE`, `GIZLANG_HANDED`, `GIZLANG_CGROUP` | Set by a program that starts a confined child: confine it, the folder whose files it may run, the descriptors that it gets, and the cgroup that it enters. | [System](../internals/system.md) |
| `GIZLANG_IPC`, `GIZLANG_SCRIPT` | Set by the VM for a Node child process: framed IPC on its channel, and the script that a fork runs. | [VM](../internals/vm.md) |

## Libraries

| Variable | Effect | More |
| --- | --- | --- |
| `GIZDB_PASSWORD` | The password that the GizDB server asks for. The same as `--password`. | [GizDB server](../operations/gizdb-server.md) |
| `GIZDB_MODELS`, `GIZDB_MODELS_ALLOW`, `GIZDB_MODELS_LIMIT` | The models folder of SQL ML functions, the model names that may be fetched, and the bytes that they may hold. | [SQL ML](../guides/sql-ml.md) |
| `GIZ_STORAGE_NODES`, `GIZ_STORAGE_CREDENTIAL`, `GIZ_STORAGE_SITE` | For a GizFS client: the nodes of the range, the issued credential, and the site to read from first. | [Storage](../guides/storage.md) |
| `GIZ_STORAGE_KEY`, `GIZ_STORAGE_HISTORY`, `GIZ_STORAGE_RESTORE_KEY`, `GIZ_STORAGE_VOTERS` | For a GizFS node: the master key, the name of the range, the key of a backup to restore, and the IDs of the nodes that vote (comma separated). | [Storage range](../operations/storage-range.md) |
| `GIZ_STORAGE_TLS_CHAIN`, `GIZ_STORAGE_TLS_KEY` | The certificate chain and the key of a GizFS node. | [Storage range](../operations/storage-range.md) |
| `GIZ_STORAGE_SCRUB_INTERVAL_MS`, `GIZ_STORAGE_SCRUB_BYTES_PER_SECOND` | How often a node reads its stored data again to find damage, and how fast. The defaults are 30 s and 8 MiB/s. | [Storage range](../operations/storage-range.md) |
| `GIZ_STORAGE_CACHE_BYTES`, `GIZ_STORAGE_NETWORK_MEMORY_BYTES` | The read cache of a node (default: part of the free space, at most 64 GiB) and the memory of its transfers in flight. | [Storage internals](../internals/storage.md) |
| `GIZ_STORAGE_EC_AFTER_MS`, `GIZ_STORAGE_GC_EXCLUSIVE` | The age at which copies become erasure-coded stripes (negative: never), and `1` to run garbage collection only with exclusive access. | [Storage internals](../internals/storage.md) |
| `GIZ_S3_ENDPOINT`, `GIZ_S3_REGION`, `GIZ_S3_ACCESS`, `GIZ_S3_SECRET` | For `giz storage s3`: the gateway, its region, and the access key and secret. | [Storage](../guides/storage.md) |
| `GIZ_S3_ENDPOINT_HOST`, `GIZ_S3_TLS_CHAIN`, `GIZ_S3_TLS_KEY`, `GIZ_S3_NATIVE_CREDENTIAL`, `GIZ_S3_CAPABILITY_KEY`, `GIZ_S3_MEASURE` | For the S3 gateway: its host name, certificate chain and key, the credential that it uses on the range, the key of its signed capabilities, and `1` to log the bytes of each operation. | [Storage internals](../internals/storage.md) |
| `GIZ_ADMIN` | The user who manages the thread of the comments example. | |

## Giz and GizStack accounts

| Variable | Effect | More |
| --- | --- | --- |
| `GIZ_TOKEN`, `GIZSTACK_TOKEN` | A token to use instead of a sign-in, for CI. | [Giz account](../guides/giz-account.md) |
| `GIZSTACK_URL` | The GizStack deployment of `giz deploy` and the AI gateway. The default is `https://gizstack.com`. | |
| `GIZ_CONFIG` | The file that keeps the sign-in. The default is `~/.config/giz/credentials.json`. | [Giz account](../guides/giz-account.md) |
| `GIZ_URL`, `GIZ_ORGANIZATION` | The Giz deployment and the organization to work in. | [Giz account](../guides/giz-account.md) |
| `GIZ_ORG` | The team of a Computer for `giz ssh-proxy`. | [Giz account](../guides/giz-account.md) |
| `GIZ_WORKER_AUTHORIZATION` | The authorization that a worker sends when it connects. | |

## Developing Gizlang

These are for a Gizlang checkout. `bin/giz` and `giz test` set most of them.

| Variable | Effect |
| --- | --- |
| `GIZLANG_ROOT`, `GIZLANG_STACK` | The checkout, and a second checkout whose `tests/` `giz test` runs with this toolchain. |
| `GIZLANG_COMPILER`, `GIZLANG_COMPILER_ID`, `GIZLANG_COMPILER_KEY`, `GIZLANG_RUNTIME_ID`, `GIZLANG_RUNTIME_ABI` | The compiler and runtime that `bin/giz` built, and the keys of the cache entries that they make. |
| `GIZLANG_BUILD_LEVEL`, `GIZLANG_RUNTIME_STATIC` | The optimization level of a run, and `1` to link the runtime statically. |
| `GIZLANG_LIVE_TESTS`, `GIZLANG_LIVE_UNITS` | `1` to run the tests of each live generation in `--fast` mode, and the units that a live host already has. |
| `GIZLANG_COLLECT`, `GIZLANG_INPUTS` | The folder that a warm-up run writes kernel sources to, and the file that notes the inputs a test observed. |
| `GIZLANG_CI` | The folder of the CI runner. The default is `~/.cache/gizlang-ci`. |
| `GIZLANG_SLOT`, `GIZLANG_SLOT_CLASS`, `GIZLANG_SLOTS`, `GIZLANG_SLOTS_DIR`, `GIZLANG_SLOTS_CONFIG` | The build slots: the slot of this run, its class, the local slot count, the slot folder, and the file of remote build hosts. |
| `GIZLANG_CAPS`, `GIZLANG_NEEDS_GROUP`, `GIZLANG_EXECUTION_SLICE`, `GIZLANG_MEMORY_MAX` | The capabilities of the test host, the `needs` sets of one part of a split run, the systemd slice and the memory limit of a test. |
| `GIZLANG_FARM_SPOOL`, `GIZLANG_FARM_SLOTS`, `GIZLANG_FARM_RUN`, `GIZLANG_FARM_SHIPS`, `GIZLANG_FARM_MIN_SECONDS` | Tests that run on other hosts: the spool, its lanes, a run on a farm host, the data paths that it gets, and the shortest suite that goes there. |
| `GIZLANG_BROWSER` | The Chromium that browser tests drive. The default is the newest headless shell in `~/.cache/ms-playwright`. |
| `GIZLANG_BENCH_SUITES`, `GIZLANG_BENCH_RESULTS`, `GIZLANG_BENCH_RECORD`, `GIZLANG_BENCH_BUILD`, `GIZLANG_CLI` | Benchmarks: the suites folder, the results folder, a folder to record raw runs, the build being measured, and the `giz` command to run. |

Settings

Gizlang has no configuration file of its own. A program, a library or the giz command reads the settings below from the environment. A project's own settings are in its package.json (the manifest).

The docs suite (tests/docs) fails when the code reads a variable that this page does not list.

Install and toolchain

Variable	Effect	More
`GIZ_INSTALL`, `GIZDB_INSTALL`	The folder that the install script installs into. The defaults are `~/.giz` and `~/.gizdb`.	Start
`GIZ_VERSION`	The toolchain version that runs this command. It takes precedence over `gizlang.version` of `package.json`.	Start
`GIZ_ACCESS_TOKEN`	The access token of the gizstack.com preview, for the installer, `giz upgrade` and package reads. The default is the file `~/.config/gizstack/access-token`. It is sent to gizstack.com only.
`GIZ_INSTALLER`	Set by the install script: the path of the signed installer, which `giz update` runs.
`GIZ_SELF`, `GIZ_SKILLS`, `GIZ_STANDALONE`	Set by the npm launcher: its own command, the folder of its agent skill, and that no toolchain is installed yet.

Build, cache and packages

Variable	Effect	More
`GIZLANG_CACHE`	The store of compiled units, test passes, executables and fetched models. The default is `$XDG_CACHE_HOME/gizlang`, else `~/.cache/gizlang`.	Command line
`GIZLANG_CACHE_GB`	The size past which the hourly pass removes the least recently used cache files. The default is 150, at most half of the disk.	Command line
`GIZLANG_SHARED_CACHE`, `GIZLANG_TRUSTED_KEYS`	A store of units, executables and test passes that other machines built, and the Ed25519 keys whose signatures you accept.	Command line
`GIZLANG_SIGNING_KEY`	A file with a 32-byte Ed25519 seed. The machine signs what it builds with it.	Command line
`GIZLANG_STORE`, `GIZLANG_STORE_GB`	A build store that machines share (`ssh://HOST/PATH` or a folder; `off` for none), and its size in GiB (default 150).	Compiler
`GIZLANG_REGISTRY`	The package registry: a folder, or an HTTP or HTTPS URL. The default is `https://gizstack.com/packages`.	Command line
`GIZLANG_REGISTRY_TOKEN`, `GIZLANG_REGISTRY_ORG`, `GIZLANG_REGISTRY_VISIBILITY`	The bearer token, the organization and the visibility (`public` or `private`) of a remote publication.	Command line
`GIZLANG_TAILWIND`	The Tailwind compiler to run, instead of the pinned one that the cache fetches.	Markup
`GIZLANG_NODE_LIB`	The folder of Node's `lib/` for the VM, instead of the copy in the cache.	VM
`GIZLANG_CLANG`	The `clang` that compiles LLVM IR. The default is the one of the toolchain.	Tools
`GIZLANG_HOST_LLVM`	For a macOS release built on Linux: the folder of the host LLVM tools.	Tools
`GIZLANG_WINDOWS_TOOLS`	For a Windows build (`giz build --target x86_64-pc-windows-gnu`): the work folder of `tools/windows/runtime.giz`, with `llvm-mingw/` and `openssl/`.	Tools
`GIZLANG_WINDOWS_RUNTIME`	For a Windows build: the output folder of `tools/windows/runtime.giz` (the runtime archive).	Tools

Programs at run time

Variable	Effect	More
`GIZLANG_MEMORY_LIMIT`	The bytes that one World may own. The default is 80% of the memory of the machine or of its cgroup. Past it, the program faults with R011.	Runtime
`GIZLANG_THREADS`	The number of threads of parallel loops and tasks. The default is one for each CPU of the affinity and quota.	System
`GIZLANG_WORKERS`, `GIZLANG_WORKER`	`N` or `auto`: run `main` in N processes that share the listening sockets. Each worker has `GIZLANG_WORKER` set.	System
`GIZLANG_TASK_STACK`	The bytes of the stack of each task. Smaller values than the minimum are ignored.	Runtime
`GIZLANG_CPU`	`x86-64`, `v3` or `v4`: the x86-64 level that vector code runs at. The default is the highest that the CPU has.	Language
`GIZLANG_DEVICE`	`cpu`, `cuda`, `hip` or `metal`: the device of tensors and kernels.	Compute
`GIZLANG_GPU_SOURCES`	The folder that receives the source of each GPU kernel as it compiles (PTX, or LLVM IR on AMD).	Language
`GIZLANG_PROFILE`, `GIZLANG_PROFILE_HZ`	A file (`%p` is the process ID) that receives stack samples of the run, and the samples per second (default 997).	Runtime
`GIZLANG_RECORD`, `GIZLANG_REPLAY`	Set by `--record LOG` and `--replay LOG`: the log of the inputs of the run.	Command line
`GIZLANG_GC_STRESS`	Any value but `0` collects at each allocation of a Ref, to find a missing root.	Memory
`GIZLANG_ISOLATE`, `GIZLANG_ISOLATE_CODE`, `GIZLANG_HANDED`, `GIZLANG_CGROUP`	Set by a program that starts a confined child: confine it, the folder whose files it may run, the descriptors that it gets, and the cgroup that it enters.	System
`GIZLANG_IPC`, `GIZLANG_SCRIPT`	Set by the VM for a Node child process: framed IPC on its channel, and the script that a fork runs.	VM

Libraries

Variable	Effect	More
`GIZDB_PASSWORD`	The password that the GizDB server asks for. The same as `--password`.	GizDB server
`GIZDB_MODELS`, `GIZDB_MODELS_ALLOW`, `GIZDB_MODELS_LIMIT`	The models folder of SQL ML functions, the model names that may be fetched, and the bytes that they may hold.	SQL ML
`GIZ_STORAGE_NODES`, `GIZ_STORAGE_CREDENTIAL`, `GIZ_STORAGE_SITE`	For a GizFS client: the nodes of the range, the issued credential, and the site to read from first.	Storage
`GIZ_STORAGE_KEY`, `GIZ_STORAGE_HISTORY`, `GIZ_STORAGE_RESTORE_KEY`, `GIZ_STORAGE_VOTERS`	For a GizFS node: the master key, the name of the range, the key of a backup to restore, and the IDs of the nodes that vote (comma separated).	Storage range
`GIZ_STORAGE_TLS_CHAIN`, `GIZ_STORAGE_TLS_KEY`	The certificate chain and the key of a GizFS node.	Storage range
`GIZ_STORAGE_SCRUB_INTERVAL_MS`, `GIZ_STORAGE_SCRUB_BYTES_PER_SECOND`	How often a node reads its stored data again to find damage, and how fast. The defaults are 30 s and 8 MiB/s.	Storage range
`GIZ_STORAGE_CACHE_BYTES`, `GIZ_STORAGE_NETWORK_MEMORY_BYTES`	The read cache of a node (default: part of the free space, at most 64 GiB) and the memory of its transfers in flight.	Storage internals
`GIZ_STORAGE_EC_AFTER_MS`, `GIZ_STORAGE_GC_EXCLUSIVE`	The age at which copies become erasure-coded stripes (negative: never), and `1` to run garbage collection only with exclusive access.	Storage internals
`GIZ_S3_ENDPOINT`, `GIZ_S3_REGION`, `GIZ_S3_ACCESS`, `GIZ_S3_SECRET`	For `giz storage s3`: the gateway, its region, and the access key and secret.	Storage
`GIZ_S3_ENDPOINT_HOST`, `GIZ_S3_TLS_CHAIN`, `GIZ_S3_TLS_KEY`, `GIZ_S3_NATIVE_CREDENTIAL`, `GIZ_S3_CAPABILITY_KEY`, `GIZ_S3_MEASURE`	For the S3 gateway: its host name, certificate chain and key, the credential that it uses on the range, the key of its signed capabilities, and `1` to log the bytes of each operation.	Storage internals
`GIZ_ADMIN`	The user who manages the thread of the comments example.

Giz and GizStack accounts

Variable	Effect	More
`GIZ_TOKEN`, `GIZSTACK_TOKEN`	A token to use instead of a sign-in, for CI.	Giz account
`GIZSTACK_URL`	The GizStack deployment of `giz deploy` and the AI gateway. The default is `https://gizstack.com`.
`GIZ_CONFIG`	The file that keeps the sign-in. The default is `~/.config/giz/credentials.json`.	Giz account
`GIZ_URL`, `GIZ_ORGANIZATION`	The Giz deployment and the organization to work in.	Giz account
`GIZ_ORG`	The team of a Computer for `giz ssh-proxy`.	Giz account
`GIZ_WORKER_AUTHORIZATION`	The authorization that a worker sends when it connects.

Developing Gizlang

These are for a Gizlang checkout. bin/giz and giz test set most of them.

Variable	Effect
`GIZLANG_ROOT`, `GIZLANG_STACK`	The checkout, and a second checkout whose `tests/` `giz test` runs with this toolchain.
`GIZLANG_COMPILER`, `GIZLANG_COMPILER_ID`, `GIZLANG_COMPILER_KEY`, `GIZLANG_RUNTIME_ID`, `GIZLANG_RUNTIME_ABI`	The compiler and runtime that `bin/giz` built, and the keys of the cache entries that they make.
`GIZLANG_BUILD_LEVEL`, `GIZLANG_RUNTIME_STATIC`	The optimization level of a run, and `1` to link the runtime statically.
`GIZLANG_LIVE_TESTS`, `GIZLANG_LIVE_UNITS`	`1` to run the tests of each live generation in `--fast` mode, and the units that a live host already has.
`GIZLANG_COLLECT`, `GIZLANG_INPUTS`	The folder that a warm-up run writes kernel sources to, and the file that notes the inputs a test observed.
`GIZLANG_CI`	The folder of the CI runner. The default is `~/.cache/gizlang-ci`.
`GIZLANG_SLOT`, `GIZLANG_SLOT_CLASS`, `GIZLANG_SLOTS`, `GIZLANG_SLOTS_DIR`, `GIZLANG_SLOTS_CONFIG`	The build slots: the slot of this run, its class, the local slot count, the slot folder, and the file of remote build hosts.
`GIZLANG_CAPS`, `GIZLANG_NEEDS_GROUP`, `GIZLANG_EXECUTION_SLICE`, `GIZLANG_MEMORY_MAX`	The capabilities of the test host, the `needs` sets of one part of a split run, the systemd slice and the memory limit of a test.
`GIZLANG_FARM_SPOOL`, `GIZLANG_FARM_SLOTS`, `GIZLANG_FARM_RUN`, `GIZLANG_FARM_SHIPS`, `GIZLANG_FARM_MIN_SECONDS`	Tests that run on other hosts: the spool, its lanes, a run on a farm host, the data paths that it gets, and the shortest suite that goes there.
`GIZLANG_BROWSER`	The Chromium that browser tests drive. The default is the newest headless shell in `~/.cache/ms-playwright`.
`GIZLANG_BENCH_SUITES`, `GIZLANG_BENCH_RESULTS`, `GIZLANG_BENCH_RECORD`, `GIZLANG_BENCH_BUILD`, `GIZLANG_CLI`	Benchmarks: the suites folder, the results folder, a folder to record raw runs, the build being measured, and the `giz` command to run.